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 通道这一设计让音频数据的吞吐不受控制指令的干扰控制 WebSocket默认ws://127.0.0.1:8011用于收发控制命令例如设置录音器参数、读取参数值、调用录音器方法set_microphone、abort、stop、clear_audio_queue、wakeup等。数据 WebSocket默认ws://127.0.0.1:8012用于上行传输音频数据二进制帧并向所有已连接客户端广播实时转写结果与录音事件文本帧。从 stt_server.py 的main_async()可以看到服务端同时启动两个websockets.serve监听器并通过broadcast_audio_messages()协程把录音器回调产生的 JSON 消息广播给所有数据通道客户端——这意味着多个客户端可以同时订阅同一份转写结果非常适合会议纪要、多屏展示等一对多场景。在服务端内部AudioToTextRecorder运行在一个独立线程_recorder_thread中麦克风被关闭use_microphoneFalse音频完全由数据通道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_requires3.11因此建议使用 Python 3.11 或更高版本。安装 RealtimeSTT包含RealtimeSTT_server包及其stt-server、stt命令入口见 setup.pypip 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-server3.1 启动服务端stt-server [OPTIONS]服务端初始化后会在指定端口监听 WebSocket 连接。最简单的启动方式stt-server此时默认加载large-v2主模型与tiny.en实时模型监听控制端口8011、数据端口8012语言为英语。一个精简的典型启动示例换用小模型、指定语言、改端口stt-server -m small.en -l en -c 9001 -d 90023.2 服务端参数全表以下参数均可在启动时通过命令行指定其定义与默认值可在 stt_server.py 的parse_arguments()中核对模型与语言参数类型默认值说明-m,--modelstrlarge-v2主转写模型路径或模型规格可选tiny、tiny.en、base、base.en、small、small.en、medium、medium.en、large-v1、large-v2或任意 HuggingFace CTranslate2 STT 模型如deepdml/faster-whisper-large-v3-turbo-ct2-r,--rt-model,--realtime_model_typestrtiny.en实时转写模型规格仅当启用实时转写--enable_realtime_transcription时生效-l,--lang,--languagestren转写语言代码留空则根据输入音频自动检测-b,--batch,--batch_sizeint16推理批大小控制并行处理的音频块数量--root,--download_rootstrNoneWhisper 模型下载根目录--compute_typestrdefaultCTranslate2 计算类型量化方式可参考 CTranslate2 量化文档--gpu_device_indexint0使用的 GPU 设备索引--devicestrcuda计算设备cuda或cpu音频输入与端口参数类型默认值说明-i,--input-device,--input_device_indexint1音频输入设备索引服务端本身不采集麦克风该值会透传给录音器配置-c,--control,--control_portint8011控制 WebSocket 端口-d,--data,--data_portint8012数据 WebSocket 端口VAD 与静音检测参数类型默认值说明--silero_sensitivityfloat0.05Silero VAD 灵敏度范围0~1值越低越不敏感适合嘈杂环境--silero_use_onnxstore_trueFalse使用 Silero ONNX 版本更快且资源占用更低--webrtc_sensitivityint3WebRTC VAD 灵敏度范围0~3值越高越不敏感适合干净环境--silero_deactivity_detectionstore_trueTrue使用 Silero 模型做说话结束检测嘈杂环境更稳健但更耗 GPU 资源--deactivity_silence_confirmation_durationfloat0.16确认说话结束前需要连续 VAD 静音的秒数默认值来自 audio_recorder_client.py 的DEACTIVITY_SILENCE_CONFIRMATION_DURATION--min_length_of_recordingfloat1.1有效录音的最小时长秒过滤噪声或意外声响产生的过短片段--min_gap_between_recordingsfloat0相邻两次录音之间的最小间隔秒避免短暂静音导致录音重叠--early_transcription_on_silencefloat0.2检测到该秒数静音后提前触发转写用于句中短暂停顿应小于post_speech_silence_duration设0关闭-s,--silence_timingstore_trueTrue根据句子结构与标点动态调整话后静音时长见下文动态静音时长一节实时转写参数类型默认值说明--enable_realtime_transcriptionstore_trueTrue启用边接收边转写结果近乎实时下发--realtime_processing_pausefloat0.02处理音频块的时间间隔秒越小响应越快、CPU 负载越高--init_realtime_after_secondsfloat0.2会话开始后延迟启动实时转写的秒数避免开场误判--realtime_batch_sizeint16实时转写模型批大小--beam_sizeint5主模型 beam 大小越大越准、越慢--beam_size_realtimeint3实时模型 beam 大小越小越快、精度略降--initial_promptstr见下文引导主模型输出风格的初始提示词--initial_prompt_realtimestr引导实时转写模型输出风格的初始提示词--use_main_model_for_realtimestore_trueFalse用主模型替代小模型做实时转写精度更高但更慢--allowed_latency_limitint100实时队列中允许积压的最大音频块数超出则丢弃旧块--faster_whisper_vad_filterstore_trueFalse为 Faster Whisper 启用 VAD 过滤--suppress_tokensint 列表[-1]转写时抑制的 token 列表--handle_buffer_overflowstore_trueFalse转写期间处理缓冲区溢出--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转义。句子边界检测动态静音时长参数类型默认值说明--end_of_sentence_detection_pausefloat0.45被解释为句子结束的静音时长秒--unknown_sentence_detection_pausefloat0.7被解释为不完整/未知句子的停顿时长秒用于识别句子拖尾或未说完--mid_sentence_detection_pausefloat2.0被解释为句中停顿的时长秒长停顿可能只是思考而非句子结束这三者并非同时生效而是由-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。唤醒词参数类型默认值说明-w,--wake_wordsstr触发服务端开始监听的唤醒词如Jarvis--wake_words_sensitivityfloat0.5唤醒词灵敏度范围0最灵敏~1最不灵敏--wake_word_timeoutfloat5.0等待唤醒词的超时秒数超时后停止监听直到重新激活--wake_word_activation_delayfloat见下文开始监听后延迟激活唤醒检测的秒数避免会话开始的误触发--wakeword_backendstrnone唤醒词后端可指定default或自定义实现如pvporcupine、openwakeword--openwakeword_model_pathsstr可多值无OpenWakeWord 自定义模型文件路径列表--openwakeword_inference_frameworkstrtensorflowOpenWakeWord 推理框架tensorflow、pytorch等--wake_word_buffer_durationfloat1.0唤醒词检测缓冲时长秒决定唤醒前后保留多少音频版本差异提示README 将--wake_word_activation_delay默认值标注为20而仓库源码 stt_server.py 的 argparse 实际默认值为0客户端侧的初始常量同样为0.0audio_recorder_client.py。以源码为准如需防止开场误触发请显式传入较大值。调试与日志参数类型说明-D,--debugstore_true开启详细调试日志--debug_websocketsstore_true额外开启 websockets 库的调试日志-W,--writeFILEmetavar把收到的音频保存为 WAV 文件--use_extended_loggingstore_true为处理音频块的录音工作线程输出大量日志--logchunksstore_true记录收到的每个音频块用.标记四、客户端使用指南stt4.1 启动客户端stt [OPTIONS]客户端会连接服务端的控制与数据 WebSocket 地址完成实时语音转写。客户端还内置了「服务端未运行时自动拉起」的能力当--control指定的地址无法建立 WebSocket 握手时AudioToTextRecorderClient.ensure_server_running()会尝试以stt-server子进程启动服务端Windows 下用start /min cmd /cUnix 下用subprocess.Popen详见 audio_recorder_client.py。注意服务端需要先启动或保证客户端能自动拉起它再启动客户端。4.2 客户端参数全表参数类型默认值说明-i,--input-deviceintmetavarINDEX无音频输入设备索引用-L列出可用设备-l,--languagestrmetavarLANGen转写语言代码-sed,--speech-end-detectionstore_true关启用智能说话结束检测见 4.3 节-D,--debugstore_true关调试模式-n,--norealtimestore_true关关闭实时转写输出-W,--writeFILEmetavar无把录音保存为 WAV 文件-s,--setlist(PARAM,VALUE)可多次无设置一个录音器参数-m,--methodlist可多次无调用一个录音器方法可带参数-g,--getlist可多次无获取录音器参数当前值-c,--continuousstore_true关连续转写模式转完一句话不退出-L,--liststore_true关列出所有可用音频输入设备并退出--control,--control_urlstrws://127.0.0.1:8011控制 WebSocket URL--data,--data_urlstrws://127.0.0.1:8012数据 WebSocket URL4.3 speech-end-detection 专属参数仅在启用-sed/--speech-end-detection后生效用于精细化句子边界判断默认值均可在 stt_cli_client.py 核对参数类型默认值说明--post-silencefloat1.0话后静音时长秒--unknown-pausefloat1.3未知句子检测停顿秒--mid-pausefloat3.0句中停顿检测秒--end-pausefloat0.7句末检测停顿秒--hard-breakfloat3.0有背景噪声时的硬中断阈值秒--min-textsint3硬中断检测所需的最少文本条数--min-similarityfloat0.99硬中断检测的最小文本相似度--min-charsint15硬中断检测所需的最少字符数这些参数对应客户端侧的「硬中断」机制客户端维护一个 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.pycall_method{command: call_method, method: ..., args: [...], kwargs: {...}}动态调用录音器方法。出于安全考虑服务端维护了两份白名单stt_server.pyallowed_methodsset_microphone、abort、stop、clear_audio_queue、wakeup、shutdown、textallowed_parameterslanguage、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 文本帧广播给所有数据连接常用类型包括消息类型触发时机realtime实时转写更新{type: realtime, text: ...}fullSentence一句话的最终转写结果{type: fullSentence, text: ...}recording_start/recording_stop录音开始 / 结束vad_detect_start/vad_detect_stopVAD 检测开始 / 结束wakeword_detected/wakeword_detection_start/wakeword_detection_end唤醒词相关事件transcription_start转写开始附带 Base64 编码的音频字节audio_bytes_base64start_turn_detection/stop_turn_detection轮次检测开始 / 结束客户端侧的消息分发与回调映射实现在 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 stt6.2 动态设置参数# 把 Silero VAD 灵敏度设为 0.1更不敏感适合嘈杂环境 stt -s silero_sensitivity 0.16.3 动态获取参数# 读取当前 Silero 灵敏度 stt -g silero_sensitivity # 输出形如Parameter silero_sensitivity 0.16.4 调用录音器方法# 关闭静音麦克风采集 stt -m set_microphone False6.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考