VoiceStudio — whisper.cpp 语音识别¶

通过上游 whisper.cpp CLI 提供的可选本地转录与翻译功能。它在所有平台上都可在 CPU 上运行；当你的 CLI 构建支持时，也可在 GPU 上运行：Vulkan（AMD）、CUDA（NVIDIA）或 Metal（macOS）。仅有 Vulkan 加载程序并不能让已安装的 CLI 具备 GPU 支持。

安装¶

二进制文件和模型均由用户自行管理；VoiceStudio 不会自动下载它们，也不会通过 Model Catalogue 提供它们。

1. 安装或构建带有所需 GPU 后端的 whisper-cli（Windows 上为 whisper-cli.exe）。
2. 下载兼容的 Whisper GGML 模型，例如 ggml-base.bin。
3. 在 Linux 和 macOS 上，为 CLI 赋予执行权限：chmod +x /path/to/whisper-cli。

选择¶

在启动 VoiceStudio 之前设置以下环境变量（适用于所有桌面操作系统）：

• OMNIVOICE_ASR_BACKEND=whisper-cpp 明确选择该引擎。
• OMNIVOICE_WHISPER_CPP_BIN 指向 whisper-cli。
• OMNIVOICE_WHISPER_CPP_MODEL 指向你下载的模型文件。
• OMNIVOICE_WHISPER_CPP_DEVICE 可选地选择原生 GPU 索引。
• OMNIVOICE_WHISPER_CPP_BACKEND=cpu 禁用原生 GPU 加速。

自动 ASR 选择逻辑不变：只有在你明确选择时，才会使用 whisper.cpp。

查找位置¶

• CLI：backend/engines/whisper_cpp/bin/ 或 PATH；OMNIVOICE_WHISPER_CPP_DIR 选择其目录。仅在明确选择的目录或包本地目录中接受旧版 main 可执行文件。
• 模型：backend/engines/whisper_cpp/models/、~/.cache/whisper/，或 ggerganov/whisper.cpp 现有的 Hugging Face 缓存。在这些位置仅搜索不含路径的模型名称（如 ggml-base.bin）；如果 OMNIVOICE_WHISPER_CPP_MODEL 中的路径不存在，则会报告为缺失，而不会从其他文件夹加载同名模型。这也适用于明确选择的当前目录路径，如 ./ggml-base.bin 或 .\ggml-base.bin；如需本地缓存搜索，请使用不带路径的名称。

源语言与翻译¶

• 如果 CLI 省略了检测到的语言元数据，或返回格式错误的元数据，则该语言保持为未知，而不会默认设为英语。在交互式配音中，请先选择源语言，然后再进行翻译。批量配音需要指定语言：当 ASR 未报告任何语言时，任务会停止，并显示一条消息要求你选择源语言。
• 你在配音中选择的源语言适用于所有读取源文本的位置：翻译请求、为任务检查并安装的 Argos 语言包，以及从源文本中提取的术语表词条。只有在未作出明确选择时，自动检测才会填补这一信息。
• 翻译需要多语言模型；仅支持英语的 .en、Turbo 和 Distil 检查点会被拒绝用于翻译。这一判断以检查点自身的文件名为依据，因此缓存在 Hugging Face hub 中的模型（以符号链接形式存储到内容寻址的 blob 中）会依据缓存条目的名称而非 blob 的哈希值来判断。

许可证¶

许可证检查依据的是文件本身而非名称：所选模型沿用实际保存它的仓库的条款，即使缓存条目指向其他地方也是如此。从 Hugging Face 缓存解析出的模型保留其来源仓库的许可证检查。其他自定义本地文件没有假定的仓库身份；其条款仍由你自行负责。

注意事项¶

• 全局 CPU 选择始终禁用 GPU 使用。
• 诊断信息使用保守的 CPU 估算，因为 CLI 的 GPU 提供商未经验证。
• 不具备完整 JSON 输出的旧版 CLI 构建可以进行转录，但不会提供词级时间戳。
• 音频转换仅允许本地文件和管道输入。上传的播放列表中的远程 URL 条目将被拒绝。