VoiceStudio MCP 技能手册为 Agent 提供本地语音合成、声音克隆与多语言配音的完整指南【免费下载链接】VoiceStudioVoiceStudio is the open-source, fully-local ElevenLabs alternative — voice cloning, voice design, video dubbing, dictation, transcription audiobook creation in 646 languages.项目地址: https://gitcode.com/GitHub_Trending/om/VoiceStudioVoiceStudio 是一个完全本地运行的开源语音平台ElevenLabs 的开源替代品而本文聚焦于它面向 AI Agent 的 MCPModel Context Protocol接口通过generate_speech、list_voices、list_personalities、list_languages、check_health等工具Agent 可以在不联网、不申请 API Key 的前提下完成文本转语音、3 秒参考片段声音克隆、646 种语言配音与叙述生成。读完本文你将掌握 VoiceStudio MCP 服务器的安装、启动、接线、核心工作流叙述生成、克隆配方、声音设计、引擎选型决策以及常见故障排查的完整实战方案。一、VoiceStudio MCP 概览Agent 能拿到哪些能力VoiceStudio 的 MCP 服务器基于 FastMCP 实现入口位于 backend/mcp_server.py它把本地 FastAPI 后端的合成能力包装成标准的 MCP 工具与资源供 Claude Desktop、Claude Code、Cursor、OpenClaw 等任意 MCP 客户端调用。其能力边界如下工具Toolsgenerate_speech文本 → WAV 音频支持克隆或设计、list_voices枚举已保存的声音档案、list_personalities列出叙述者/休闲/新闻主播等风格预设、list_languages列出支持的 646 种语言、check_health后端状态与当前 GPU 设备。资源Resourcesvoice://{id}查询某个声音档案的元数据、history://recent最近 20 条生成历史。从 backend/mcp_server.py 的源码看实际实现的工具比文档中的清单更丰富还包含clone_voice直接把参考音频以 base64 或文件路径形式创建新声音档案和transcribe语音转文本。这意味着一个 Agent 通过 MCP 即可闭环完成听一段音频 → 克隆该声音 → 用该声音生成新台词的完整链路。# 标准启动方式stdio 传输供 Claude Desktop 等客户端使用 python -m backend.mcp_server # 远程 Agent 使用 SSE 传输默认端口 8765 python -m backend.mcp_server --sse --port 8765二、前置条件后端必须处于运行状态MCP 工具的全部请求都打到$OMNIVOICE_API_URL默认http://localhost:3900。如果 FastAPI 后端没有启动所有 MCP 工具都会返回连接错误——这是使用前最容易踩的坑。2.1 安装与初始化git clone https://gitcode.com/GitHub_Trending/om/VoiceStudio.git $OMNIVOICE_HOME cd $OMNIVOICE_HOME uv sync VIRTUAL_ENV$(pwd)/.venv uv pip install mcp[cli]其中OMNIVOICE_HOME未设置时默认指向~/VoiceStudio。uv sync在 macOS arm64 上约产生 1.6 GB 的虚拟环境mcp[cli]需要单独安装因为它不在项目锁文件中。2.2 启动与健康检查仓库中提供了三个幂等的生命周期脚本详见 .claude/skills/omnivoice/scriptsscripts/check-health.sh # 退出码 0 表示后端已就绪 scripts/start-backend.sh # 后台启动MPS/CUDA/CPU 自动检测 scripts/stop-backend.sh # 通过 kill -TERM 优雅停机从 start-backend.sh 源码可以看到它细致的边界处理启动前先探测/health已运行则直接返回 0若 3900 端口被占用但/health无响应会识别占用进程是否为残留的 uvicorn 并给出提示退出码 3绝不自动误杀未知进程随后nohup uv run uvicorn main:app --app-dir backend --host 127.0.0.1 --port 3900后台拉起并在 60 秒内每 2 秒轮询健康检查退出码 4/5 分别对应超时与进程早退。stop-backend.sh 则采用 SIGTERM 优雅停机 → 10 秒宽限 → SIGKILL 升级的三段式策略并会显式报出 EPERM 权限错误。首次合成的懒加载第一次调用generate_speech时后端会从 HuggingFace 懒下载k2-fsa/OmniVoice模型约 2.4 GB后续启动直接命中缓存无需再次下载。三、任务索引先选对工具任务工具说明验证后端是否在线check_health返回{status:ok,device:mps\|cuda\|cpu}用已保存的声音把文本转成音频generate_speech(text, profile_id)返回 base64 WAV。profile_iddemo0001是内置演示声音不克隆、纯声音设计generate_speech(text, instruct…)省略profile_id传入如warm middle-aged female narrator, calm pace的风格指令多语言叙述generate_speech(text, languagees)任意 ISO 639 语言代码或Auto列出已有声音list_voices返回 id、name、type、personality列出风格预设list_personalities返回 narrator / casual / news-anchor 等预设及其instruct文本列出支持语言list_languages共 646 种返回 20 种常用语言 总数说明对应到 backend/mcp_server.py 中generate_speech的真实签名可用的参数为参数默认值说明text必填待合成的文本languageAuto目标语言ISO 639 代码或 Auto 自动检测profile_idNone已保存声音档案 ID省略则使用当前 Agent 绑定的声音或全局默认instructNone风格指令如whisper、excited、narratorspeed1.0语速倍率范围 0.5–2.0steps16扩散步数8 快速/草稿、16 均衡、32 高质量四、常用工作流4.1 一键叙述使用演示声音# 经由 MCP 客户端调用你的 Agent 会自动完成 result generate_speech( textHello — this is VoiceStudio generating speech locally., profile_iddemo0001, languageEnglish, steps16, # 8 快速/草稿 · 16 均衡 · 32 高质量 ) # result 是 JSON包含 audio_id, generation_time_s, audio_duration_s, format, wav_base64基准参考在 Apple Silicon 的 MPS 上以 16 步扩散生成 4.2 秒音频服务端耗时约 24 秒。从 generation.py 源码可见/generate端点接收的表单字段与上述参数一一对应num_step默认 16、speed默认 1.0、profile_id可空——MCP 层与 REST 层共享同一套合成管线。4.2 把 WAV 保存到磁盘并播放工具返回的是16-bit、单声道、24 kHz的 base64 编码 PCM WAVimport base64, json payload json.loads(result_text) # 解析工具返回的 JSON open(out.wav,wb).write(base64.b64decode(payload[wav_base64]))macOS 上播放afplay out.wav转成 MP3ffmpeg -i out.wav -codec:a libmp3lame -b:a 128k out.mp3。进阶从 backend/mcp_server.py 可以看到generate_speech的返回值还受环境变量OMNIVOICE_MCP_OUTPUT_MODE控制默认resourcesfiles模式返回渲染产物的 URL如api_base/audio/audio_id.wav并在配置了OMNIVOICE_MCP_BASE_PATH时把 WAV 直接写入该目录both模式两者都返回。对于 LLM Agentfiles模式更优——避免大段 base64 音频进入上下文造成 token 浪费。4.3 声音克隆——端到端配方克隆需要一个3–10 秒的干净参考片段模型会把它编码为说话人嵌入speaker embedding。注意MCP 服务器本身不暴露档案创建接口它只读取已有档案创建档案有两条路径。路径 A —— 自带辅助脚本macOS推荐用于全新克隆scripts/record-reference.sh ~/Downloads/my-ref.wav 12 1 # 参数: 输出路径 原始录制时长(秒) 麦克风索引 # 默认麦克风索引1MacBook 内置枚举设备 # ffmpeg -f avfoundation -list_devices true -i 这个脚本解决了 macOS 终端输出缓冲导致的提示文字晚到问题用say语音倒计时 系统提示音Ping.aiff/Pop.aiff提供可听见的开始/结束提示先录一段更长的原始窗口再用silenceremove atrim裁出约 10 秒语音自动回放供验证最后打印下一步curl命令。脚本还内置了三层质量护栏详见 record-reference.sh录制静音检测平均音量 -50 dB 直接判定麦克风权限被拒并退出码 3、裁剪后时长校验 2 秒判定无效并退出码 4、音量检测输出。该脚本为 macOS 专用依赖 avfoundation、say、系统音效Linux 可用arecord espeak aplay组合替代。路径 B —— 手动录制与裁剪# 1. 录制单声道、24 kHz 原生采样率——与模型内部采样率一致 ffmpeg -f avfoundation -i :1 -t 12 -ac 1 -ar 24000 raw.wav # 2. 去除开头静音 截取前 10 秒语音 ffmpeg -i raw.wav \ -af silenceremovestart_periods1:start_silence0.05:start_threshold-40dB,atrimend10 \ -ac 1 -ar 24000 ref.wav # 3. 验证 ffmpeg -i ref.wav -af volumedetect -f null - 21 | grep volume # max 应 -20 dB afplay ref.wavPOST 到 /profiles 创建档案multipart/form-data必填字段name、ref_audiocurl -X POST http://127.0.0.1:3900/profiles \ -F namecarlos-clone \ -F ref_audioref.wav \ -F ref_textThe exact text spoken in the clip \ -F languageEnglish \ | python3 -m json.tool # 返回 { id: abc12345, name: carlos-clone }从 profiles.py 源码看POST /profiles支持kind字段clone或designclone 类型必须有ref_audiodesign 类型则基于vd_states声音设计器类别选择两者缺失对应字段都会返回 422。档案创建后将其id作为profile_id传给generate_speech经 MCP或直接POST /generate即可使用。档案持久化在 SQLite 参考音频文件中路径为~/Library/Application Support/OmniVoice/voices/id.ext后端保留上传文件的扩展名上传 WAV 存为.wavMP3 存为.mp3等重启后端后状态依然保留。参考片段质量要点直接影响克隆音质因素为什么重要单一说话人混合说话人会使嵌入模糊干净语音、无音乐/噪声模型会把噪声一并嵌入自然韵律避免念绕口令扩散采样复刻的是韵律而不只是音色3–10 秒是最佳区间小于 3 秒信息不足大于 10 秒只增加算力不提升质量ref_text与实际台词一致改善对齐尤其对嘈杂参考有效language正确语言错误会产生跨语种迁移伪影峰值响度 ≥ -15 dB过静参考虽可用但归一化效果差此外MCP 层的clone_voice工具见 backend/mcp_server.py接受 base64 或ref_audio_path两种输入并会先嗅探音频容器魔数flac/mp3/ogg/m4a/wav来确定扩展名避免MP3 存成 .wav导致的后续解码失败。4.4 声音设计无需参考片段跳过profile_id传入描述期望声音的instruct字符串generate_speech( textWelcome to the future of agentic systems., instructwarm middle-aged female narrator, calm authoritative pace, documentary style, )通过list_personalities可以拿到现成的 instruct 预设narrator、casual、news-anchor 等直接复制与需求匹配的那条即可。4.5 视频配音仅 Web UIMCP 服务器不暴露配音端点。完整的转写 → 翻译 → 重新配音 → 混流管线运行在桌面 UIbun run desktop与/dub/*REST 路由之后。当用户要求给视频配音时应引导其使用 UI本技能只覆盖上述合成原语。五、MCP 接线与后端生命周期5.1 MCP 客户端配置将以下片段写入 MCP 客户端配置Claude Desktop、Claude Code 的~/.claude.json、Cursor、OpenClaw 等把OMNIVOICE_HOME替换为绝对路径{ mcpServers: { omnivoice: { type: stdio, command: uv, args: [ --directory, OMNIVOICE_HOME, run, python, -m, backend.mcp_server ], env: { OMNIVOICE_API_URL: http://localhost:3900 } } } }重启 MCP 客户端后配置才生效——MCP 服务器只在客户端启动时创建会话内的编辑不会热重载。兼容性提示mcp SDK ≥ 1.10若报TypeError: FastMCP.__init__() got an unexpected keyword argument version说明检出版本早于修复提交version/description参数在新版 SDK 中被移除。在 backend/mcp_server.py 中将其替换为instructions(…)即可当前仓库已使用新的instructions写法。5.2 后端生命周期管理# 前台运行日志在终端 cd $OMNIVOICE_HOME uv run uvicorn main:app --app-dir backend --host 127.0.0.1 --port 3900 # 后台运行使用技能自带脚本 scripts/start-backend.sh # 幂等 scripts/check-health.sh # 退出码 0/1 scripts/stop-backend.sh # 优雅 SIGTERM127.0.0.1让 API 仅限本机访问项目package.json默认使用0.0.0.0会在所有网卡暴露 API个人使用场景下范围过宽。首次启动会针对 SQLite 设置库data_dir/omnivoice.db执行 alembic 迁移幂等、可重复执行。模型缓存路径因操作系统而异macOS/Linux 为~/.cache/huggingface/hub/Windows 为%LOCALAPPDATA%\OmniVoice\hf_cacheVoiceStudio 通过backend/core/config.py重定向避免缓存落在系统盘根目录。空闲行为GET /system/info暴露idle_timeout_seconds: 900见 system.py。连续 15 分钟无合成请求后扩散模型会从 GPU 内存卸载但 FastAPI 服务保持在线下一次调用需付出约 5–10 秒的重新预热成本。5.3 环境变量一览变量默认值作用OMNIVOICE_HOME~/VoiceStudioVoiceStudio 仓库克隆位置本技能脚本使用OMNIVOICE_API_URLhttp://localhost:3900MCP 服务器指向的后端地址OMNIVOICE_TTS_BACKENDomnivoice切换引擎cosyvoice、mlx-audio、voxcpm2、moss-tts-nano、kittenttsHF_TOKEN无仅当使用受门控的 pyannote 说话人分离模型时需要基础 TTS 不需要MCP 层还有两个进阶变量见 backend/mcp_server.py 源码OMNIVOICE_MCP_OUTPUT_MODEresources/files/both默认resources与OMNIVOICE_MCP_BASE_PATHAgent 可读取音频、接收文件的唯一目录是文件型输入的安全边界——未配置时一切路径型参数都会被拒绝路径经 realpath 归一化且禁止符号链接逃逸OMNIVOICE_MCP_TIMEOUT_S默认 120控制工具等待后端 POST 的超时时间。5.4 故障排查速查表症状原因修复MCP 工具返回连接错误后端未运行scripts/start-backend.shaddress already in use3900 端口有残留 uvicornlsof -nP -iTCP:3900 -sTCP:LISTEN→kill -TERM pidFastMCP.__init__() got unexpected keyword argument versionmcp SDK ≥ 1.10 移除了version/description参数更新检出或手动将 backend/mcp_server.py 改为instructions(…)首次调用卡 5–10 分钟正在从 HuggingFace 下载模型观察~/.cache/huggingface/hub/models--k2-fsa--OmniVoice/增长/health返回 500alembic 迁移失败检查data_dir/crash_log.txt声音档案找不到profile_id无效或尚未创建先调list_voices获取合法 ID启动时pyannote.audio报错缺少分离模型所需HF_TOKEN仅影响配音管线基础 TTS 不受影响Apple Silicon 上生成缓慢扩散模型回退到 CPU/health应返回device:mps把steps从 16 降到 8 用于草稿5.5 干净卸载scripts/stop-backend.sh # 优雅停机 # 卸载: 删除 $OMNIVOICE_HOME 与 ~/.cache/huggingface/hub/models--k2-fsa--OmniVoice # 同时从 MCP 客户端配置中移除 omnivoice 条目用户档案与历史记录保存在平台数据目录macOS~/Library/Application Support/OmniVoice/Linux~/.local/share/VoiceStudio/。如果重装后想保留已保存的声音档案请先备份该目录。六、引擎选型什么时候用 VoiceStudio什么时候用别的6.1 决策树是否需要声音克隆 ├─ 是 → VoiceStudio3 秒参考片段、零样本、646 种语言 └─ 否 → 是否为非英语 ├─ 是 → VoiceStudio646 语言或 Edge TTS子集、云端 └─ 否英语→ 是否需要隐私不联网 ├─ 是 → │ 有 GPU 吗 │ ├─ 是CUDA/MPS→ VoiceStudio质量最佳或 Voicebox │ └─ 否仅 CPU→ kokoro-ttsCPU 上 2× 实时或 VoiceStudio on CPU慢 └─ 否可上云→ 预算无上限 ├─ 是 → ElevenLabs润色最佳其次 OpenAI TTS └─ 否 → Edge TTS免费、非官方、MS Azure 神经语音6.2 全量对比引擎质量克隆多语言成本隐私安装最适合VoiceStudio8-9/10✅ 3 秒参考646 种语言免费本地Bun uv 安装多语言、克隆、隐私敏感场景ElevenLabs9-10/10✅ 3 秒参考32 种语言$5-330/月云端API Key最佳英语润色、最快云端 TTSVoicebox (Qwen3-TTS)8-9/10✅多免费本地DockerVoiceStudio 的自托管替代Voicebox (LuxTTS)7/10❌多免费本地DockerCPU 上 150× 实时kokoro-tts7-8/10❌多有限免费本地pipCPU 上快速英语叙述mlx-audio7-8/10视情况多免费本地pipApple Silicon 原生14 子引擎Edge TTS7-8/10❌50免费*云端pip零摩擦的一次性使用OpenAI TTS8/10❌多$0.015/千字符云端API Key便捷、便宜、质量好Google Cloud TTS8/10❌多$4/百万字符 (WaveNet)云端GCP 项目大额免费额度每月 1M 字符*Edge TTS 非官方服务微软随时可能封锁。6.3 VoiceStudio 的显著优势场景声音克隆——3 秒参考片段、零样本、无需微调。ElevenLabs 是唯一对手而 VoiceStudio 免费且本地运行。长尾语言——支持 646 种ElevenLabs 覆盖 32 种其余引擎更少。隐私/合规——数据不出本机。ElevenLabs 和 OpenAI 会把音频发往其服务器。无 API Key 约束——本地优先无需注册账号。海量批量生成无计费风险——ElevenLabs 按字符计费VoiceStudio 任意体量免费。6.4 VoiceStudio 不占优的场景最低摩擦的一次性 TTS——需要后端安装 约 3 GB 模型 uvicorn 启动Edge TTS 或 OpenAI TTS 一条命令即可。弱硬件上的快速英语叙述——kokoro-tts 约 30 MB对比 VoiceStudio 的 2.4 GBCPU 上可达 2× 实时。博客批量叙述优先用 kokoro除非需要克隆。流式实时 TTS——VoiceStudio 基于扩散模型、非流式真正需要流式请用 Edge TTS 或云 API。Apple Silicon 专属的特定音色——mlx-audio内置 14 个引擎Kokoro、CSM、Dia、Qwen3-TTS 等可能更贴合某个特定音色。6.5 与内容管线的组合VoiceStudio 位于视觉资产生成与视频组装之间研究 → 文案 → 视觉资产 → 音频VoiceStudio → 视频组装 → 分发博客音频叙述的默认选择英语、无需克隆、要快→ kokoro-ttsCPU 成本低英语、想要特定克隆声音→ VoiceStudio 已保存档案非英语→ VoiceStudio一次性、零安装→ Edge TTS对于原本依赖 ElevenLabs 的 Remotion 视频管线VoiceStudio 可以关闭最后一个云依赖——配合任意本地图像/视频生成器即可搭建完全自托管的媒体生产栈。七、资源清单与进一步阅读.claude/skills/omnivoice/references/engines-comparison.md —— VoiceStudio / kokoro / Voicebox / Edge TTS / ElevenLabs / 云 API 的完整决策树.claude/skills/omnivoice/references/mcp-setup.md —— MCP 接线、后端生命周期、环境变量、故障排查.claude/skills/omnivoice/scripts/check-health.sh ——curl /health退出码 0/1.claude/skills/omnivoice/scripts/start-backend.sh —— 在 127.0.0.1:3900 启动 uvicorn 并做健康探测.claude/skills/omnivoice/scripts/stop-backend.sh —— 通过kill -TERM优雅关闭绑定进程.claude/skills/omnivoice/scripts/record-reference.sh —— macOS 专用录制 裁剪 验证克隆参考片段用say 系统提示音绕过终端输出缓冲后端 Swagger / OpenAPI 文档位于http://127.0.0.1:3900/docs后端运行时可用。该应用采用 AGPL-3.0-only 协议可选引擎与下载的模型各自保留其许可证详见仓库根目录的 LICENSE-NOTICE.md。结合本文与 backend/mcp_server.py 源码可以确认VoiceStudio 的 MCP 层是一个薄代理它把generate_speech等调用翻译成对本地 FastAPI 后端的表单 POST并负责任何 Agent 侧的安全边界文件路径白名单、base64 输入上限 200 MB、输出模式切换。理解这一层之后无论是接入新 Agent 框架、调整输出模式还是排查连接问题你都有了完整的行动地图。【免费下载链接】VoiceStudioVoiceStudio is the open-source, fully-local ElevenLabs alternative — voice cloning, voice design, video dubbing, dictation, transcription audiobook creation in 646 languages.项目地址: https://gitcode.com/GitHub_Trending/om/VoiceStudio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
VoiceStudio MCP 技能手册：为 Agent 提供本地语音合成、声音克隆与多语言配音的完整指南
VoiceStudio MCP 技能手册为 Agent 提供本地语音合成、声音克隆与多语言配音的完整指南【免费下载链接】VoiceStudioVoiceStudio is the open-source, fully-local ElevenLabs alternative — voice cloning, voice design, video dubbing, dictation, transcription audiobook creation in 646 languages.项目地址: https://gitcode.com/GitHub_Trending/om/VoiceStudioVoiceStudio 是一个完全本地运行的开源语音平台ElevenLabs 的开源替代品而本文聚焦于它面向 AI Agent 的 MCPModel Context Protocol接口通过generate_speech、list_voices、list_personalities、list_languages、check_health等工具Agent 可以在不联网、不申请 API Key 的前提下完成文本转语音、3 秒参考片段声音克隆、646 种语言配音与叙述生成。读完本文你将掌握 VoiceStudio MCP 服务器的安装、启动、接线、核心工作流叙述生成、克隆配方、声音设计、引擎选型决策以及常见故障排查的完整实战方案。一、VoiceStudio MCP 概览Agent 能拿到哪些能力VoiceStudio 的 MCP 服务器基于 FastMCP 实现入口位于 backend/mcp_server.py它把本地 FastAPI 后端的合成能力包装成标准的 MCP 工具与资源供 Claude Desktop、Claude Code、Cursor、OpenClaw 等任意 MCP 客户端调用。其能力边界如下工具Toolsgenerate_speech文本 → WAV 音频支持克隆或设计、list_voices枚举已保存的声音档案、list_personalities列出叙述者/休闲/新闻主播等风格预设、list_languages列出支持的 646 种语言、check_health后端状态与当前 GPU 设备。资源Resourcesvoice://{id}查询某个声音档案的元数据、history://recent最近 20 条生成历史。从 backend/mcp_server.py 的源码看实际实现的工具比文档中的清单更丰富还包含clone_voice直接把参考音频以 base64 或文件路径形式创建新声音档案和transcribe语音转文本。这意味着一个 Agent 通过 MCP 即可闭环完成听一段音频 → 克隆该声音 → 用该声音生成新台词的完整链路。# 标准启动方式stdio 传输供 Claude Desktop 等客户端使用 python -m backend.mcp_server # 远程 Agent 使用 SSE 传输默认端口 8765 python -m backend.mcp_server --sse --port 8765二、前置条件后端必须处于运行状态MCP 工具的全部请求都打到$OMNIVOICE_API_URL默认http://localhost:3900。如果 FastAPI 后端没有启动所有 MCP 工具都会返回连接错误——这是使用前最容易踩的坑。2.1 安装与初始化git clone https://gitcode.com/GitHub_Trending/om/VoiceStudio.git $OMNIVOICE_HOME cd $OMNIVOICE_HOME uv sync VIRTUAL_ENV$(pwd)/.venv uv pip install mcp[cli]其中OMNIVOICE_HOME未设置时默认指向~/VoiceStudio。uv sync在 macOS arm64 上约产生 1.6 GB 的虚拟环境mcp[cli]需要单独安装因为它不在项目锁文件中。2.2 启动与健康检查仓库中提供了三个幂等的生命周期脚本详见 .claude/skills/omnivoice/scriptsscripts/check-health.sh # 退出码 0 表示后端已就绪 scripts/start-backend.sh # 后台启动MPS/CUDA/CPU 自动检测 scripts/stop-backend.sh # 通过 kill -TERM 优雅停机从 start-backend.sh 源码可以看到它细致的边界处理启动前先探测/health已运行则直接返回 0若 3900 端口被占用但/health无响应会识别占用进程是否为残留的 uvicorn 并给出提示退出码 3绝不自动误杀未知进程随后nohup uv run uvicorn main:app --app-dir backend --host 127.0.0.1 --port 3900后台拉起并在 60 秒内每 2 秒轮询健康检查退出码 4/5 分别对应超时与进程早退。stop-backend.sh 则采用 SIGTERM 优雅停机 → 10 秒宽限 → SIGKILL 升级的三段式策略并会显式报出 EPERM 权限错误。首次合成的懒加载第一次调用generate_speech时后端会从 HuggingFace 懒下载k2-fsa/OmniVoice模型约 2.4 GB后续启动直接命中缓存无需再次下载。三、任务索引先选对工具任务工具说明验证后端是否在线check_health返回{status:ok,device:mps\|cuda\|cpu}用已保存的声音把文本转成音频generate_speech(text, profile_id)返回 base64 WAV。profile_iddemo0001是内置演示声音不克隆、纯声音设计generate_speech(text, instruct…)省略profile_id传入如warm middle-aged female narrator, calm pace的风格指令多语言叙述generate_speech(text, languagees)任意 ISO 639 语言代码或Auto列出已有声音list_voices返回 id、name、type、personality列出风格预设list_personalities返回 narrator / casual / news-anchor 等预设及其instruct文本列出支持语言list_languages共 646 种返回 20 种常用语言 总数说明对应到 backend/mcp_server.py 中generate_speech的真实签名可用的参数为参数默认值说明text必填待合成的文本languageAuto目标语言ISO 639 代码或 Auto 自动检测profile_idNone已保存声音档案 ID省略则使用当前 Agent 绑定的声音或全局默认instructNone风格指令如whisper、excited、narratorspeed1.0语速倍率范围 0.5–2.0steps16扩散步数8 快速/草稿、16 均衡、32 高质量四、常用工作流4.1 一键叙述使用演示声音# 经由 MCP 客户端调用你的 Agent 会自动完成 result generate_speech( textHello — this is VoiceStudio generating speech locally., profile_iddemo0001, languageEnglish, steps16, # 8 快速/草稿 · 16 均衡 · 32 高质量 ) # result 是 JSON包含 audio_id, generation_time_s, audio_duration_s, format, wav_base64基准参考在 Apple Silicon 的 MPS 上以 16 步扩散生成 4.2 秒音频服务端耗时约 24 秒。从 generation.py 源码可见/generate端点接收的表单字段与上述参数一一对应num_step默认 16、speed默认 1.0、profile_id可空——MCP 层与 REST 层共享同一套合成管线。4.2 把 WAV 保存到磁盘并播放工具返回的是16-bit、单声道、24 kHz的 base64 编码 PCM WAVimport base64, json payload json.loads(result_text) # 解析工具返回的 JSON open(out.wav,wb).write(base64.b64decode(payload[wav_base64]))macOS 上播放afplay out.wav转成 MP3ffmpeg -i out.wav -codec:a libmp3lame -b:a 128k out.mp3。进阶从 backend/mcp_server.py 可以看到generate_speech的返回值还受环境变量OMNIVOICE_MCP_OUTPUT_MODE控制默认resourcesfiles模式返回渲染产物的 URL如api_base/audio/audio_id.wav并在配置了OMNIVOICE_MCP_BASE_PATH时把 WAV 直接写入该目录both模式两者都返回。对于 LLM Agentfiles模式更优——避免大段 base64 音频进入上下文造成 token 浪费。4.3 声音克隆——端到端配方克隆需要一个3–10 秒的干净参考片段模型会把它编码为说话人嵌入speaker embedding。注意MCP 服务器本身不暴露档案创建接口它只读取已有档案创建档案有两条路径。路径 A —— 自带辅助脚本macOS推荐用于全新克隆scripts/record-reference.sh ~/Downloads/my-ref.wav 12 1 # 参数: 输出路径 原始录制时长(秒) 麦克风索引 # 默认麦克风索引1MacBook 内置枚举设备 # ffmpeg -f avfoundation -list_devices true -i 这个脚本解决了 macOS 终端输出缓冲导致的提示文字晚到问题用say语音倒计时 系统提示音Ping.aiff/Pop.aiff提供可听见的开始/结束提示先录一段更长的原始窗口再用silenceremove atrim裁出约 10 秒语音自动回放供验证最后打印下一步curl命令。脚本还内置了三层质量护栏详见 record-reference.sh录制静音检测平均音量 -50 dB 直接判定麦克风权限被拒并退出码 3、裁剪后时长校验 2 秒判定无效并退出码 4、音量检测输出。该脚本为 macOS 专用依赖 avfoundation、say、系统音效Linux 可用arecord espeak aplay组合替代。路径 B —— 手动录制与裁剪# 1. 录制单声道、24 kHz 原生采样率——与模型内部采样率一致 ffmpeg -f avfoundation -i :1 -t 12 -ac 1 -ar 24000 raw.wav # 2. 去除开头静音 截取前 10 秒语音 ffmpeg -i raw.wav \ -af silenceremovestart_periods1:start_silence0.05:start_threshold-40dB,atrimend10 \ -ac 1 -ar 24000 ref.wav # 3. 验证 ffmpeg -i ref.wav -af volumedetect -f null - 21 | grep volume # max 应 -20 dB afplay ref.wavPOST 到 /profiles 创建档案multipart/form-data必填字段name、ref_audiocurl -X POST http://127.0.0.1:3900/profiles \ -F namecarlos-clone \ -F ref_audioref.wav \ -F ref_textThe exact text spoken in the clip \ -F languageEnglish \ | python3 -m json.tool # 返回 { id: abc12345, name: carlos-clone }从 profiles.py 源码看POST /profiles支持kind字段clone或designclone 类型必须有ref_audiodesign 类型则基于vd_states声音设计器类别选择两者缺失对应字段都会返回 422。档案创建后将其id作为profile_id传给generate_speech经 MCP或直接POST /generate即可使用。档案持久化在 SQLite 参考音频文件中路径为~/Library/Application Support/OmniVoice/voices/id.ext后端保留上传文件的扩展名上传 WAV 存为.wavMP3 存为.mp3等重启后端后状态依然保留。参考片段质量要点直接影响克隆音质因素为什么重要单一说话人混合说话人会使嵌入模糊干净语音、无音乐/噪声模型会把噪声一并嵌入自然韵律避免念绕口令扩散采样复刻的是韵律而不只是音色3–10 秒是最佳区间小于 3 秒信息不足大于 10 秒只增加算力不提升质量ref_text与实际台词一致改善对齐尤其对嘈杂参考有效language正确语言错误会产生跨语种迁移伪影峰值响度 ≥ -15 dB过静参考虽可用但归一化效果差此外MCP 层的clone_voice工具见 backend/mcp_server.py接受 base64 或ref_audio_path两种输入并会先嗅探音频容器魔数flac/mp3/ogg/m4a/wav来确定扩展名避免MP3 存成 .wav导致的后续解码失败。4.4 声音设计无需参考片段跳过profile_id传入描述期望声音的instruct字符串generate_speech( textWelcome to the future of agentic systems., instructwarm middle-aged female narrator, calm authoritative pace, documentary style, )通过list_personalities可以拿到现成的 instruct 预设narrator、casual、news-anchor 等直接复制与需求匹配的那条即可。4.5 视频配音仅 Web UIMCP 服务器不暴露配音端点。完整的转写 → 翻译 → 重新配音 → 混流管线运行在桌面 UIbun run desktop与/dub/*REST 路由之后。当用户要求给视频配音时应引导其使用 UI本技能只覆盖上述合成原语。五、MCP 接线与后端生命周期5.1 MCP 客户端配置将以下片段写入 MCP 客户端配置Claude Desktop、Claude Code 的~/.claude.json、Cursor、OpenClaw 等把OMNIVOICE_HOME替换为绝对路径{ mcpServers: { omnivoice: { type: stdio, command: uv, args: [ --directory, OMNIVOICE_HOME, run, python, -m, backend.mcp_server ], env: { OMNIVOICE_API_URL: http://localhost:3900 } } } }重启 MCP 客户端后配置才生效——MCP 服务器只在客户端启动时创建会话内的编辑不会热重载。兼容性提示mcp SDK ≥ 1.10若报TypeError: FastMCP.__init__() got an unexpected keyword argument version说明检出版本早于修复提交version/description参数在新版 SDK 中被移除。在 backend/mcp_server.py 中将其替换为instructions(…)即可当前仓库已使用新的instructions写法。5.2 后端生命周期管理# 前台运行日志在终端 cd $OMNIVOICE_HOME uv run uvicorn main:app --app-dir backend --host 127.0.0.1 --port 3900 # 后台运行使用技能自带脚本 scripts/start-backend.sh # 幂等 scripts/check-health.sh # 退出码 0/1 scripts/stop-backend.sh # 优雅 SIGTERM127.0.0.1让 API 仅限本机访问项目package.json默认使用0.0.0.0会在所有网卡暴露 API个人使用场景下范围过宽。首次启动会针对 SQLite 设置库data_dir/omnivoice.db执行 alembic 迁移幂等、可重复执行。模型缓存路径因操作系统而异macOS/Linux 为~/.cache/huggingface/hub/Windows 为%LOCALAPPDATA%\OmniVoice\hf_cacheVoiceStudio 通过backend/core/config.py重定向避免缓存落在系统盘根目录。空闲行为GET /system/info暴露idle_timeout_seconds: 900见 system.py。连续 15 分钟无合成请求后扩散模型会从 GPU 内存卸载但 FastAPI 服务保持在线下一次调用需付出约 5–10 秒的重新预热成本。5.3 环境变量一览变量默认值作用OMNIVOICE_HOME~/VoiceStudioVoiceStudio 仓库克隆位置本技能脚本使用OMNIVOICE_API_URLhttp://localhost:3900MCP 服务器指向的后端地址OMNIVOICE_TTS_BACKENDomnivoice切换引擎cosyvoice、mlx-audio、voxcpm2、moss-tts-nano、kittenttsHF_TOKEN无仅当使用受门控的 pyannote 说话人分离模型时需要基础 TTS 不需要MCP 层还有两个进阶变量见 backend/mcp_server.py 源码OMNIVOICE_MCP_OUTPUT_MODEresources/files/both默认resources与OMNIVOICE_MCP_BASE_PATHAgent 可读取音频、接收文件的唯一目录是文件型输入的安全边界——未配置时一切路径型参数都会被拒绝路径经 realpath 归一化且禁止符号链接逃逸OMNIVOICE_MCP_TIMEOUT_S默认 120控制工具等待后端 POST 的超时时间。5.4 故障排查速查表症状原因修复MCP 工具返回连接错误后端未运行scripts/start-backend.shaddress already in use3900 端口有残留 uvicornlsof -nP -iTCP:3900 -sTCP:LISTEN→kill -TERM pidFastMCP.__init__() got unexpected keyword argument versionmcp SDK ≥ 1.10 移除了version/description参数更新检出或手动将 backend/mcp_server.py 改为instructions(…)首次调用卡 5–10 分钟正在从 HuggingFace 下载模型观察~/.cache/huggingface/hub/models--k2-fsa--OmniVoice/增长/health返回 500alembic 迁移失败检查data_dir/crash_log.txt声音档案找不到profile_id无效或尚未创建先调list_voices获取合法 ID启动时pyannote.audio报错缺少分离模型所需HF_TOKEN仅影响配音管线基础 TTS 不受影响Apple Silicon 上生成缓慢扩散模型回退到 CPU/health应返回device:mps把steps从 16 降到 8 用于草稿5.5 干净卸载scripts/stop-backend.sh # 优雅停机 # 卸载: 删除 $OMNIVOICE_HOME 与 ~/.cache/huggingface/hub/models--k2-fsa--OmniVoice # 同时从 MCP 客户端配置中移除 omnivoice 条目用户档案与历史记录保存在平台数据目录macOS~/Library/Application Support/OmniVoice/Linux~/.local/share/VoiceStudio/。如果重装后想保留已保存的声音档案请先备份该目录。六、引擎选型什么时候用 VoiceStudio什么时候用别的6.1 决策树是否需要声音克隆 ├─ 是 → VoiceStudio3 秒参考片段、零样本、646 种语言 └─ 否 → 是否为非英语 ├─ 是 → VoiceStudio646 语言或 Edge TTS子集、云端 └─ 否英语→ 是否需要隐私不联网 ├─ 是 → │ 有 GPU 吗 │ ├─ 是CUDA/MPS→ VoiceStudio质量最佳或 Voicebox │ └─ 否仅 CPU→ kokoro-ttsCPU 上 2× 实时或 VoiceStudio on CPU慢 └─ 否可上云→ 预算无上限 ├─ 是 → ElevenLabs润色最佳其次 OpenAI TTS └─ 否 → Edge TTS免费、非官方、MS Azure 神经语音6.2 全量对比引擎质量克隆多语言成本隐私安装最适合VoiceStudio8-9/10✅ 3 秒参考646 种语言免费本地Bun uv 安装多语言、克隆、隐私敏感场景ElevenLabs9-10/10✅ 3 秒参考32 种语言$5-330/月云端API Key最佳英语润色、最快云端 TTSVoicebox (Qwen3-TTS)8-9/10✅多免费本地DockerVoiceStudio 的自托管替代Voicebox (LuxTTS)7/10❌多免费本地DockerCPU 上 150× 实时kokoro-tts7-8/10❌多有限免费本地pipCPU 上快速英语叙述mlx-audio7-8/10视情况多免费本地pipApple Silicon 原生14 子引擎Edge TTS7-8/10❌50免费*云端pip零摩擦的一次性使用OpenAI TTS8/10❌多$0.015/千字符云端API Key便捷、便宜、质量好Google Cloud TTS8/10❌多$4/百万字符 (WaveNet)云端GCP 项目大额免费额度每月 1M 字符*Edge TTS 非官方服务微软随时可能封锁。6.3 VoiceStudio 的显著优势场景声音克隆——3 秒参考片段、零样本、无需微调。ElevenLabs 是唯一对手而 VoiceStudio 免费且本地运行。长尾语言——支持 646 种ElevenLabs 覆盖 32 种其余引擎更少。隐私/合规——数据不出本机。ElevenLabs 和 OpenAI 会把音频发往其服务器。无 API Key 约束——本地优先无需注册账号。海量批量生成无计费风险——ElevenLabs 按字符计费VoiceStudio 任意体量免费。6.4 VoiceStudio 不占优的场景最低摩擦的一次性 TTS——需要后端安装 约 3 GB 模型 uvicorn 启动Edge TTS 或 OpenAI TTS 一条命令即可。弱硬件上的快速英语叙述——kokoro-tts 约 30 MB对比 VoiceStudio 的 2.4 GBCPU 上可达 2× 实时。博客批量叙述优先用 kokoro除非需要克隆。流式实时 TTS——VoiceStudio 基于扩散模型、非流式真正需要流式请用 Edge TTS 或云 API。Apple Silicon 专属的特定音色——mlx-audio内置 14 个引擎Kokoro、CSM、Dia、Qwen3-TTS 等可能更贴合某个特定音色。6.5 与内容管线的组合VoiceStudio 位于视觉资产生成与视频组装之间研究 → 文案 → 视觉资产 → 音频VoiceStudio → 视频组装 → 分发博客音频叙述的默认选择英语、无需克隆、要快→ kokoro-ttsCPU 成本低英语、想要特定克隆声音→ VoiceStudio 已保存档案非英语→ VoiceStudio一次性、零安装→ Edge TTS对于原本依赖 ElevenLabs 的 Remotion 视频管线VoiceStudio 可以关闭最后一个云依赖——配合任意本地图像/视频生成器即可搭建完全自托管的媒体生产栈。七、资源清单与进一步阅读.claude/skills/omnivoice/references/engines-comparison.md —— VoiceStudio / kokoro / Voicebox / Edge TTS / ElevenLabs / 云 API 的完整决策树.claude/skills/omnivoice/references/mcp-setup.md —— MCP 接线、后端生命周期、环境变量、故障排查.claude/skills/omnivoice/scripts/check-health.sh ——curl /health退出码 0/1.claude/skills/omnivoice/scripts/start-backend.sh —— 在 127.0.0.1:3900 启动 uvicorn 并做健康探测.claude/skills/omnivoice/scripts/stop-backend.sh —— 通过kill -TERM优雅关闭绑定进程.claude/skills/omnivoice/scripts/record-reference.sh —— macOS 专用录制 裁剪 验证克隆参考片段用say 系统提示音绕过终端输出缓冲后端 Swagger / OpenAPI 文档位于http://127.0.0.1:3900/docs后端运行时可用。该应用采用 AGPL-3.0-only 协议可选引擎与下载的模型各自保留其许可证详见仓库根目录的 LICENSE-NOTICE.md。结合本文与 backend/mcp_server.py 源码可以确认VoiceStudio 的 MCP 层是一个薄代理它把generate_speech等调用翻译成对本地 FastAPI 后端的表单 POST并负责任何 Agent 侧的安全边界文件路径白名单、base64 输入上限 200 MB、输出模式切换。理解这一层之后无论是接入新 Agent 框架、调整输出模式还是排查连接问题你都有了完整的行动地图。【免费下载链接】VoiceStudioVoiceStudio is the open-source, fully-local ElevenLabs alternative — voice cloning, voice design, video dubbing, dictation, transcription audiobook creation in 646 languages.项目地址: https://gitcode.com/GitHub_Trending/om/VoiceStudio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考