VoiceStudio — 说话人分离¶

说话人分离将单个音频流分割为每个说话人的音轨：谁说了什么，以及何时说的。VoiceStudio 内部使用 pyannote + WhisperX —— 与原始 WhisperX 论文使用的技术栈相同。

说话人分离能带来什么¶

• 多说话人配音：每个检测到的说话人都会在目标语言中获得自己的声音克隆。一行文本中的词语若属于两个说话人，则会在说话人切换处拆分，这在所有转写路径（应用、CLI 和手机伴侣）上均适用。一个自成句子的单字回答（如"Fine."）也会被拆分出来；句子内部的单个词则被视为说话人分离噪声。落在两段话间隙中的单词和行会归属于最近的说话人。即使某个说话人只讲短句，也会获得一个声音克隆，从他们的话语中裁剪出来，并修剪掉与其他说话人相邻的边缘；只有干净语音少于约 3 秒的说话人才会回退到默认声音。与其他说话人的行重叠的行不会获得行级参考，因此其声音绝不会是两者的混合。
• 字幕样式：导出 SRT/VTT 文件上的说话人标签（SPEAKER_00:、SPEAKER_01:、……）。
• 音频编辑：时间线视图中的每个说话人独立音轨。

许可证接受流程¶

说话人分离模型——pyannote/speaker-diarization-3.1——在 HuggingFace 上受 门控 保护。仅有有效的 HF token 还不够：你还需要接受该模型的许可证一次。

1. 如果没有 HF token，请获取一个——参见 docs/setup/huggingface-token.md。
2. 通过 设置 → 凭据（或任何其他受支持的路径）设置 token。
3. 使用同一账户登录 HuggingFace 后，访问：
4. https://huggingface.co/pyannote/speaker-diarization-3.1 → "同意并访问仓库"。
5. https://huggingface.co/pyannote/segmentation-3.0 → 同样操作。
6. 在 设置 > 模型 > 说话人分离 中安装模型。等待安装完成，然后重试转写。任务只会加载本地已安装的文件。

如果你跳过许可证接受步骤，HF API 会为下载返回 401 Unauthorized 或 403 Forbidden —— 与应用内 "打开此错误的文档" 按钮深度链接到的错误类别相同。

回退行为¶

当说话人分离文件缺失或已安装的运行时无法加载时，VoiceStudio 会回退到 静音间隙启发式算法。任务警告会说明是安装/修复模型还是检查后端日志。任务绝不会下载缺失的权重。

这种启发式算法不如 pyannote 准确——音色相似或快速轮流对话的说话人可能会被合并——但它能让配音端到端完成，而不是报错。

HF token 要求¶

安装受门控的 pyannote 包需要 HF token 和已接受的仓库访问权限。一旦其 pipeline、segmentation 和 embedding 文件被缓存，推理即可离线工作，无需保留 token。参见 Hugging Face token 设置。

故障排除¶

• 安装返回 401/403：请确认 token 属于有权访问这两个受门控仓库的账户。
• 文件缺失：从 设置 > 模型 > 说话人分离 安装或修复。
• 已安装的模型无法加载：检查 设置 > 日志 > 后端。运行时失败本身并不表示许可证或 token 有问题。

本地安装与修复¶

完成上述访问步骤后，从 设置 > 模型 > 说话人分离 安装 pyannote。安装包括其 segmentation 和 speaker-embedding 检查点。仅有一个 pipeline 配置并不构成完整安装；修复也会检索缺失的依赖项。

配音会从本地缓存解析所有三个文件，不会在任务期间下载模型。一旦安装完成，该包无需保留 HF token 即可运行。文件缺失会提示安装或修复；转写会继续使用现有的静音间隙回退方案及其准确性注意事项。运行时加载失败与文件缺失会分别报告。

原生 Sortformer 适配器¶

共享的说话人分离路径也支持 audio.cpp Sortformer v1。在 设置 → 模型 → 说话人分离 中安装经过审查的模型及其带校验和的原生运行时，然后在该页面上选择 Sortformer。VoiceStudio 会在本地解析已安装的 Q8 GGUF 并持久化该选择；它在转写过程中绝不会下载模型。OMNIVOICE_DIARIZATION_BACKEND 和 OMNIVOICE_DIARIZATION_MODEL 仍然是托管部署的权威覆盖项。

该适配器将输入归一化为单声道 16 kHz，将以样本为单位的轮次转换为共享的标注格式，并以十分钟超时封装原生进程。Sortformer 最多支持四个说话人，但无法强制执行现有的精确说话人数设置；请求该设置会走现有的回退/警告路径。其加速器图会从默认的 20 秒上下文扩展到最长 120 秒的片段。更长的录音需要 pyannote，直到本地转换的 Sortformer v2.1 流式权重可以分发为止。不会隐式下载任何二进制文件或模型。模型的 CC-BY-NC-4.0 限制适用；请参阅上游 audio.cpp 模型卡。原生进程状态和取消已接入共享的任务生命周期。

运行 uv run --no-sync python scripts/smoke_sortformer.py <local-media> --min-speakers 2 以验证已安装的运行时对本地媒体的支持。添加 --seconds 120 --cancel-after 0.5 以验证进程取消。该冒烟测试只会写入一个归一化的临时片段，绝不会下载模型或更改应用数据。在受维护的 Windows RTX 4090 基准设备上，v0.7.4 通过 Vulkan 在 3.27 秒内处理了一个真实的 60 秒配音源，返回了 16 个边界明确的轮次，并在 1.2 秒内取消了 120 秒变体，没有留下已注册的进程。

audio.cpp v0.7.4 包含更新的 Sortformer v2.1 流式运行时。其 NVIDIA Open Model License 检查点目前没有可再分发的 GGUF 包，因此 VoiceStudio 不会提供上游无法合法提供的下载。一旦模型可以通过明确的本地包工作流提供，本地转换的混合 F16/F32 检查点就是计划中的长录音方案。