OmniVoice
概述
通过OmniVoice Studio MCP服务器在本地生成音频。工具：generate_speech、list_voices、list_personalities、list_languages、check_health。资源：voice://{id}、history://recent。
前提条件——后端必须正在运行
所有MCP工具都会访问 $OMNIVOICE_API_URL（默认为 http://localhost:3900）。如果后端未运行，每个工具都将返回连接错误。安装并启动：
git clone https://github.com/debpalash/OmniVoice-Studio.git "$OMNIVOICE_HOME"
cd "$OMNIVOICE_HOME"
uv sync
VIRTUAL_ENV="$(pwd)/.venv" uv pip install 'mcp[cli]'
然后：
scripts/check-health.sh # 退出码0表示运行正常
scripts/start-backend.sh # 后台启动（自动检测MPS/CUDA）
首次合成调用时会从HuggingFace惰性下载 k2-fsa/OmniVoice 模型（约2.4 GB）——后续启动时缓存。
任务索引——选择合适的工具
| 任务 | 工具 | 说明 |
|---|---|---|
| 验证后端是否运行 | check_health | 返回 `{"status":"ok","device":"mps |
| 使用已保存的语音将文本转为音频 | generate_speech(text, profile_id) | 返回base64编码WAV。profile_id="demo0001" 为内置演示语音 |
| 无需克隆的文本转音频（语音设计） | generate_speech(text, instruct="…") | 省略 profile_id；传入 instruct，例如 "warm middle-aged female narrator, calm pace" |
| 多语言语音生成 | generate_speech(text, language="es") | 任意ISO 639代码或 "Auto" |
| 列出已有语音 | list_voices | 返回id、名称、类型、个性 |
| 列出现成个性预设 | list_personalities | 返回 narrator / casual / news-anchor 等及其 instruct 字符串 |
| 列出支持的语言 | list_languages | 总计646种；返回20种常用语言以及总数 |
对于非平凡决策（使用哪个引擎、何时选择OmniVoice而非kokoro / Edge TTS / ElevenLabs），请参见 references/engines-comparison.md。
有关MCP连接细节、后端生命周期、故障排除及彻底卸载，请参见 references/mcp-setup.md。
常见工作流
1. 使用演示语音进行一次性语音生成
# 通过MCP客户端调用（您的agent将自动完成）：
result = generate_speech(
text="Hello — this is OmniVoice generating speech locally.",
profile_id="demo0001",
language="English",
steps=16, # 8 = 快速/草稿 · 16 = 平衡 · 32 = 高质量
)
# result 为 JSON，包含 audio_id、generation_time_s、audio_duration_s、format、wav_base64
基准测试：在Apple Silicon MPS上，16个扩散步数下，生成4.2秒音频大约需要24秒服务器端时间。
2. 将WAV保存到磁盘并播放
工具返回base64编码的PCM WAV（16位、单声道、24 kHz）。解码并写入：
import base64, json
payload = json.loads(result_text) # 解析工具返回的JSON
open("out.wav","wb").write(base64.b64decode(payload["wav_base64"]))
在macOS上：afplay out.wav。使用 ffmpeg -i out.wav -codec:a libmp3lame -b:a 128k out.mp3 转换为MP3。
3. 语音克隆——端到端配方
克隆需要一个3-10秒的参考片段，模型将其用作说话人嵌入。MCP服务器不暴露配置文件的创建——它只读取现有配置文件。创建方法有两种：
方法A——使用捆绑脚本（macOS，推荐用于新的克隆）：
scripts/record-reference.sh ~/Downloads/my-ref.wav 12 1
# 参数：输出路径 原始录音时长(秒) 麦克风索引
# 默认 mic_index=1（MacBook内置）；列出设备：
# ffmpeg -f avfoundation -list_devices true -i ""
该脚本通过macOS的 say 和 /System/Library/Sounds/Ping.aiff 提供可听见的倒计时和开始/结束提示，以便用户知道何时说话（终端stdout有缓冲——文本“speak now”提示到达太晚）。它会录制一个较长的原始窗口，然后通过 silenceremove + atrim 修剪到约10秒的语音，播放以验证，并打印下一步的 curl 命令。
方法B——手动：
# 1. 录制（单声道，24 kHz原生——与模型内部速率匹配）
ffmpeg -f avfoundation -i ":1" -t 12 -ac 1 -ar 24000 raw.wav
# 2. 修剪前导静音并截取前10秒语音
ffmpeg -i raw.wav \
-af "silenceremove=start_periods=1:start_silence=0.05:start_threshold=-40dB,atrim=end=10" \
-ac 1 -ar 24000 ref.wav
# 3. 验证
ffmpeg -i ref.wav -af volumedetect -f null - 2>&1 | grep volume # 最大值应 > -20 dB
afplay ref.wav
向 /profiles 发送POST请求（multipart/form-data——必填字段：name、ref_audio）：
curl -X POST http://127.0.0.1:3900/profiles \
-F "name=carlos-clone" \
-F "[email protected]" \
-F "ref_text=The exact text spoken in the clip" \
-F "language=English" \
| python3 -m json.tool
# 返回 { "id": "abc12345", "name": "carlos-clone" }
创建后，将 profile_id 传递给 generate_speech（通过MCP）或直接通过 POST /generate 调用。配置文件持久化存储在SQLite中，参考音频文件保存在 ~/Library/Application Support/OmniVoice/voices/<id>.<ext>（后端保留上传的扩展名——如果是WAV则为 .wav，MP3则为 .mp3，等等）。配置文件在后端重启后仍然保持。
对质量有实质性影响的参考片段提示：
| 因素 | 为何重要 |
|---|---|
| 单一说话人 | 混合说话人会使嵌入模糊 |
| 干净语音，无音乐/噪音 | 模型也会嵌入噪音 |
| 自然韵律（避免使用 pangrams） | 扩散采样复制韵律，而不仅仅是音色 |
| 3-10秒是最佳长度 | < 3秒信息不足；> 10秒增加计算量而不提升质量 |
ref_text 与实际说出内容匹配 | 提高对齐效果，尤其对于有噪音的参考片段 |
language 正确 | 语言错误会导致跨语言迁移伪影 |
| 响度峰值 ≥ -15 dB | 较静的参考片段也能工作，但归一化效果差 |
4. 语音设计（无需参考片段）
省略 profile_id；提供一个描述所需语音的 instruct 字符串：
generate_speech(
text="Welcome to the future of agentic systems.",
instruct="warm middle-aged female narrator, calm authoritative pace, documentary style",
)
通过 list_personalities 获取预制指示，并复制与需求匹配的指示（narrator、casual、news-anchor等）。
5. 视频配音（仅限Web界面）
MCP服务器不公开配音端点。完整的转写→翻译→重新配音→混流管道位于桌面UI（$OMNIVOICE_HOME 中的 bun run desktop）和 /dub/* REST路由之后。当用户要求配音视频时，请引导他们使用UI；本技能仅用于上述合成原语。
何时不使用OmniVoice
- 在弱硬件上进行快速英语语音生成 →
kokoro-tts体积小约10倍，在CPU上可实现2倍实时合成（参见 references/engines-comparison.md） - 最低摩擦的一次性TTS → Edge TTS无需安装或后端
- 不考虑成本的最佳质量 → ElevenLabs在英语语音的自然度上仍然领先；OmniVoice在多语言和克隆方面持平或更优
- 实时流式听写 → 使用OmniVoice桌面小部件（
⌘+⇧+Space），而非MCP服务器
参考资料
- references/engines-comparison.md — 在OmniVoice / kokoro / Voicebox / Edge TTS / ElevenLabs / 云API之间的决策树
- references/mcp-setup.md — MCP连接、后端生命周期、环境变量、故障排除
- scripts/check-health.sh —
curl /health，退出码0/1 - scripts/start-backend.sh — 在127.0.0.1:3900上启动uvicorn并带有健康探测
- scripts/stop-backend.sh — 通过
kill -TERM干净地关闭绑定的PID - scripts/record-reference.sh — 仅macOS：录制+修剪+验证用于克隆的参考片段，带可听见提示（
say+ 系统蜂鸣声），绕过终端输出缓冲
后端Swagger / OpenAPI：http://127.0.0.1:3900/docs（后端运行时）。
上游：github.com/debpalash/OmniVoice-Studio — FSL-1.1-ALv2（免费用于个人/内部/非商业用途；每个版本发布两年后自动转换为Apache-2.0）。