听写¶

VoiceStudio 听写通过系统级快捷键进行录音，在本地转写，并在桌面环境允许时将结果插入到按下快捷键时所在的应用中。药丸控件永远不需要键盘焦点。

编辑器扩展、代理钩子和脚本可以将自己的麦克风音频流式传输到带版本号的 WebSocket API，或通过 HTTP 转写文件。有关协议和示例，请参阅本地语音平台。

使用¶

1. 从 Model Catalogue 安装一个听写模型，然后在 Settings → Voice 或顶部栏的 Engines 菜单（Transcription → Sherpa-ONNX dictation → Dictation model）中选中它。该选择也是 Sherpa-ONNX 引擎在配音和批量转写时加载的模型。
2. 在 Settings → Hotkey 中设置快捷键以及按住/切换行为。
3. 将光标放在文本字段中，按下快捷键，开始说话，然后松开或再次按下。

Transcriptions 页面通过一个 Start dictation 操作打开此录音器。在您还没有任何转写记录之前，此操作处于空状态；在第一条转写记录之后，它会出现在页面头部。在桌面上，该操作会唤醒录音器窗口，等待其确认，并且只有在麦克风启动被接受后才确认成功。页面会报告听写被禁用、请求被拒绝或超时、或录音器启动失败的情况。

Whisper Tiny 是 macOS、Windows 和 Linux 上推荐的默认模型。它能自动检测 90 多种语言。Parakeet TDT v3 仍然可用于其支持的 25 种欧洲语言，但不会被自动选中。

只有当原生插入成功时，药丸控件才会报告 Inserted。Copied 表示自动插入不可用，完整的最终转写文本已准备好供正常粘贴。VoiceStudio 仅通过另一个已安装权重的 ASR 模型重试语音级别的空 Sherpa 解码；当该回退确认音频包含词语时，静音模型会被降级。此恢复过程绝不会启动下载。

目标和剪贴板安全¶

桌面在按下快捷键时捕获目标，并在部分结果、语句和摘要消息中携带其会话 ID。来自较旧会话的迟到结果不能使用较新会话的目标。macOS、Windows 和 X11 会在插入前验证并重新激活所捕获的进程/窗口。Wayland 不暴露可移植的目标身份或任意外部窗口激活能力，因此安全的默认做法是将转写文本保留为已复制状态，而不是猜测哪个应用应接收它。GTK 药丸控件保持不可聚焦。

对于粘贴交付，VoiceStudio 会快照文本、HTML（及其纯文本替代）、图像或文件列表剪贴板内容，暂存转写文本，并在目标消费后恢复快照。流式片段共享一个代际跟踪的租约：过期的恢复不能胜过较新的片段，且 VoiceStudio 绝不会覆盖您在转写期间复制的剪贴板内容。不支持的剪贴板格式无法往返恢复；在这种情况下，转写文本会保留在剪贴板上，而不是尝试有损恢复。

平台行为¶

在 macOS 上，原生键盘创建、布局查找、粘贴和实时打字在两个桌面 Shell 中均于主线程运行。会话和剪贴板工作保留在现有的 worker 路径上，并且粘贴使用当前活动键盘布局的 Command-V 映射，而不是假定物理 QWERTY 键。

高级 Wayland 用户可以设置 VOICESTUDIO_WAYLAND_UNTARGETED_INSERT=1，在转写完成时插入到当前拥有键盘焦点的任何客户端中。wlroots 合成器使用 wtype；KDE Plasma 和 GNOME 可以通过 dotool 或 ydotool 使用剪贴板粘贴。辅助程序以来自 AppImage 的主机加载器变量运行，具有受限超时时间，并且在其中一个可能已发出部分输入后绝不重试。这种选择加入方式无法在焦点改变时保证按下快捷键时的目标。dotool 需要直接写入 /dev/uinput；ydotool 1.0+ 需要运行具有该访问权限的 ydotoold 以及用户可读的 socket。VoiceStudio 在选择前会检查这些先决条件。从托盘启动的 Wayland 听写始终仅复制。

Transcriptions 模型设置¶

Transcriptions 在启用 Start dictation 之前会检查当前听写模型。如果缺少权重，页面会列出每个听写模型，按您在两者之间选择的权衡进行分组——最佳准确性（离线，在您停止后转写）与最低延迟（流式，在您说话时实时显示文本）——每一行都标明语言和下载大小，以便您安装适合您工作的模型，而不仅仅是推荐的默认模型。已存在于磁盘上的模型可以无需下载即可切换。会显示所选模型的名称、下载大小和安装进度。下载需要显式点击。失败的下载可以重试，从 Settings 返回时模型状态会刷新。一旦安装验证通过，Start dictation 就可用；录音绝不会自动开始。在设置过程中，现有的转写历史仍然可访问。

浮动录音控件¶

录音气泡包含 Pause / Resume、Stop 和 Close。Pause 会禁用麦克风轨道、停止发送新的音频，并冻结已用录音时间，同时保留会话。Resume 会继续同一会话。Stop（或录音快捷键）会结束并转写，包括在暂停时。Close 会取消待处理的录音/转写并释放麦克风；已经交付给另一个应用的文本无法撤回。暂停是手动的，不会因静音或桌面空闲而触发。

转写页面会显示有效的录音快捷方式和平台粘贴快捷方式。浮动气泡会将其实时转录文本以多行预览的形式展示在控件下方，这样控件就不会把文本挤压成寥寥几个字符。