本地语音平台¶

VoiceStudio 既是桌面听写应用，也是无头本地语音服务。桌面应用负责麦克风采集、听写快捷键和原生插入；Python 后端保持 ASR 模型常驻，并向任何其他接口暴露音频数据平面。

VS Code / custom GUI / remote mic ── PCM or WebM ───────> WS/HTTP :3900
                                                          │
                                                          └─ partial/final text

Scripts / TUIs / hooks ── audio files ──────────────────> HTTP :3900

Claude Code / Codex / Pi / agents ── MCP HTTP/stdio ───> MCP :3900

原生听写控制已退役。 Tauri 桌面应用曾捆绑一个回环控制服务器，监听 3902 端口（/v1/dictation/*、JSON-RPC、--dictate-* 标志、输出会话）。Electron 应用不再提供该功能，3902 现在是其开发服务器的端口。请使用应用内听写快捷键，或自行采集音频并按下文所述进行流式传输。

发现能力¶

curl http://127.0.0.1:3900/.well-known/voicestudio-speech

该文档返回 voicestudio.speech.v1 及相对 URL，因此它也能在 Tailscale 或反向代理之后工作。features.native_dictation_control 仍保留在 schema 中，且始终为 false。

无依赖的 Python 桥接器便于 hooks 和 TUI 使用：

python -m backend.speech_client capabilities
python -m backend.speech_client transcribe recording.wav

它优先使用 VOICESTUDIO_URL，否则使用 OMNIVOICE_PORT（默认 3900）上的回环后端；当设置了 OMNIVOICE_API_KEY 时，会将其作为 bearer 密钥发送。之前的 status、start、stop、toggle 和 transcribe --insert 命令会退出并附带说明。诸如 127.1 的数字回环拼写无需 DNS 查找即可识别；远程 bearer 凭据仍要求使用 HTTPS。上传的文件名在进入 multipart 头之前会被简化为可移植的 basename；音频字节和表单字段内容保持不变。

自带采集接口¶

编辑器扩展或 GUI 可以拥有麦克风并消费实时文本。连接到：

ws://127.0.0.1:3900/v1/audio/transcriptions/stream

默认发送二进制 WebM/Opus 帧。如需原始有符号 16 位单声道 PCM，请使用 ?pcm=1&sr=16000。不关闭 socket 而结束会话，请发送：

{"type":"input_audio.end"}

每个响应都携带 protocol 和 session_id：

{"type":"session.started","protocol":"voicestudio.speech.v1","session_id":"..."}
{"type":"partial","text":"hello wor...","session_id":"..."}
{"type":"final","final_kind":"summary","text":"Hello world.","session_id":"..."}

流式 Sherpa 模型还可以在权威的整会话 summary 之前发出 final_kind: "utterance"。现有的 /ws/transcribe 客户端保持其未更改的旧版帧和 EOF 控制不变。

批处理与代理协议¶

集成图谱¶

回环客户端无需凭据。远程原生 WebSocket 客户端可以发送已配置的 bearer 密钥。浏览器客户端应将该密钥兑换为短期会话，在 /api/auth/ws-ticket 处生成路径绑定的 ticket，并使用 ?ws_ticket=... 连接；参见 API 身份验证。远程端点应限制在可信网络内；API 密钥用于认证客户端，但不提供网络隔离。在完全可信的 LAN 之外，请使用 HTTPS/WSS，切勿通过明文 HTTP/WebSocket 发送 bearer 凭据或进行 ticket 交换。

安全与隐私¶

• 任何接口都无法远程打开桌面应用的麦克风；采集只能由应用本身启动。远程 ASR 保持在现有的 API 密钥边界上。
• 麦克风保持在接口边缘。远程 GPU 后端绝不假定它拥有用户的输入设备。
• 任何协议都不会添加必需的网络调用、账户、分析事件或云提供商。

研究基础¶

设计调研覆盖了 GitHub speech-to-text 主题 的五页：1、2、3、4 和 5。

该平台保留了最值得复用的想法，而不照搬它们的 UI 边界：

差异化优势在于连接层：一个捆绑式应用同时提供原生捕获与插入，外加一项协议无关的 ASR 服务，因此每个接口都无需重新构建模型加载。