RealtimeSTT v1.0.2 版本全解析流式转录引擎架构、Kroko-ONNX 与 Omnilingual ASR 集成【免费下载链接】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 官方 RELEASE_NOTES.md 为骨架系统梳理 v1.0.1 → v1.0.2 两个版本的架构演进与新增能力AudioToTextRecorder核心模块拆分、通用流式转录会话接口、Kroko-ONNX 实时预览引擎与 Meta Omnilingual ASR 引擎的接入方式以及stt-install-kroko构建助手的使用方法。读者读完可掌握新版本引擎的安装约束、配置参数、源码调用链与验证路径并据此评估自身项目的升级方案。一、版本概况一次面向「可审计架构」的演进v1.0.22026-05-31以「拆分 文档化 规范化」为主不新增引擎能力。v1.0.12026-05-20以「流式化 新引擎」为主引入流式转录会话接口、Kroko-ONNX 引擎、Omnilingual ASR 引擎与构建助手。两者叠加构成了当前仓库版本setup.py中current_version 1.0.2的核心技术面貌对外保持AudioToTextRecorder公共门面不变对内按职责拆分为可独立审计的模块同时为可选转录引擎建立统一的同步 流式双通道抽象。二、v1.0.2AudioToTextRecorder核心模块拆分2.1 拆分动机与结果v1.0.2 将原本集中于单个类实现的功能拆解到RealtimeSTT/core/下的聚焦模块中分别负责生命周期lifecycle.py录音启动、停止、语音活动监听、唤醒等外部可见行为录音与缓冲recording.py、recording_buffers.py音频帧采集与队列管理实时转录realtime.py实时工作线程与流式会话调度语音活动voice_activity.py、silero_vad.pyVAD 后端与边界检测唤醒词wakeword.py唤醒词后端加载与参数归一化初始化与关闭initialization.py、shutdown.py资源装配与释放格式化text_formatting.py大小写、句号等输出后处理。公共门面 audio_recorder.py 仅保留AudioToTextRecorder类的公开 API 与兼容常量如INIT_MODEL_TRANSCRIPTION tiny、INIT_REALTIME_PROCESSING_PAUSE 0.2、INIT_POST_SPEECH_SILENCE_DURATION 0.6并通过from .core.xxx import ...组合各模块能力。这一拆分的直接收益正如发布说明所述公共门面、线程边界与回归检查都更容易审计——每个关注点对应一个可独立阅读、独立测试的模块。2.2 工程规范化细节包内 docstring 与注释统一为块式摘要block-style summaries并聚焦运行时解释便于文档生成工具与 IDE 悬停提示移除了audio_recorder.py中未使用的内部控制台颜色辅助函数Removed条目属于纯粹的清理型变更不影响公共 API。三、v1.0.1通用流式转录会话接口3.1 接口设计v1.0.1 在 base.py 中新增了抽象基类StreamingTranscriptionSession定义了流式解码的六个方法方法职责reset()为新一轮话语重置会话状态accept_audio(audio, sample_rateNone)接收一段新音频块decode()执行已接收音频的待处理解码get_result()返回当前部分/最终转录结果TranscriptionResultfinish()收尾当前话语并返回最终结果默认实现为decode()get_result()close()释放会话资源配套的BaseTranscriptionEngine默认supports_streaming False其create_streaming_session()默认抛错只有明确声明supports_streaming True的引擎才能接入流式实时通道其余引擎保持「整段缓冲后一次性转录」的旧有回退行为从而做到增量能力与兼容性并存。3.2 实时工作线程中的流式调度实时工作线程 realtime.py 是流式会话的消费方其调度逻辑可从源码结构确认_streaming_realtime_target()检查实时转录模型是否具备supports_streaming与create_streaming_session_ensure_streaming_session(recording_id)为每个录音会话维护一个持久流式会话录音切换时先_finish_streaming_session()收尾再新建_transcribe_with_realtime_streaming_model()只把「本次快照相对上次的新增帧」通过session.accept_audio()喂入再decode()并get_result()这正是发布说明中「只把新录制音频帧送入持久会话」的实现位置录音结束时由_finish_streaming_session()补喂尾部剩余帧并调用finish()。此外工作线程内置多重触发机制定时器触发realtime_processing_pause默认 0.2 秒、音节边界触发realtime_boundary_followup_delays默认(0.05, 0.2)触发原因包括syllable-boundary、syllable-boundary-followup、syllable-boundary-fallback并会跳过小于 50ms 的过小缓冲以避免把初始空缓冲送入模型。四、Kroko-ONNX 引擎面向流式的实时预览4.1 引擎身份与懒加载kroko_onnx适配 Kroko/Banafo 流式.data模型适配器在 kroko_onnx_engine.py 中实现采用懒加载普通安装与测试不依赖该运行时只有显式选择该引擎时才导入。在 factory.py 中注册了三个可用引擎名kroko_onnx、kroko、banafo_kroko连字符形式kroko-onnx、banafo-kroko经统一归一化后同样可用。引擎类声明supports_streaming True并提供KrokoOnnxStreamingSession实现流式会话。4.2 安装与构建Kroko-ONNX 不随默认安装附带需通过构建助手安装pip install RealtimeSTT[kroko-builder,silero-onnx-cpu] stt-install-kroko --buildkroko-builderextra 仅引入huggingface_hub见 setup.py用于模型下载与构建流程silero-onnx-cpu提供本地 VAD 后端供基于AudioToTextRecorder的 smoke 测试与真实麦克风使用构建 Kroko 本身不需要它Windows 侧要求 Python 3.12 x64、Git以及正在运行的 Docker DesktopWSL2 后端验证方式为docker version必须同时输出 Client 与 Server 两段Linux 侧要求 Git、CMake 与可用的 C/C 工具链若默认构建缓存不可写助手会自动回退到项目本地kroko-builder-work目录也可显式指定stt-install-kroko --build --work-dir .\kroko-builder-work。从 install_kroko.py 的源码可以看到完整 CLI 参数--build、--variant {free,pro}默认freepro时 Linux 构建会注入KROKO_LICENSEON、--repo、--branch默认上游cross-platform-builds分支、--work-dir、--force、--skip-install。构建完成后可下载公开社区模型from huggingface_hub import hf_hub_download hf_hub_download(repo_idBanafo/Kroko-ASR, filenameKroko-EN-Community-64-L-Streaming-001.data, local_dirtest-model-cache/kroko-onnx)4.3 模型路径解析与自动下载模型解析优先级可从 kroko_onnx_engine.py 的_resolve_model_path()推断engine_options[model_path]/[model_file]显式指定engine_options[model_dir]目录含单个.data文件或配合model_filename回退到config.model裸文件名以Kroko-开头且以.data结尾默认缓存到~/.cache/realtimestt/kroko-onnx也可用download_root重定向。已知公开社区模型Kroko-EN-Community-64-L-Streaming-001.data与128-L变体在auto_download_model别名download_model默认True开启时自动下载私有/Pro 模型则需提供model_download_url、Hugging Face repo/token 或已存在的.data文件路径。4.4 实时预览与模型节奏cadence最终转录仍是一次性整段调用one-shot流式路径仅在实时引擎声明支持流式时用于实时预览。模型文件名编码原生流式节奏数字 × 20ms。即16≈ 320ms、32≈ 640ms、64≈ 1280ms。喂入更小的分块不会迫使 Kroko 更快产出部分结果只是避免额外的调度与缓冲延迟。Kroko-EN-Pro-16-L被标注为可获得最快部分结果的推荐实时模型但发布说明同时强调确切的节奏取决于运行时、提供方、硬件与调度且「本地私有验证观察到符合预期的低延迟部分结果行为」——属于谨慎的经验性结论而非承诺指标。尾部填充tail_padding_seconds/finalization_padding_seconds默认auto从模型路径推断chunk_seconds取max(0.66, chunk_seconds 0.1)常量KROKO_ONNX_FALLBACK_TAIL_PADDING_SECONDS 0.66、KROKO_ONNX_TAIL_PADDING_MARGIN_SECONDS 0.1见源码顶部用于一次性解码前的静音补帧。4.5 配置参数表结合 docs/engines/kroko-onnx.md 与源码中_recognizer_kwargs()的默认值核心选项如下选项含义默认值model_path/model_file显式.data模型文件覆盖modelmodel_dir/model_filename模型目录与目录内文件名auto_download_model/download_model自动下载缺失的公开社区模型默认Truemodel_download_url直接下载 URL适合 Pro/私有模型model_repo_id、model_revision、hf_tokenHugging Face 下载设置key/referralcodePro 模型许可密钥 / 可选推荐码providercpu/cuda/coreml默认由device推导cuda*→cuda否则cpunum_threads运行时线程数默认1sample_rate识别采样率默认16000feature_dim特征维度默认80decoding_methodgreedy_search或modified_beam_searchmax_active_paths改进束搜索路径数默认4hotwords_file/hotwords_score热词偏置输入默认分1.5blank_penalty解码时空白符号惩罚默认0.0enable_endpoint_detection端点检测开关默认Truerule1_min_trailing_silence/rule2_min_trailing_silence/rule3_min_utterance_length端点规则默认2.4/1.2/20.0秒tail_padding_seconds/finalization_padding_seconds一次性解码前尾部静音填充默认autosuppress_native_output抑制原生 stdout/stderr 并设置KROKO_ONNX_SUPPRESS_LICENSE_OUTPUT1别名suppress_output、quiet、silentrecognizer额外字典合并进OnlineRecognizer.from_transducer(...)需要特别说明suppress_native_output的双层机制Python 侧在识别调用期间将 fd 1/2 重定向到os.devnull同时设置环境变量但异步 Pro 许可刷新消息如Remaining seconds updated: ...的可靠抑制需要基于 RealtimeSTT 原生静音补丁重建的 Kroko wheel旧版 wheel 仍可能打印后台许可状态文本。4.6 使用示例from RealtimeSTT import AudioToTextRecorder recorder AudioToTextRecorder( transcription_enginekroko_onnx, modelKroko-EN-Community-128-L-Streaming-001.data, devicecpu, languageen, enable_realtime_transcriptionTrue, realtime_transcription_enginekroko_onnx, realtime_model_typeKroko-EN-Pro-16-L-Streaming-001.data, realtime_transcription_engine_options{ provider: cpu, num_threads: 4, key: ..., suppress_native_output: True, }, )五、Omnilingual ASR 引擎Linux/WSL2 专属的多语言转录5.1 平台约束与安装omnilingual_asr通过ASRInferencePipeline适配 Meta Omnilingual ASR实现见 omnilingual_asr_engine.py同样是懒加载的可选引擎。平台约束非常明确仅 Linux / WSL2 Python 3.11.x原生 Windows 不受支持因为fairseq2n没有 Windows wheelPython 3.12.x 被上游omnilingual-asr包的元数据阻断omnilingual-asr0.2.0声明Requires-Python: 3.12,3.10导致常规 3.12 patch 版本无法解析依赖。安装命令pip install RealtimeSTT[omnilingual]setup.py 中该 extra 带非 Windows 平台标记并约束omnilingual-asr0.2.0、torch2.8.0、torchaudio2.8.0。注意若自行安装 CUDA 版 PyTorch须保持 torch/torchaudio 版本配对否则可能出现python -m pip check通过但导入时报缺libcudart.so的错误。可用引擎名factory.pyomnilingual_asr、omnilingual、meta_omnilingual_asr、omni_asr。5.2 模型卡与默认选择当model仍为 RealtimeSTT 默认 Whisper 名tiny/tiny.en等见源码_WHISPER_DEFAULT_MODEL_NAMES时适配器自动选择omniASR_CTC_1B_v2作为默认transcription_engine_options[model_card]可显式覆盖model源码维护了完整的 v2 模型卡清单KNOWN_OMNILINGUAL_ASR_MODELS覆盖 300M/1B/3B/7B 的 CTC 与 LLM 家族以及omniASR_LLM_Unlimited_*_v2系列遇到ModelNotKnownError尤其_v2卡片时适配器不会静默回退到旧的非 v2 卡片而是提示升级到携带该卡片的omnilingual-asr0.2.0版本omniASR_CTC_1B_v2被标注为推荐起点比 300M 卡需要更多显存与启动时间但它是本集成通过验证的默认。5.3 语言处理与音频输入CTC 模型卡忽略语言适配器在调用管线前移除lang参数LLM 模型卡可接受 Omnilingual 语言 ID如eng_Latn常用短码en、de、es、fr、zh等通过内置_LANGUAGE_ALIASES映射为完整 ID也可用transcription_engine_options[language_aliases]扩充内存音频以预解码波形字典传入{waveform: waveform_np, sample_rate: sample_rate}避免上游包把原始 NumPy float 数组误当作编码音频字节处理内置时长守卫max_audio_seconds默认39.9秒因为上游非流式管线要求音频短于 40 秒可设为false关闭。5.4 配置参数表选项含义默认值modelOmnilingual 模型卡transcription_engine_options[model_card]覆盖modeldevice传入ASRInferencePipelinecuda会结合gpu_device_index变成cuda:Ncompute_type映射为 torch dtypeCUDA 默认 FP16、CPU 默认 FP32transcription_engine_options[dtype]/[torch_dtype]显式 dtype 字符串float16、bfloat16、float32或torch.*形式transcription_engine_options[sample_rate]内存音频采样率默认 16000batch_size全局batch_size 0时使用否则默认 1引擎选项可覆盖transcription_engine_options[pipeline]透传给ASRInferencePipeline的额外关键字transcription_engine_options[transcribe]透传给pipeline.transcribe(...)的额外关键字transcription_engine_options[max_audio_seconds]时长守卫默认 39.9false关闭transcription_engine_options[language]/[lang]未显式传language时的默认语言transcription_engine_options[language_aliases]额外短码 → Omnilingual ID 映射5.5 使用示例from RealtimeSTT import AudioToTextRecorder # CTC 模型忽略语言 recorder AudioToTextRecorder( transcription_engineomnilingual_asr, modelomniASR_CTC_1B_v2, devicecuda, compute_typefloat16, enable_realtime_transcriptionTrue, realtime_transcription_engineomnilingual_asr, realtime_model_typeomniASR_CTC_1B_v2, use_main_model_for_realtimeTrue, # 共享单一模型节省显存 )实时场景建议用use_main_model_for_realtimeTrue保持单一模型驻留内存这是最安全的显存起步配置但最终转录与实时请求会争用同一模型若改为双模型需先验证显存余量。六、文档与验证体系6.1 新增文档v1.0.1 新增 docs/licenses.md集中记录各引擎与模型家族的许可注意事项帮助使用者在引入 Pro/私有模型前核对许可边界。发布说明还特别给出安全提醒不要把密钥、Pro 模型、生成的日志、本地 wheel 或缓存内容提交进仓库密钥应通过配置、CLI 或环境变量在运行时注入。6.2 测试与回归快速契约测试使用假运行时对象fake Kroko/Omnilingual 对象不依赖可选依赖即可运行例如python -m unittest -v tests.unit.test_kroko_onnx_engine与tests.unit.test_omnilingual_asr_engine真实模型 smoke 测试需要完整运行时Kroko 通过环境变量如REALTIMESTT_RUN_KROKO_ONNX1、REALTIMESTT_KROKO_ONNX_MODEL、REALTIMESTT_KROKO_ONNX_PROVIDER触发Omnilingual 通过 tests/realtimestt_omnilingual_test.py 的--file-smoke --device cuda模式以 LJ Speech 夹具tests/unit/audio/LJ001-0002.wav验证识别文本应包含in being模型资产可达数 GiB 量级公开的手动 smoke 脚本 tests/realtimestt_kroko_test.py 提供--init-only模式仅构造AudioToTextRecorder以验证 Kroko VAD 后端装配是否成功需rich与silero-onnx-cpu许可证密钥可通过REALTIMESTT_KROKO_ONNX_KEY、KROKO_ONNX_KEY或KROKO_KEY环境变量注入用于 Pro-only 检查但须避免进入提交文件、shell 日志与生成的报告。6.3 FastAPI 参考用法仓库内 example_fastapi_server/server.py 可作为服务化验证入口该参考应用仅存在于源码树不随 PyPI wheel 安装。Kroko 与 Omnilingual 两个引擎均可通过--engine、--realtime-engine、--engine-options等参数配置Omnilingual 场景需在 WSL2/Linux 下运行例如PYTHONPATH. python example_fastapi_server/server.py --engine omnilingual_asr --model omniASR_CTC_1B_v2 --realtime-engine omnilingual_asr --realtime-model omniASR_CTC_1B_v2 --use-main-model-for-realtime --device cuda --compute-type float16 --realtime-processing-pause 0.05。七、升级建议与注意事项小结API 兼容性两次发布均保持AudioToTextRecorder公共门面不变升级以增量能力为主1.0.2 的模块拆分是内部实现细节但如果你依赖内部私有属性仍需按 module-map.md 之类的架构文档核对。流式引擎的适用条件实时预览走流式路径的前提是引擎声明supports_streaming目前仓库中 Kroko-ONNX 是代表其余引擎维持整段缓冲回退因此「是否获得增量部分结果」取决于所选引擎。平台硬约束Kroko-ONNX 的 Windows 构建限定 Python 3.12 x64 Docker DesktopOmnilingual 限定 Linux/WSL2 Python 3.11.x。两者均属可选依赖未安装时普通 RealtimeSTT 使用不受影响。许可与安全Pro 模型密钥、模型文件、日志与缓存一律不应入库密钥运行时注入。验证先行先跑不依赖真实模型的契约测试再跑带真实模型的 smoke 测试最后才进入服务化部署可快速定位「依赖缺失 / 模型缺失 / 运行时不匹配」三类常见故障。总体而言v1.0.2 为 RealtimeSTT 建立了更清晰的可审计架构而 v1.0.1 奠定的流式会话接口与两个高性能可选引擎则为低延迟实时转录场景提供了从「整段转录」迈向「增量解码」的落地路径。如需在自有项目中复用这些能力可结合 docs/engines/kroko-onnx.md、docs/engines/omnilingual-asr.md 与 docs/configuration.md 进一步核对与自身环境匹配的参数组合。【免费下载链接】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），仅供参考 RealtimeSTT v1.0.2 版本全解析：流式转录引擎架构、Kroko-ONNX 与 Omnilingual ASR 集成
RealtimeSTT v1.0.2 版本全解析流式转录引擎架构、Kroko-ONNX 与 Omnilingual ASR 集成【免费下载链接】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 官方 RELEASE_NOTES.md 为骨架系统梳理 v1.0.1 → v1.0.2 两个版本的架构演进与新增能力AudioToTextRecorder核心模块拆分、通用流式转录会话接口、Kroko-ONNX 实时预览引擎与 Meta Omnilingual ASR 引擎的接入方式以及stt-install-kroko构建助手的使用方法。读者读完可掌握新版本引擎的安装约束、配置参数、源码调用链与验证路径并据此评估自身项目的升级方案。一、版本概况一次面向「可审计架构」的演进v1.0.22026-05-31以「拆分 文档化 规范化」为主不新增引擎能力。v1.0.12026-05-20以「流式化 新引擎」为主引入流式转录会话接口、Kroko-ONNX 引擎、Omnilingual ASR 引擎与构建助手。两者叠加构成了当前仓库版本setup.py中current_version 1.0.2的核心技术面貌对外保持AudioToTextRecorder公共门面不变对内按职责拆分为可独立审计的模块同时为可选转录引擎建立统一的同步 流式双通道抽象。二、v1.0.2AudioToTextRecorder核心模块拆分2.1 拆分动机与结果v1.0.2 将原本集中于单个类实现的功能拆解到RealtimeSTT/core/下的聚焦模块中分别负责生命周期lifecycle.py录音启动、停止、语音活动监听、唤醒等外部可见行为录音与缓冲recording.py、recording_buffers.py音频帧采集与队列管理实时转录realtime.py实时工作线程与流式会话调度语音活动voice_activity.py、silero_vad.pyVAD 后端与边界检测唤醒词wakeword.py唤醒词后端加载与参数归一化初始化与关闭initialization.py、shutdown.py资源装配与释放格式化text_formatting.py大小写、句号等输出后处理。公共门面 audio_recorder.py 仅保留AudioToTextRecorder类的公开 API 与兼容常量如INIT_MODEL_TRANSCRIPTION tiny、INIT_REALTIME_PROCESSING_PAUSE 0.2、INIT_POST_SPEECH_SILENCE_DURATION 0.6并通过from .core.xxx import ...组合各模块能力。这一拆分的直接收益正如发布说明所述公共门面、线程边界与回归检查都更容易审计——每个关注点对应一个可独立阅读、独立测试的模块。2.2 工程规范化细节包内 docstring 与注释统一为块式摘要block-style summaries并聚焦运行时解释便于文档生成工具与 IDE 悬停提示移除了audio_recorder.py中未使用的内部控制台颜色辅助函数Removed条目属于纯粹的清理型变更不影响公共 API。三、v1.0.1通用流式转录会话接口3.1 接口设计v1.0.1 在 base.py 中新增了抽象基类StreamingTranscriptionSession定义了流式解码的六个方法方法职责reset()为新一轮话语重置会话状态accept_audio(audio, sample_rateNone)接收一段新音频块decode()执行已接收音频的待处理解码get_result()返回当前部分/最终转录结果TranscriptionResultfinish()收尾当前话语并返回最终结果默认实现为decode()get_result()close()释放会话资源配套的BaseTranscriptionEngine默认supports_streaming False其create_streaming_session()默认抛错只有明确声明supports_streaming True的引擎才能接入流式实时通道其余引擎保持「整段缓冲后一次性转录」的旧有回退行为从而做到增量能力与兼容性并存。3.2 实时工作线程中的流式调度实时工作线程 realtime.py 是流式会话的消费方其调度逻辑可从源码结构确认_streaming_realtime_target()检查实时转录模型是否具备supports_streaming与create_streaming_session_ensure_streaming_session(recording_id)为每个录音会话维护一个持久流式会话录音切换时先_finish_streaming_session()收尾再新建_transcribe_with_realtime_streaming_model()只把「本次快照相对上次的新增帧」通过session.accept_audio()喂入再decode()并get_result()这正是发布说明中「只把新录制音频帧送入持久会话」的实现位置录音结束时由_finish_streaming_session()补喂尾部剩余帧并调用finish()。此外工作线程内置多重触发机制定时器触发realtime_processing_pause默认 0.2 秒、音节边界触发realtime_boundary_followup_delays默认(0.05, 0.2)触发原因包括syllable-boundary、syllable-boundary-followup、syllable-boundary-fallback并会跳过小于 50ms 的过小缓冲以避免把初始空缓冲送入模型。四、Kroko-ONNX 引擎面向流式的实时预览4.1 引擎身份与懒加载kroko_onnx适配 Kroko/Banafo 流式.data模型适配器在 kroko_onnx_engine.py 中实现采用懒加载普通安装与测试不依赖该运行时只有显式选择该引擎时才导入。在 factory.py 中注册了三个可用引擎名kroko_onnx、kroko、banafo_kroko连字符形式kroko-onnx、banafo-kroko经统一归一化后同样可用。引擎类声明supports_streaming True并提供KrokoOnnxStreamingSession实现流式会话。4.2 安装与构建Kroko-ONNX 不随默认安装附带需通过构建助手安装pip install RealtimeSTT[kroko-builder,silero-onnx-cpu] stt-install-kroko --buildkroko-builderextra 仅引入huggingface_hub见 setup.py用于模型下载与构建流程silero-onnx-cpu提供本地 VAD 后端供基于AudioToTextRecorder的 smoke 测试与真实麦克风使用构建 Kroko 本身不需要它Windows 侧要求 Python 3.12 x64、Git以及正在运行的 Docker DesktopWSL2 后端验证方式为docker version必须同时输出 Client 与 Server 两段Linux 侧要求 Git、CMake 与可用的 C/C 工具链若默认构建缓存不可写助手会自动回退到项目本地kroko-builder-work目录也可显式指定stt-install-kroko --build --work-dir .\kroko-builder-work。从 install_kroko.py 的源码可以看到完整 CLI 参数--build、--variant {free,pro}默认freepro时 Linux 构建会注入KROKO_LICENSEON、--repo、--branch默认上游cross-platform-builds分支、--work-dir、--force、--skip-install。构建完成后可下载公开社区模型from huggingface_hub import hf_hub_download hf_hub_download(repo_idBanafo/Kroko-ASR, filenameKroko-EN-Community-64-L-Streaming-001.data, local_dirtest-model-cache/kroko-onnx)4.3 模型路径解析与自动下载模型解析优先级可从 kroko_onnx_engine.py 的_resolve_model_path()推断engine_options[model_path]/[model_file]显式指定engine_options[model_dir]目录含单个.data文件或配合model_filename回退到config.model裸文件名以Kroko-开头且以.data结尾默认缓存到~/.cache/realtimestt/kroko-onnx也可用download_root重定向。已知公开社区模型Kroko-EN-Community-64-L-Streaming-001.data与128-L变体在auto_download_model别名download_model默认True开启时自动下载私有/Pro 模型则需提供model_download_url、Hugging Face repo/token 或已存在的.data文件路径。4.4 实时预览与模型节奏cadence最终转录仍是一次性整段调用one-shot流式路径仅在实时引擎声明支持流式时用于实时预览。模型文件名编码原生流式节奏数字 × 20ms。即16≈ 320ms、32≈ 640ms、64≈ 1280ms。喂入更小的分块不会迫使 Kroko 更快产出部分结果只是避免额外的调度与缓冲延迟。Kroko-EN-Pro-16-L被标注为可获得最快部分结果的推荐实时模型但发布说明同时强调确切的节奏取决于运行时、提供方、硬件与调度且「本地私有验证观察到符合预期的低延迟部分结果行为」——属于谨慎的经验性结论而非承诺指标。尾部填充tail_padding_seconds/finalization_padding_seconds默认auto从模型路径推断chunk_seconds取max(0.66, chunk_seconds 0.1)常量KROKO_ONNX_FALLBACK_TAIL_PADDING_SECONDS 0.66、KROKO_ONNX_TAIL_PADDING_MARGIN_SECONDS 0.1见源码顶部用于一次性解码前的静音补帧。4.5 配置参数表结合 docs/engines/kroko-onnx.md 与源码中_recognizer_kwargs()的默认值核心选项如下选项含义默认值model_path/model_file显式.data模型文件覆盖modelmodel_dir/model_filename模型目录与目录内文件名auto_download_model/download_model自动下载缺失的公开社区模型默认Truemodel_download_url直接下载 URL适合 Pro/私有模型model_repo_id、model_revision、hf_tokenHugging Face 下载设置key/referralcodePro 模型许可密钥 / 可选推荐码providercpu/cuda/coreml默认由device推导cuda*→cuda否则cpunum_threads运行时线程数默认1sample_rate识别采样率默认16000feature_dim特征维度默认80decoding_methodgreedy_search或modified_beam_searchmax_active_paths改进束搜索路径数默认4hotwords_file/hotwords_score热词偏置输入默认分1.5blank_penalty解码时空白符号惩罚默认0.0enable_endpoint_detection端点检测开关默认Truerule1_min_trailing_silence/rule2_min_trailing_silence/rule3_min_utterance_length端点规则默认2.4/1.2/20.0秒tail_padding_seconds/finalization_padding_seconds一次性解码前尾部静音填充默认autosuppress_native_output抑制原生 stdout/stderr 并设置KROKO_ONNX_SUPPRESS_LICENSE_OUTPUT1别名suppress_output、quiet、silentrecognizer额外字典合并进OnlineRecognizer.from_transducer(...)需要特别说明suppress_native_output的双层机制Python 侧在识别调用期间将 fd 1/2 重定向到os.devnull同时设置环境变量但异步 Pro 许可刷新消息如Remaining seconds updated: ...的可靠抑制需要基于 RealtimeSTT 原生静音补丁重建的 Kroko wheel旧版 wheel 仍可能打印后台许可状态文本。4.6 使用示例from RealtimeSTT import AudioToTextRecorder recorder AudioToTextRecorder( transcription_enginekroko_onnx, modelKroko-EN-Community-128-L-Streaming-001.data, devicecpu, languageen, enable_realtime_transcriptionTrue, realtime_transcription_enginekroko_onnx, realtime_model_typeKroko-EN-Pro-16-L-Streaming-001.data, realtime_transcription_engine_options{ provider: cpu, num_threads: 4, key: ..., suppress_native_output: True, }, )五、Omnilingual ASR 引擎Linux/WSL2 专属的多语言转录5.1 平台约束与安装omnilingual_asr通过ASRInferencePipeline适配 Meta Omnilingual ASR实现见 omnilingual_asr_engine.py同样是懒加载的可选引擎。平台约束非常明确仅 Linux / WSL2 Python 3.11.x原生 Windows 不受支持因为fairseq2n没有 Windows wheelPython 3.12.x 被上游omnilingual-asr包的元数据阻断omnilingual-asr0.2.0声明Requires-Python: 3.12,3.10导致常规 3.12 patch 版本无法解析依赖。安装命令pip install RealtimeSTT[omnilingual]setup.py 中该 extra 带非 Windows 平台标记并约束omnilingual-asr0.2.0、torch2.8.0、torchaudio2.8.0。注意若自行安装 CUDA 版 PyTorch须保持 torch/torchaudio 版本配对否则可能出现python -m pip check通过但导入时报缺libcudart.so的错误。可用引擎名factory.pyomnilingual_asr、omnilingual、meta_omnilingual_asr、omni_asr。5.2 模型卡与默认选择当model仍为 RealtimeSTT 默认 Whisper 名tiny/tiny.en等见源码_WHISPER_DEFAULT_MODEL_NAMES时适配器自动选择omniASR_CTC_1B_v2作为默认transcription_engine_options[model_card]可显式覆盖model源码维护了完整的 v2 模型卡清单KNOWN_OMNILINGUAL_ASR_MODELS覆盖 300M/1B/3B/7B 的 CTC 与 LLM 家族以及omniASR_LLM_Unlimited_*_v2系列遇到ModelNotKnownError尤其_v2卡片时适配器不会静默回退到旧的非 v2 卡片而是提示升级到携带该卡片的omnilingual-asr0.2.0版本omniASR_CTC_1B_v2被标注为推荐起点比 300M 卡需要更多显存与启动时间但它是本集成通过验证的默认。5.3 语言处理与音频输入CTC 模型卡忽略语言适配器在调用管线前移除lang参数LLM 模型卡可接受 Omnilingual 语言 ID如eng_Latn常用短码en、de、es、fr、zh等通过内置_LANGUAGE_ALIASES映射为完整 ID也可用transcription_engine_options[language_aliases]扩充内存音频以预解码波形字典传入{waveform: waveform_np, sample_rate: sample_rate}避免上游包把原始 NumPy float 数组误当作编码音频字节处理内置时长守卫max_audio_seconds默认39.9秒因为上游非流式管线要求音频短于 40 秒可设为false关闭。5.4 配置参数表选项含义默认值modelOmnilingual 模型卡transcription_engine_options[model_card]覆盖modeldevice传入ASRInferencePipelinecuda会结合gpu_device_index变成cuda:Ncompute_type映射为 torch dtypeCUDA 默认 FP16、CPU 默认 FP32transcription_engine_options[dtype]/[torch_dtype]显式 dtype 字符串float16、bfloat16、float32或torch.*形式transcription_engine_options[sample_rate]内存音频采样率默认 16000batch_size全局batch_size 0时使用否则默认 1引擎选项可覆盖transcription_engine_options[pipeline]透传给ASRInferencePipeline的额外关键字transcription_engine_options[transcribe]透传给pipeline.transcribe(...)的额外关键字transcription_engine_options[max_audio_seconds]时长守卫默认 39.9false关闭transcription_engine_options[language]/[lang]未显式传language时的默认语言transcription_engine_options[language_aliases]额外短码 → Omnilingual ID 映射5.5 使用示例from RealtimeSTT import AudioToTextRecorder # CTC 模型忽略语言 recorder AudioToTextRecorder( transcription_engineomnilingual_asr, modelomniASR_CTC_1B_v2, devicecuda, compute_typefloat16, enable_realtime_transcriptionTrue, realtime_transcription_engineomnilingual_asr, realtime_model_typeomniASR_CTC_1B_v2, use_main_model_for_realtimeTrue, # 共享单一模型节省显存 )实时场景建议用use_main_model_for_realtimeTrue保持单一模型驻留内存这是最安全的显存起步配置但最终转录与实时请求会争用同一模型若改为双模型需先验证显存余量。六、文档与验证体系6.1 新增文档v1.0.1 新增 docs/licenses.md集中记录各引擎与模型家族的许可注意事项帮助使用者在引入 Pro/私有模型前核对许可边界。发布说明还特别给出安全提醒不要把密钥、Pro 模型、生成的日志、本地 wheel 或缓存内容提交进仓库密钥应通过配置、CLI 或环境变量在运行时注入。6.2 测试与回归快速契约测试使用假运行时对象fake Kroko/Omnilingual 对象不依赖可选依赖即可运行例如python -m unittest -v tests.unit.test_kroko_onnx_engine与tests.unit.test_omnilingual_asr_engine真实模型 smoke 测试需要完整运行时Kroko 通过环境变量如REALTIMESTT_RUN_KROKO_ONNX1、REALTIMESTT_KROKO_ONNX_MODEL、REALTIMESTT_KROKO_ONNX_PROVIDER触发Omnilingual 通过 tests/realtimestt_omnilingual_test.py 的--file-smoke --device cuda模式以 LJ Speech 夹具tests/unit/audio/LJ001-0002.wav验证识别文本应包含in being模型资产可达数 GiB 量级公开的手动 smoke 脚本 tests/realtimestt_kroko_test.py 提供--init-only模式仅构造AudioToTextRecorder以验证 Kroko VAD 后端装配是否成功需rich与silero-onnx-cpu许可证密钥可通过REALTIMESTT_KROKO_ONNX_KEY、KROKO_ONNX_KEY或KROKO_KEY环境变量注入用于 Pro-only 检查但须避免进入提交文件、shell 日志与生成的报告。6.3 FastAPI 参考用法仓库内 example_fastapi_server/server.py 可作为服务化验证入口该参考应用仅存在于源码树不随 PyPI wheel 安装。Kroko 与 Omnilingual 两个引擎均可通过--engine、--realtime-engine、--engine-options等参数配置Omnilingual 场景需在 WSL2/Linux 下运行例如PYTHONPATH. python example_fastapi_server/server.py --engine omnilingual_asr --model omniASR_CTC_1B_v2 --realtime-engine omnilingual_asr --realtime-model omniASR_CTC_1B_v2 --use-main-model-for-realtime --device cuda --compute-type float16 --realtime-processing-pause 0.05。七、升级建议与注意事项小结API 兼容性两次发布均保持AudioToTextRecorder公共门面不变升级以增量能力为主1.0.2 的模块拆分是内部实现细节但如果你依赖内部私有属性仍需按 module-map.md 之类的架构文档核对。流式引擎的适用条件实时预览走流式路径的前提是引擎声明supports_streaming目前仓库中 Kroko-ONNX 是代表其余引擎维持整段缓冲回退因此「是否获得增量部分结果」取决于所选引擎。平台硬约束Kroko-ONNX 的 Windows 构建限定 Python 3.12 x64 Docker DesktopOmnilingual 限定 Linux/WSL2 Python 3.11.x。两者均属可选依赖未安装时普通 RealtimeSTT 使用不受影响。许可与安全Pro 模型密钥、模型文件、日志与缓存一律不应入库密钥运行时注入。验证先行先跑不依赖真实模型的契约测试再跑带真实模型的 smoke 测试最后才进入服务化部署可快速定位「依赖缺失 / 模型缺失 / 运行时不匹配」三类常见故障。总体而言v1.0.2 为 RealtimeSTT 建立了更清晰的可审计架构而 v1.0.1 奠定的流式会话接口与两个高性能可选引擎则为低延迟实时转录场景提供了从「整段转录」迈向「增量解码」的落地路径。如需在自有项目中复用这些能力可结合 docs/engines/kroko-onnx.md、docs/engines/omnilingual-asr.md 与 docs/configuration.md 进一步核对与自身环境匹配的参数组合。【免费下载链接】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），仅供参考