第6章 听写

概述

听写（Dictation） 按住您机器上任意位置的组合键，开口说话，松开——转录文本会直接落入你之前聚焦的文本框。

概述 听写功能让你在计算机上的任何地方都能将语音转化为整洁的文本。按住组合键说话，松开后，Voicebox 会使用 Whisper 转录你刚才说过的内容，可选地使用本地 LLM 进行清理，并将结果粘贴到你最初聚焦的文本框中。

一切都在你的硬件上发生。无云端、无账号、无音频数据离开本机。

听写功能在 0.5.0 版本中随“捕获（Captures）”标签页和每配置文件个性模式一同推出。它是 Voicebox 语音 I/O 循环中的“输入”部分——克隆和 TTS 仍然是“输出”部分。

工作流程 1. 在机器的任何地方按住按压式通话（Push-to-talk, PTT）组合键。当前应用上方会淡入一个小胶囊（pill）界面。 2. 胶囊显示“正在录音（Recording）”，伴有实时波形和经过时间计数器。自然说话即可，无需等待任何确认。 3. 松开后，胶囊变为“正在转录（Transcribing）”，如果启用了自动优化（auto-refine），则会变为“正在优化（Refining）”，随后消失。 4. 如果启用了自动粘贴且 Voicebox 拥有辅助功能（Accessibility）权限，转录文本会粘贴到你开始说话时聚焦的文本框中——即使说话过程中焦点漂移，它也不会粘贴到当前焦点所在的位置。

无论哪种情况，每次捕获的内容都会显示在“捕获”标签页中，原始音频和转录文本成对保存。关于之后能做什么，请参阅 捕获。

按压式通话与切换模式 Voicebox 默认提供两种组合键行为：

| 模式 | 默认设置 (macOS) | 默认设置 (Windows) | 行为 | | :--- | :--- | :--- | :--- | | 按压式通话 | 右 ⌘ + 右 ⌥ | 右 Ctrl + 右 Shift | 松开组合键即停止录音。 | | 切换式通话 | 按压式通话 + 空格 | 按压式通话 + 空格 | 录音持续进行，直到再次轻敲组合键。 |

在按住 PTT 的同时，中途轻敲空格键可以将“按住”升级为“切换”会话，且音频不会中断。这是组合键系统中最实用的细节——短促的话语感觉迅速，长篇叙述感觉解放双手，且无需事先决定使用哪种模式。

屏幕上的胶囊 听写期间，一个浮动胶囊会出现在当前应用上方。它展示捕获周期的各个状态，并显示每个状态的实时信号：

| 状态 | 显示内容 | | :--- | :--- | | 录音中 | 实时波形 + 经过时间。 | | 转录中 | Whisper 运行时显示思考波形。 | | 优化中 | LLM 清理转录文本时显示相同的思考波形（仅当启用自动优化时）。 | | 错误 | 红色色调。点击胶囊可将错误复制到剪贴板。自动消失。 |

该胶囊是透明的、始终置顶的，并在应用启动时预先创建并隐藏——因此当你按下组合键时，它会立即出现，没有窗口闪烁。

自定义组合键 打开 设置 → 捕获 → 听写 以更改任意组合键。

* 左/右修饰键徽章：当你在组合键选择器中按下按键时，Voicebox 会记录每个修饰键是左键还是右键变体。这意味着你可以只绑定右 ⌥，而保留左 ⌥ 不变——这很有用，例如你希望用一只手进行听写，同时保留另一只手的快捷方式。 * 组合键默认值：默认值旨在避免干扰你。在 macOS 上，默认设置故意避开左手 Cmd+Option 组合，因此 `Cmd+Option+I`（开发工具）、`Cmd+Option+Esc`（强制退出）和 `Cmd+Option+Space`（聚焦）都保留给你。在 Windows 上，默认设置绕开了德语/法语/西班牙语布局中 Ctrl+Alt 合成 AltGr 的冲突。 * 实时重新加载：在设置中更改组合键立即生效——无需重启，无需重新加载标签页。

自动粘贴到聚焦的应用 转录完成后，Voicebox 可以合成原生粘贴，将你按下组合键时具有焦点的文本框填入内容。剪贴板在粘贴前保存并在粘贴后恢复，因此你复制的内容不会丢失。

| 平台 | 机制 | | :--- | :--- | | macOS | 在 HID 层通过 CGEventPost 发送完整的 ⌘V 按键序列，先前通过 NSRunningApplication 重新激活原应用。 | | Windows | 使用正确的扫描码通过 SendInput，加上 SetForegroundWindow + AttachThreadInput 握手，以击败粘贴到非前台窗口时的前台锁定。 |

焦点在按下组合键时会被快照。即使转录/优化期间焦点漂移，粘贴目标也是原始字段——这就是“粘贴到你说话的地方，而不是你现在看的地方”的行为。

自动粘贴是可选的。如果未授予辅助功能权限（macOS），或者你更喜欢关闭合成输入，听写仍会运行——转录文本会落入“捕获”标签页，你可以手动复制。该设置位于 设置 → 捕获 → 听写 中辅助功能提示的内联旁边，而非全局横幅。

优化（Refinement） 如果启用自动优化，本地 LLM 会在粘贴前清理原始的 Whisper 转录文本。目标是去除口头冗余，而不重写你实际说过的内容。

优化通常修复： * 填充词（um, uh, like 用作停顿, you know） * 自我纠正——LLM 保留最终版本，丢弃早期尝试（例如：could you uh run the migration real quick, and then, yeah, check the logs → 变成 Could you run the migration, then check the logs?） * 基本的标点和大小写 * Whisper 循环幻觉——Voicebox 在 LLM 看到转录文本之前，会去除重复标记（连续六个或更多相同标记，不区分大小写），因此小型优化模型不会回显它们。

优化刻意保留： * 技术术语和代码标识符（`npm install`, `handleSubmit`） * 合法的重复（no, no, no, no, no 少于六个相同标记，因此保留） * 你的意图——优化是清理，不是重写。

标志按捕获进行快照，因此你可以稍后使用不同的标志重新优化相同的原始转录，而不会丢失原始内容。优化模型选择器（设置 → 捕获 → 优化）提供三种捆绑的 Qwen3 尺寸：

| 模型 | 大小 | 最适用于 | | :--- | :--- | :--- | | Qwen3 0.6B | ~400 MB | 默认。非常快，适合日常听写。 | | Qwen3 1.7B | ~1.1 GB | 转录包含代码标识符时的甜点区。 | | Qwen3 4B | ~2.5 GB | 完全质量，最慢。 |

这与每配置文件个性模式使用的本地 LLM 相同——应用中只有一个 LLM，不是两个。请参阅 语音个性。

平台注意事项

macOS * 自动粘贴需要辅助功能权限。提示位于 设置 → 捕获 → 听写 中切换开关的内联旁边，并带有指向系统设置 → 隐私与安全性 → 辅助功能的深度链接。 * TSM 崩溃缓解。全局热键监听器在后台线程上运行，使用 `set_is_main_thread(false)` 以规避 macOS 14+ 中 rdev 库的已知崩溃。如果在 macOS 上遇到意外的听写失败，请检查日志中的 TSM 相关消息。

Windows * UAC / UIPI 警告。从非提升的 Voicebox 向提升的窗口进行合成粘贴会被 Windows 本身阻止。如果你经常向提升的应用（例如提升的终端或任务管理器）听写，请以提升身份运行 Voicebox。 * 右手默认组合键（Ctrl+Shift）避开了在 Ctrl+Alt 是组合键的键盘布局（德语、法语、西班牙语等）上的 AltGr 冲突。

Linux * 此版本中尚未支持。Rust shim 在 0.5.0 中提供了 macOS 和 Windows 路径。Linux uinput / AT-SPI 支持和 Wayland 粘贴方案正在 `docs/plans/VOICE_IO.md` 中跟踪。

自动粘贴跳过自身的情况 有几种情况 Voicebox 会刻意不合成粘贴： * 按下组合键时焦点在 Voicebox 内部。转录文本会进入“捕获”标签页，以防听写进入 Voicebox 的往返操作意外粘贴到生成框中。 * 未检测到文本焦点。转录文本仍会落入“捕获”标签页；你可以从那里一键复制。 * 在 macOS 上未授予辅助功能权限。同样——仅限“捕获”标签页。

下一步 * 捕获：所有听写落入的配对音频 + 转录归档。 * 语音个性：相同的本地 LLM 驱动每配置文件撰写和人物重写。 * 转录：关于 Whisper、Whisper Turbo 和 STT 后端的开发者级细节。 * 在 GitHub 上编辑 * GPU 加速：Voicebox 如何使用你的 GPU——自动检测、手动设置、故障排除 * 捕获：配对音频 + 转录归档——所有听写、录音和上传的音频文件都显示在这里，可重放且可重新转录。