VoiceStudio 本地跨平台流式听写（Dictation Flow）全链路指南：从 Whisper Tiny 默认到命令模式的演进路线

VoiceStudio 本地跨平台流式听写Dictation Flow全链路指南从 Whisper Tiny 默认到命令模式的演进路线【免费下载链接】VoiceStudioVoiceStudio is the open-source, fully-local ElevenLabs alternative — voice cloning, voice design, video dubbing, dictation, transcription audiobook creation in 646 languages.项目地址: https://gitcode.com/GitHub_Trending/om/VoiceStudioVoiceStudio 的听写Dictation能力把「按下全局热键 → 说话 → 文字自动插入目标应用」的完整链路完全跑在本地麦克风音频经 WebSocket 进入 sherpa-onnx 流式识别引擎实时返回 partial 与 final再由原生层还原剪贴板并插入光标所在应用。本文以仓库内设计文档 docs/specs/2026-07-16-dictation-flow-program.md 为骨架结合 backend/services/sherpa_dictation.py、backend/api/routers/capture_ws.py 等源码实现系统讲解当前已落地的听写架构、模型矩阵、分阶段演进计划、落地后的真实用法docs/features/dictation.md以及计划中的 VAD、热词词典、Wayland 插入链与命令模式等方向。读完你可掌握 VoiceStudio 听写的模型选型依据、WebSocket 流式协议、剪贴板安全机制与后续功能路线。一、为什么做本地听写定位与核心差异化语音输入正在成为 AI Agent 时代增长最快的文本输入方式但成熟的方案大多云优先、Linux 支持参差。VoiceStudio 已经具备听写所需的全部硬件紧凑的捕获悬浮窗capture pill、全局热键、sherpa-onnx 流式 WebSocket、以Whisper Tiny int8 为默认的跨平台模型、可还原的剪贴板粘贴以及本地 LLM 精修refinement。因此从设计文档看本计划的楔子定位非常明确本地local Linux/Wayland Agent 提示词agent-prompting这是一个战略性的差异化方向见 docs/specs/2026-07-16-dictation-flow-program.md 的 Why 一节。值得强调的是「本地」与「私有」整个识别链路不依赖任何云端 ASR麦克风数据只在本机处理。二、当前已落地的听写架构仓库现状设计文档的 Current state 一节逐项核对了仓库内的实现这里结合源码把现状讲清楚。2.1 前端交互层悬浮窗 全局热键悬浮窗pill基于 Tauri WebView记录期间无需键盘焦点即可工作docs/features/dictation.md。全局热键CmdOrCtrlShiftSpace支持 toggle切换/hold按住两种模式跨 macOS、Windows、X11Wayland 走 GlobalShortcuts 桌面 portal另有浏览器模式下的键盘回退。前端逻辑见 frontend/src/utils/dictationShortcut.jsRust 侧热键管理器见 frontend/src-tauri/src/dictation_shortcut.rs。采集getUserMedia采集 16 kHz 原始 PCM经 WebSocket/ws/transcribe上行在 WebView 不支持 MediaRecorder 的场景?pcm1sr16000是免容器的回退通道。2.2 目标捕获与剪贴板安全原生会话原生层在悬浮窗出现之前就捕获目标窗口捕获目标在 shortcut-down 时刻完成会话 ID 贯穿 partial/utterance/summary 所有消息旧会话的迟到结果不能使用新会话的目标避免结果插入错窗口。macOS/Windows/X11 在插入前校验并重新激活目标进程/窗口Wayland 由于没有可移植的目标身份标识安全默认是把完整转写结果留在剪贴板除非用户显式开启VOICESTUDIO_WAYLAND_UNTARGETED_INSERT1见 docs/features/dictation.md 的 Platform behavior 表格。粘贴前对剪贴板做快照文本、HTML 及其纯文本替代、图片、文件列表目标消费后原样还原流式片段之间用 generation-tracked 租约防竞态——旧的 restore 不能覆盖新片段也绝不会覆盖你在转写期间自己复制的内容。实现位于 frontend/src-tauri/src/backend.rs 附近的粘贴命令以及commands.rs的 shortcut-down 输入链。2.3 后端sherpa-onnx 双路径引擎后端核心是 backend/services/sherpa_dictation.py它把 sherpa-onnx 作为听写引擎与现有 Whisper/NeMo 家族并存、互不干扰且只用 CPU provider保证 macOS arm64x86_64、Windows x64、Linux 行为一致的跨平台默认平价规则_PROVIDER可用OMNIVOICE_SHERPA_ASR_PROVIDER覆盖但默认绝不偏离 CPU。源码里定义了两类识别器工厂Recognizers类别工厂函数sherpa-onnx 类型行为流式build_online_recognizerOnlineRecognizer.from_transducer/from_paraformer逐帧解码partial 实时增长靠内置 endpoint尾静音检测提交 final离线build_offline_recognizerOfflineRecognizer.from_transducer/from_whisper以约 0.8 s 的节奏重解码滑动窗口产出 partial靠 RMS 静音门提交 finalWS 路由backend/api/routers/capture_ws.py在ws_transcribe中根据?model参数或持久化的dictation.model_id偏好解析出SherpaModelSpec命中 sherpa 模型时走_run_sherpa_streamingcapture_ws.py#L786-L930或_run_sherpa_offlinecapture_ws.py#L933-L1100否则回退到传统 Whisper/WebM 路径行为逐字节不变。2.3.1 流式路径streaming每收到一帧 PCM 就accept_waveformdecode_stream文本增长即发{type:partial}sherpa 检测到 endpoint静音时把该 utterance 抛光polish后作为{type:final,final_kind:utterance}提交并rec.reset(stream)重置流同一 WS 会话内可持续处理多句。endpoint 规则默认 rule11.0 s / rule20.6 s_endpoint_rules()可用OMNIVOICE_DICTATION_ENDPOINT_R1/R2覆盖无需重启。2.3.2 离线路径offline RMS 静音门离线模型如 Parakeet、Whisper无法逐帧解码_run_sherpa_offline维护一个「仅当前未提交 utterance」的 live buffer每OMNIVOICE_SHERPA_OFFLINE_PARTIAL默认 0.8 s重解码窗口一次发送 partial当窗口尾部约 0.6 sOMNIVOICE_SHERPA_OFFLINE_SILENCE的 RMS 低于地板值OMNIVOICE_SHERPA_OFFLINE_RMS默认 0.01时触发提交解码一次、抛光后发 final、从 buffer 丢弃该段样本若整窗都是纯静音则丢弃增长部分防止长时间停顿撑爆缓冲。这样每次解码成本被限制在单个 utterance 内而非整个会话的 O(n²) 重解码句子在停顿后约 0.6 s 即提交而不是拖到 EOF。注意当前阶段这是 RMS 能量门而非真正的 VAD语音活动检测——这正是设计文档 Phase 1 要解决的核心问题之一。2.3.3 共享后端与冷启动状态机get_sherpa_dictation_backend(spec.id)返回按模型复用的共享 warm backend#888识别器只构建一次构建耗时 1.3–2.5 s被后续会话复用预加载后首次听写近乎即时。冷启动时_sherpa_load_with_status会依次发送{type:status,stage:downloading|loading|ready}让悬浮窗如实展示「为什么第一次要等」。2.3.4 静音模型降级silent-model demotion一个很重要的工程细节sherpa 模型可能装好、加载成功却对清晰语音解码出空 tokenNeMo-TDT 路径在部分构建上存在该缺陷Parakeet v2/v3 均受影响而 whisper/zipformer 能转写同样的字节。因此会话听到语音级音频但模型零输出时is_model_silent判定为「模型坏了」而非「用户没说话」_recover_silent_sherpa用已安装的兜底 ASR 重转写最近一段音频有界 RecoveryTail默认 120 s上限 300 s绝不触发自动下载确认包含真实语音后demote_model把该模型记入dictation.silent_models偏好本机不再自动选中它用户在 Settings 里重新选择即可给其一次新机会见 backend/services/sherpa_dictation.py#L482-L546。2.4 文本抛光与本地 LLM 精修每条 final 都经services.text_polishbackend/services/text_polish.py确定性抛光拉丁文首字母大写、补句末标点、单空格归一让粘贴结果读起来像手打文本。可选的本地 LLM 精修Ollama/LM Studio走maybe_refine_asyncbackend/services/refinement.py硬性预算OMNIVOICE_REFINE_TIMEOUT_S默认约 4 sLLM 再慢再死也不会拖住 final超时即回退到未精修但已抛光文本原始文本始终随包发送客户端refined_text ?? text择优。2.5 语音平台开放接口同一听写流程还可通过打包的 Rust 控制 sidecar 暴露给其他应用Herdr 动作、编辑器扩展、Agent 钩子、脚本均可经 loopback HTTP/JSON-RPC 启停捕获或把麦克风音频流式推到带版本的 WebSocket API/v1/audio/transcriptions/stream平台流路径见 backend/api/routers/capture_ws.py#L69-L70协议细节见 docs/speech-platform.md。三、模型推荐矩阵与选型依据设计文档给出了听写模型推荐矩阵仓库内的_MODELSbackend/services/sherpa_dictation.py#L123-L232与之对应共 7 个模型size_gb是 2026-08-07 从 HuggingFace tree API实测的下载大小并配套 tests/test_sherpa_model_sizes.py 钉死清单防回归使用场景模型partial 节奏停顿后 final磁盘 / 内存英语、体验最佳计划新增nemotron-streaming-en 160 ms200–400 ms~0.5–0.7 s0.66 GB / ~1.2 GB欧洲语言可选升级路径parakeet-tdt-v3 silero-VAD0.8 s 节奏~0.4–0.7 s0.67 GB / ~1.2 GB多语言流式可选Nemotron-3.5 320 ms~400 ms~0.7 s0.68 GB / ~1.2 GB低内存zipformer-20M现有~100 ms~0.6 s0.13 GB / ~0.3 GB多语言默认 / CJKwhisper-tiny现有可考虑 smalln/a离线秒级0.104 GB仓库现状对应Whisper Tiny默认sherpa-whisper-tiny离线 whisper90 语言自动检测recommendedTrue即DEFAULT_MODEL_ID。Parakeet TDT v2/v3离线 transducerNeMo-TDTv3 覆盖 25 种欧洲语言实测 0.67 GB此前元数据把 0.17–0.18 GB 当下载大小偏差约 3.8 倍——即设计文档 Phase 0 要修的size_gb问题。Zipformer EN 20M / ZH 14M轻量流式低内存回退此前元数据多报约 3 倍0.128 → 0.044 GB。Zipformer / Paraformer 中英双语流式中文英文。所有模型为 int8 ONNX 权重均来自csukuangfj/HF 仓库首次使用经snapshot_download下载allow_patterns只拉固定清单里的精确 int8 资产绝不误拉 fp32 或测试 wav并接入了hf_cache_repair修复 Windows 上悬挂的缓存快照#1733与不可变 revision 钉定backend/services/hf_revisions.py。线程数上_threads_for对 heavy0.6B 级模型自动升到 4 线程上限不超宿主核心数2 核机器不会被告知跑 4 线程小 zipformer 维持 2 线程默认OMNIVOICE_SHERPA_ASR_THREADS始终作为显式覆盖生效。设计文档 Phase 0 正是计划把默认 2→4因为老 x64 上 2 线程 Parakeet 的 RTF 只有约 0.33余量太薄。四、Phase 0诚实性与低成本修补小时级修size_gb元数据Parakeet 曾标 0.17–0.18 GB真实 int8 约 0.67 GB 磁盘 / 约 1.2 GB 内存onnxruntime arena 分配器不归还已释放块见 sherpa-onnx#2626。在模型选择器里同时展示磁盘与预期内存。线程 2→4为 0.6B 模型提升解码余量OMNIVOICE_SHERPA_ASR_THREADS仍是覆盖项。注size_gb的实测修正与线程策略当前仓库已部分落地见_MODELS注释与_threads_for文档计划与实现互为印证。五、Phase 1手感——真 VAD 真流式 Parakeet核心诉求这是「体验」质变的一步silero-VAD v5 替换 RMS 门_run_sherpa_offline在 VAD 的 speech-end 事件上触发提交解码最小静音约 0.35 s带约 0.2 s pre-rollpartial 只在 VAD 判定为语音时解码 →停顿后 final 从约 1.4 s 降到约 0.4–0.7 s空闲 CPU 占用归零风扇/音乐等噪声下更鲁棒。Silero 是 MIT 许可且已内置在 sherpa-onnx 内无需新增依赖ten-vad 因 modified-Apache 许可需审查不作为默认。新增真流式 Parakeet 模型无依赖变更仓库钉定sherpa-onnx1.13.3nemotron-speech-streaming-en-0.6bint8160 ms chunk推荐英语词级 partial 落后语音约 200–400 msfinal 约 0.5–0.7 s自带标点。现有_run_sherpa_streaming直接可跑只需新增_MODELS条目与配置。Nemotron-3.5-ASR-Streaming-0.6Bint8320 ms可选多语言40 个 locale。许可说明NVIDIA Open Model License / OpenMDW-1.1允许再分发需文档注明不同于 CC-BY 的 Parakeet。悬浮窗 partial UX现有降灰 live partial 文案打磨成 Claude-Code/Aqua 模式——悬浮窗内流式预览、只把 final 插入目标应用。内存缓解如实标签Phase 0、现有 idle-unload#1104、zipformer-20M 低内存回退保持一等公民。六、Phase 2个人词典与技术词汇杠杆最高的一环Parakeet 唯一的硬伤是 OOV 技术术语——而词典正是 Wispr 最受欢迎的功能且没有任何 OSS 应用提供完整版本确定性替换引擎STT 后置、大小写感知、引擎无关用户术语 纠错omni voice→VoiceStudio、cube control→kubectl。Settings → Dictation UI 管理存于 prefs在 polish/refinement之前生效。可选热词偏置hotword biasing仅对离线 Parakeet用 sherpa-onnxmodified_beam_search hotwords 文件上游 PR #3077≥v1.12.24。严格 opt-in——greedy 保持默认因为已知 TDT beam-search 约有 20% 的幻觉 bug#3267需用静音与短片段做回归测试上游修复后再翻转为默认。流式 Nemotron 热词尚未上游化见 #3572。精修保真扩展 prompt 增加逐字跨度保护代码标识符、路径、带引号的错误文本不被改写并默认「转写不要润色」transcribe, dont improve——过度改写是 Wispr 最大的准确性抱怨。Stretchv2从悬浮窗内的用户纠错中自动学习词典候选。七、Phase 3模式——应用感知格式化 Agent 提示词前台应用检测Tauri 按 OS 实现→ 格式化 profile终端/IDE不加句尾句号、不自动大写、不用智能引号——今天常开的text_polish给终端注入句尾句号是破坏性行为聊天口语化、无句尾句号散文保持现状。默认 profile 映射 用户按应用覆盖浏览器/Docker 模式在悬浮窗内提供手动 profile 切换功能处处可用检测只是桌面端增强。Agent 提示词模式词典偏置识别复用 Phase 2 机制、终端安全插入、可选自动提交Enter带词数守卫Claude Code 的模式、「粘贴上次转写」热键。悬浮窗/面板内语言选择器现按模型绑定语言。八、Phase 4插入可靠性 Wayland在 Linux 上做到领先可靠性工程Wispr 做 5 次重试粘贴带退避重试、失败时转写保留在剪贴板并 toast 提示、拒绝密码框、Windows 提权窗口检测。Wayland 插入链取代裸 enigowtype → dotool → ydotool → wl-copynotify 回退评估 GNOME 的 IBus/Fcitx5 输入法提交路径质量最高、主流方案无人做libei/RemoteDesktop-portal 作为远期押注。可靠的本机 Linux 插入是护城河。现状可参考 docs/features/dictation.mdwlroots 用wtypeKDE Plasma/GNOME 可用dotool/ydotool走剪贴板粘贴。dotool需直接写/dev/uinputydotool1.0 需要运行中的ydotoold且 socket 用户可读——VoiceStudio 在选择前会检查这些前置条件。托盘启动的 Wayland 听写始终仅复制。九、Phase 5命令模式头条特性纯本地差异化第二热键 → 对选中文本说出指令 → 本地 LLM 改写 → 显式 Apply。Wispr 对此收费而这里本地且免费。需要已配置 LLM 才显示复用现有llm_ready管道否则隐藏。十、Phase 6文档、基准与评测新建docs/features/dictation.md已落地即本文引用的用户指南模式、模型、延迟预期、词典、各 OS 插入说明。延迟在产品内可见悬浮窗 done 状态显示 release→pasted 毫秒让「快」成为可见特性。扩展tests/probe/dictation评测延迟预算、VAD 定稿、词典命中率、终端 profile 无句尾句号。现有探测骨架见 tests/probe/specs/dictation.probe.yaml 与 tests/probe/judges/dictation.py。十一、Top Risks 与显式非目标主要风险设计文档原样保留内存8 GB 机器上约 1.2 GB 占用——如实标签、idle-unload、zipformer 回退并在 8 GB Windows 上测试。TDT beam-search bug#3267——热词仅 opt-in等上游修复。老 CPU 的 RTF 余量——线程提升 首载自动基准测试RTF 0.8 时回退 zipformer。Wayland 碎片化——带按技术检测的回退链wl-copynotify 作为保底。范围蔓延——各阶段独立可交付都落在现有 Settings 界面之后互不阻塞。显式非目标token 级语音编程Talon/Cursorless 语法学习曲线以月计且生态已成熟——本项目的编程叙事是 Agent 提示词模式、任何云端 ASR、常开麦克风。十二、实战现在就怎么用对应现状文档按 docs/features/dictation.md从 Model Catalogue 安装听写模型在Settings → Voice或顶栏 EnginesTranscription → Sherpa-ONNX dictation → Dictation model中选择该选择与配音、批量转写共享同一 Sherpa-ONNX 引擎。在Settings → Hotkey设置热键及 hold/toggle 行为。光标置于文本域按热键、说话、松开或再按一次。Transcriptions 页提供同款录音器的Start dictation上下文动作悬浮录音条含Pause / Resume / Stop / Close暂停是手动的不因静音或桌面空闲触发。悬浮窗报告Inserted仅当原生投递成功Copied表示自动插入不可用、完整最终转写已就绪可正常粘贴。静音模型兜底只会换用已安装的另一 ASR 模型绝不启动下载。各平台自动插入行为速查macOS 重新激活目标应用并发 Command-V无辅助功能权限则保持复制Windows 校验并激活窗口后发 Ctrl-V激活被拒则保持复制Linux X11 通过 EWMH 重新激活后发 Ctrl-VWayland 默认仅复制浏览器模式仅复制。高级 Wayland 用户可设VOICESTUDIO_WAYLAND_UNTARGETED_INSERT1在转写完成时插入当前键盘焦点应用。结语从本文可见VoiceStudio 的听写不是「又一个麦克风转文字」它以 7 个 int8 ONNX 模型的矩阵覆盖从 0.025 GB 低内存到 0.68 GB 多语言流式的全部场景用流式/离线双路径加 RMS 静音门未来升级为 silero-VAD在 CPU 上做到亚秒级 final用会话 ID 捕获目标、剪贴板快照还原、静音模型降级与硬预算 LLM 精修把可靠性做到可日常使用并以六阶段路线图向「本地 Wayland Agent 提示词」的差异化纵深演进。对开发者而言docs/specs/2026-07-16-dictation-flow-program.md 是路线蓝图backend/services/sherpa_dictation.py 与 backend/api/routers/capture_ws.py 是可直接研读的参考实现docs/features/dictation.md 是当下的使用手册。【免费下载链接】VoiceStudioVoiceStudio is the open-source, fully-local ElevenLabs alternative — voice cloning, voice design, video dubbing, dictation, transcription audiobook creation in 646 languages.项目地址: https://gitcode.com/GitHub_Trending/om/VoiceStudio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考