企业官网建设流程全解析

RealtimeSTT Server 实战指南：基于 WebSocket 的实时语音转写服务端与客户端

【免费下载链接】RealtimeSTTA robust, efficient, low-latency speech-to-text library with advanced voice activity detection, wake word activation and instant transcription.项目地址: https://gitcode.com/GitHub_Trending/re/RealtimeSTT

本文围绕仓库 RealtimeSTT_server 目录下的stt-server与stt两条 CLI 命令展开，系统讲解如何将 RealtimeSTT 库以「服务端 + 客户端」的形态部署为可远程调用的实时语音转写系统。读完本文，你将掌握双 WebSocket 通道（控制通道 + 数据通道）的通信架构、全部服务端/客户端命令行参数的语义与调优建议、通过控制命令动态设置参数与调用录音器方法，以及如何对接浏览器等自定义客户端。

一、整体架构：控制通道与数据通道分离

RealtimeSTT Server 的核心设计是「控制与数据分离」的双 WebSocket 通道，这一设计让音频数据的吞吐不受控制指令的干扰：

1. 控制 WebSocket（默认ws://127.0.0.1:8011）：用于收发控制命令，例如设置录音器参数、读取参数值、调用录音器方法（set_microphone、abort、stop、clear_audio_queue、wakeup等）。
2. 数据 WebSocket（默认ws://127.0.0.1:8012）：用于上行传输音频数据（二进制帧），并向所有已连接客户端广播实时转写结果与录音事件（文本帧）。

从 stt_server.py 的main_async()可以看到，服务端同时启动两个websockets.serve监听器，并通过broadcast_audio_messages()协程把录音器回调产生的 JSON 消息广播给所有数据通道客户端——这意味着多个客户端可以同时订阅同一份转写结果，非常适合会议纪要、多屏展示等一对多场景。

在服务端内部，AudioToTextRecorder运行在一个独立线程（_recorder_thread）中，麦克风被关闭（use_microphone=False），音频完全由数据通道feed_audio()注入；回调函数则通过make_callback(loop, callback)绑定到 asyncio 事件循环，再以asyncio.run_coroutine_threadsafe安全地投递到audio_queue，最终由广播协程统一分发，见 stt_server.py 与 stt_server.py。

二、安装与启动前置条件

原 README 要求 Python 3.8+；以仓库实际配置为准，setup.py 中声明python_requires='>=3.11'，因此建议使用 Python 3.11 或更高版本。

安装 RealtimeSTT（包含RealtimeSTT_server包及其stt-server、stt命令入口，见 setup.py）：

pip install realtimestt

如需本地默认推荐依赖（faster-whisper 转写后端 + Silero ONNX CPU VAD），可安装：

pip install "realtimestt[recommended]"

如果你已克隆本仓库，也可以直接在仓库根目录执行pip install .完成安装。服务端在启动时会通过 install_packages.py 自检RealtimeSTT、websockets、numpy、scipy等依赖，缺失时会交互式提示安装。

首次启动stt-server会自动下载 Whisper 模型权重（默认large-v2，体积较大），请确保网络可达且磁盘空间充足；也可用--model指定更小的模型以加速冷启动。

三、服务端使用指南（stt-server）

3.1 启动服务端

stt-server [OPTIONS]

服务端初始化后会在指定端口监听 WebSocket 连接。最简单的启动方式：

stt-server

此时默认加载large-v2主模型与tiny.en实时模型，监听控制端口8011、数据端口8012，语言为英语。

一个精简的典型启动示例（换用小模型、指定语言、改端口）：

stt-server -m small.en -l en -c 9001 -d 9002

3.2 服务端参数全表

以下参数均可在启动时通过命令行指定，其定义与默认值可在 stt_server.py 的parse_arguments()中核对：

模型与语言

音频输入与端口

VAD 与静音检测

实时转写

--initial_prompt的默认值为一段引导模型正确使用省略号标注未完成句子的提示：

Incomplete thoughts should end with '...'. Examples of complete thoughts: 'The sky is blue.' 'She walked home.' Examples of incomplete thoughts: 'When the sky...' 'Because he...'

源码提示：parse_arguments()会在解析后把initial_prompt/initial_prompt_realtime中的\n转义还原为真实换行（stt_server.py），因此命令行传入多行提示词时需用\\n转义。

句子边界检测（动态静音时长）

这三者并非同时生效，而是由-s/--silence_timing驱动的动态策略：在 stt_server.py 的text_detected()回调中，服务端根据实时文本的形态切换recorder.post_speech_silence_duration——文本以省略号结尾时切换为mid_sentence_detection_pause；连续两句都以句号等结束标点结尾时切换为end_of_sentence_detection_pause；其余情况使用unknown_sentence_detection_pause。

唤醒词

版本差异提示：README 将--wake_word_activation_delay默认值标注为20，而仓库源码 stt_server.py 的 argparse 实际默认值为0；客户端侧的初始常量同样为0.0（audio_recorder_client.py）。以源码为准，如需防止开场误触发请显式传入较大值。

调试与日志

四、客户端使用指南（stt）

4.1 启动客户端

stt [OPTIONS]

客户端会连接服务端的控制与数据 WebSocket 地址，完成实时语音转写。客户端还内置了「服务端未运行时自动拉起」的能力：当--control指定的地址无法建立 WebSocket 握手时，AudioToTextRecorderClient.ensure_server_running()会尝试以stt-server子进程启动服务端（Windows 下用start /min cmd /c，Unix 下用subprocess.Popen），详见 audio_recorder_client.py。

注意：服务端需要先启动（或保证客户端能自动拉起它），再启动客户端。

4.2 客户端参数全表

4.3 speech-end-detection 专属参数

仅在启用-sed/--speech-end-detection后生效，用于精细化句子边界判断（默认值均可在 stt_cli_client.py 核对）：

这些参数对应客户端侧的「硬中断」机制：客户端维护一个 3 秒窗口内的文本队列，当窗口内文本数量 ≥--min-texts、首尾文本相似度 >--min-similarity且长度 >--min-chars时，判定为背景噪声重复，主动调用client.call_method("stop")中断录音（stt_cli_client.py）。服务端text_detected()中也有完全对应的逻辑（stt_server.py）。

4.4 客户端常用示例

# 列出可用音频设备 stt -L # 指定输入设备与语言 stt -i 1 -l en # 启用智能说话结束检测并进入连续模式 stt -sed -c # 设置参数并把录音保存到文件 stt -s silero_sensitivity 0.1 -W recording.wav # 使用自定义 WebSocket 地址 stt --control ws://localhost:9001 --data ws://localhost:9002

-s的值会先尝试解析为 float，再尝试 int，失败则保留字符串（stt_cli_client.py），所以stt -s silero_sensitivity 0.1会把 0.1 作为浮点数下发。

五、WebSocket 协议细节

5.1 控制通道：JSON 文本命令

客户端通过控制连接发送 JSON 命令，服务端在 stt_server.py 的control_handler()中分发：

• set_parameter：{"command": "set_parameter", "parameter": "...", "value": ...}，执行setattr(recorder, parameter, value)，并返回{"status": "success"}或错误信息；
• get_parameter：{"command": "get_parameter", "parameter": "...", "request_id": N}，服务端回带request_id的响应，客户端据此匹配挂起的请求（超时 5 秒，见 audio_recorder_client.py）；
• call_method：{"command": "call_method", "method": "...", "args": [...], "kwargs": {...}}，动态调用录音器方法。

出于安全考虑，服务端维护了两份白名单（stt_server.py）：

• allowed_methods：set_microphone、abort、stop、clear_audio_queue、wakeup、shutdown、text；
• allowed_parameters：language、silero_sensitivity、wake_word_activation_delay、post_speech_silence_duration、deactivity_silence_confirmation_duration、listen_start、recording_stop_time、last_transcription_bytes、last_transcription_bytes_b64、speech_end_silence_start、is_recording、use_wake_words。

不在白名单中的参数或方法会被拒绝并返回错误，这防止了客户端通过控制通道任意修改内部状态。

5.2 数据通道：二进制音频帧 + 事件广播

上行（客户端 → 服务端）：每个音频帧为二进制消息，结构为4 字节小端序元数据长度 + JSON 元数据 + PCM 音频数据（组装逻辑见 audio_recorder_client.py）。元数据必须包含sampleRate字段；服务端在 stt_server.py 中解析该字段，若采样率不是 16000，则通过scipy.signal.resample重采样后再调用recorder.feed_audio()注入。

下行（服务端 → 客户端）：服务端把录音器事件序列化为 JSON 文本帧广播给所有数据连接，常用类型包括：

客户端侧的消息分发与回调映射实现在 audio_recorder_client.py 的on_data_message()中。仓库还自带一个纯前端浏览器客户端示例 RealtimeSTT_server/index.html，仅通过数据 WebSocket 接收realtime与fullSentence消息即可在网页中实时展示转写，可作为自定义客户端的参考实现。

六、端到端实战演练

6.1 默认设置启动服务端与客户端

# 终端 1：启动服务端（默认 large-v2 / tiny.en，端口 8011、8012） stt-server # 终端 2：启动客户端（默认连接 ws://127.0.0.1:8011 与 ws://127.0.0.1:8012） stt

6.2 动态设置参数

# 把 Silero VAD 灵敏度设为 0.1（更不敏感，适合嘈杂环境） stt -s silero_sensitivity 0.1

6.3 动态获取参数

# 读取当前 Silero 灵敏度 stt -g silero_sensitivity # 输出形如：Parameter silero_sensitivity = 0.1

6.4 调用录音器方法

# 关闭（静音）麦克风采集 stt -m set_microphone False

6.5 调试模式

stt -D

服务端可配合-D（含--debug_websockets）、--use_extended_logging、--logchunks观察音频块流入与转写文本的实时打印，客户端-D会输出连接建立、参数设置等详细过程。

七、常见问题排查

• 服务端无法启动：确认依赖已安装（可用pip install "realtimestt[recommended]"补齐默认后端），并确认8011/8012端口未被占用——端口冲突时服务端会打印明确的 OSError 提示（stt_server.py）。
• 没有声音 / 转写为空：用stt -L检查可用的音频输入设备，通过-i指定正确的设备索引。
• WebSocket 连接失败：核对--control/--data地址与端口是否与服务端实际监听一致；确保服务端先于客户端启动，或允许客户端自动拉起服务端。
• 首次启动慢：large-v2主模型下载与加载耗时较长，可先用-m small.en -r tiny.en验证链路，再按需升级模型。

八、许可证

RealtimeSTT 项目基于 MIT License 发布，详见 LICENSE。服务端与客户端脚本设计为无缝配合工作，在配置灵活性与转写延迟之间取得平衡，你可以根据环境噪声调节 VAD 灵敏度，也可以根据资源条件选择主模型与实时模型的大小组合。

【免费下载链接】RealtimeSTTA robust, efficient, low-latency speech-to-text library with advanced voice activity detection, wake word activation and instant transcription.项目地址: https://gitcode.com/GitHub_Trending/re/RealtimeSTT