VoiceStudio：开源全本地语音克隆与视频配音工具部署指南

VoiceStudio 是一个完全本地运行的开源语音工作台，官方定位为"开源、全本地的 ElevenLabs 替代品"。它把语音克隆、音色设计、视频配音、语音听写、语音转写与有声书制作整合进同一个桌面应用中，默认引擎由 k2-fsa/OmniVoice 提供，官方宣称支持 646 种语言。与依赖云端 API 的商业语音服务不同，VoiceStudio 的所有推理都在你自己的硬件上完成，不上传任何音频或文本，远程服务只是可选项，使用分析也需要你主动同意。

它的工作区分为三大块：创作（克隆声音或设计自己的音色）、生产（按时轴配音视频、生成故事与有声书、批量任务）、连接（对外提供本地 API 与 MCP，供 AI Agent 调用）。你可以从默认的 VoiceStudio（OmniVoice 引擎）开始，也可以在引擎目录里切换其他引擎。整个项目以 Electron 作为唯一的桌面应用与网页界面壳，版本 0.5.3 是最后一个 Tauri 发布版，旧的 Tauri 用户需要单独安装 Electron 版本。

一、项目官方信息

二、项目背景

商业语音合成产品普遍采用云端订阅模式：你上传文本或参考音频，模型在服务商的服务器上运行，按字符计费，且语音数据要离开本机。VoiceStudio 针对的正是这一痛点——它把 TTS 推理、ASR 转写、模型管理全部搬到本地，让创作者在断网或内网环境下也能完成声音克隆与配音，同时通过 MCP 与本地 API 把这些能力暴露给 Claude Code、Codex、Cursor 等编码 Agent。

具体到工作流，VoiceStudio 把"创作—生产—连接"三层拆开：创作层负责克隆声音或用文字描述音色；生产层负责按时间轴给视频配音、把故事和有声书做成批量任务；连接层负责把能力以本地 API 和 MCP 形式开放给外部程序。你既可以在桌面界面里点选完成，也可以在无头服务器上用 Docker 跑后端、用浏览器访问网页界面，再通过脚本或 Agent 调用同一套能力。这种分层让它既能服务于不写代码的内容创作者，也能接入开发者自己的自动化管线。

它面向的不仅是开发者：视频创作者可以给多角色视频按时轴配音，播客与有声书作者可以跑批量任务，需要口述输入的用户可以用浮动小窗听写。模型权重在你首次安装某个模型时从 Hugging Face 拉取，磁盘与模型都由你自己掌控。官方提供了简体中文、日语、韩语、俄语多语言文档，国内用户按中文 README 对照操作即可。

在隐私与合规上，VoiceStudio 与云端方案有本质区别：所有合成与转写都在本机完成，产品分析采用 opt-in（基于 PostHog、仅无内容的使用元数据），首次启动会弹出同意提示，拒绝或跳过即关闭；Docker 部署里还可以设置 -e OMNIVOICE_ANALYTICS_DISABLED=1 彻底关闭分析。这意味着你可以在断网环境、内网服务器或对数据出境有严格要求的场景里使用它，而不必担心音频被上传到第三方服务器。模型管理器会为每个模型显示版本化的来源声明、证据链接与未决审查缺口，帮你判断某个音色或权重能否商用。

三、核心特性

• 语音克隆：选一个已有的音色，或录一段干净的参考音频，输入文本即可生成与参考音色一致的语音。
• 音色设计：用自然语言描述你想要的声音，由模型生成对应的合成音色。
• 视频配音：按时间轴给视频配定时语音，支持多角色配音与导出。
• 听写与转写：浮动小窗听写，以及基于 whisper.cpp 的 ASR 语音转写。
• 有声书与批量任务：把长文本批量转成语音，适合故事与有声书。
• 本地 API 与 MCP：对外提供本地 API 和 MCP 接口，让 Agent 直接调用语音能力。
• 可复用配方与监听目录：把常用流程存成配方，配合 watch folder 自动化处理。
• 多硬件加速：NVIDIA GPU（CUDA）、Apple Silicon（Metal/MPS）、AMD Radeon（Windows ROCm 可选），无独显时也能在 CPU 上完整运行。
• 手机端预览：Android 10+ 与 iOS 17+ 提供预览版，模型在手机本地运行，下载完成后离线可用。

默认的 VoiceStudio 引擎由 k2-fsa/OmniVoice 驱动，其 GGUF 量化源码构建在 Windows 与 Linux 上还可选择 Vulkan 加速；如果你不想用默认引擎，仓库内置了引擎目录（feature-catalog），可以切换包括 CosyVoice GGUF、whisper.cpp ASR 在内的其他引擎。不同引擎在硬件支持、模型大小、合成质量与延迟上差异明显，官方在性能文档里给出了各引擎的基准数据，选型时应按自己的显卡与目标语种对照，而不是盲目追求最大模型。模型全部在你本地的模型管理器里安装与卸载，升级、回滚都在同一界面完成。

四、环境要求

• 桌面系统：macOS（Apple Silicon 走 Metal 加速；Intel Mac 仅能跑界面，需连接远程后端）、Windows（10+，NVIDIA 走 CUDA，AMD 可选 ROCm）、Linux。
• GPU 支持矩阵：NVIDIA GPU（Windows / Linux，CUDA 加速）；Apple Silicon（MPS）；AMD Radeon / Ryzen AI（Windows，默认 CPU，ROCm 需手动开启）；核显或老电脑可完整使用但较慢。
• CPU 模式磁盘：CPU 安装会拉取约 5GB 的 PyTorch CPU 版；首次在 Docker 里安装模型还会下载约 2.4GB 模型权重。
• 运行发布版：只需要 curl 与 SHA-256 校验工具；从源码 --main 构建则需要 Git、Node.js 22+、Bun、Rust/Cargo 与平台构建工具。
• Windows on ARM：实验性支持，原生 ARM64 应用加 x64 模拟 Python 后端，仅 CPU。

除了桌面端，官方还提供 Android 10+ 与 iOS 17+ 的预览版手机应用：模型下载完成后在手机本地运行，可离线使用，适合外出时做短语音合成。iPhone 与 iPad 需要用你的 Apple ID 侧载 IPA；Android 则直接安装 .apk。这两个端目前都是预览阶段，模型能力与桌面端一致，但验证仍在进行中。

五、部署步骤

方式一：本地桌面安装（推荐）

macOS / Linux 一行命令安装最新 Electron 版：

# 安装最新 Electron 发布版
curl -fsSL https://voicestudio.sh/install | sh

# 安装指定版本（把 X.Y.Z 换成实际版本号）
curl -fsSL https://voicestudio.sh/install | sh -s -- --version X.Y.Z

# 从当前 main 构建并安装桌面应用
curl -fsSL https://voicestudio.sh/install | sh -s -- --main

# 卸载应用但保留你的数据
curl -fsSL https://voicestudio.sh/install | sh -s -- --uninstall

Windows 在 PowerShell 中执行：

irm https://voicestudio.sh/install.ps1 | iex

如果 voicestudio.sh/install 无法访问或返回 404，可以直接从仓库跑安装脚本：

curl -fsSL https://raw.githubusercontent.com/debpalash/VoiceStudio/main/scripts/install.sh | sh

也可以从 Releases 页面 直接下载：macOS 是 .dmg，Windows 是 .exe，Linux 是 .AppImage 或 .deb，Android 是 .apk，iPhone 是 .ipa；Linux 也可用 sudo snap install voicestudio。安装器会保留你的设置、项目与模型，不会回退到已归档的 Tauri 构建。

macOS 若提示"VoiceStudio is damaged and can't be opened"，并非下载损坏，而是 Gatekeeper 拦截了未公证的隔离应用，按官方 macOS 指南的 Gatekeeper 章节放行即可。

方式二：浏览器网页端 Docker 部署

对于无头服务器、专用 GPU 或想要"一条命令"部署的场景，官方提供 Docker 镜像：镜像内置后端，界面通过 HTTP 暴露，你在普通浏览器里打开即可使用；推理全部在容器内进行。官方镜像为 ghcr.io/debpalash/voicestudio，Docker Hub 上同名镜像 palashdeb/omnivoice-studio 内容一致。

CPU 模式启动：

docker pull ghcr.io/debpalash/voicestudio:stable

docker run -d --name omnivoice \
  -p 127.0.0.1:3900:3900 \
  -e OMNIVOICE_API_KEY="$OMNIVOICE_API_KEY" \
  -v omnivoice-data:/app/omnivoice_data \
  ghcr.io/debpalash/voicestudio:stable

NVIDIA GPU 模式（加 --gpus all）：

docker run -d --name omnivoice --gpus all \
  -p 127.0.0.1:3900:3900 \
  -e OMNIVOICE_API_KEY="$OMNIVOICE_API_KEY" \
  -v omnivoice-data:/app/omnivoice_data \
  ghcr.io/debpalash/voicestudio:stable

启动后在浏览器打开 http://localhost:3900。首次运行会下载约 2.4GB 模型权重，用 docker logs -f omnivoice 观察进度。ARM64 机器上拉普通标签可能报 no matching manifest for linux/arm64/v8，需要改用 :stable-cuda-arm64 标签；Apple Silicon 请直接用原生 macOS 应用，Linux 容器无法通过 MPS/MLX 调用苹果 GPU。

方式三：从源码运行 Electron 预览

git clone https://github.com/debpalash/VoiceStudio.git
cd VoiceStudio
bun install
bun run setup:api   # 启动前先准备 Python 依赖
bun run dev

用 bun run smoke-test 可以构建并启动一个隔离的打包版 Electron 应用，加 -- --install 可做联网的托管运行时安装检查。

六、使用方法

安装完成后打开"Voice cloning"工作区，选择一个音色（或添加一段干净的参考录音），输入文本，点击生成；首次使用某个模型时会提示你安装，按需下载即可。后端默认绑定 3900 端口，若该端口被系统保留，Electron 托管后端会自动选择下一个回环端口（每次步进 1000，最多 16 个备选），API 代理与健康检查会自动跟随。

多角色配音的典型流程是：在视频配音工作区导入视频，按时间轴切出每一段台词，为不同角色分别指定克隆音色，再逐段生成；官方提供了《多角色配音指南》与《配音导出》文档，导出时可对齐字幕时间戳。想要更有表现力的语音时，可在文本中标注情绪与停顿，走 expressive speech 流程。有声书场景则把长文本切成章节批量任务，用监听目录（watch folder）把待处理音频丢进指定文件夹即可自动跑批，配合可复用配方（recipes）把"选哪个音色、什么语速、导出什么格式"固化下来。

在终端可以用自检命令排查环境：

uv run python backend/main.py --diagnose          # 检查计算设备、ffmpeg、磁盘、模型等
uv run python backend/main.py --diagnose --deep   # 额外加载当前引擎并合成一句测试语音

--deep 会抓出"装了但跑不起来"的引擎。在图形界面里，可通过"设置 → 关于 → 运行自检"检查计算设备（CUDA/MPS/CPU）、ffmpeg、Hugging Face token、磁盘空间、数据目录权限、内存、已安装 TTS 引擎与 hub 连通性，每一项异常都会给出提示；提交 issue 前用"保存诊断包"导出 zip，里面会带上自检报告、近期错误与脱敏日志，主目录路径和 token 形态的字符串在离开本机前都会被打码。要接入 AI Agent，可在支持 skills 的 Agent 里执行 npx skills add debpalash/VoiceStudio，选择 voicestudio（音频工作流）或 voicestudio-maintainer（仓库维护）；也可以把一段官方 agent 指南直接粘贴给 Claude Code、Codex、Cursor 等让它替你完成安装与验证。

七、常见问题 FAQ

Q：macOS 打开提示"应用已损坏"怎么办？ A：这是 Gatekeeper 对未公证应用的隔离提示，不是下载损坏，按官方 macOS 指南的 Gatekeeper 章节放行即可。

Q：没有独立显卡能用吗？ A：能。核显或老电脑可完整在 CPU 上运行，只是速度慢；CPU 模式会额外拉取约 5GB 的 PyTorch CPU 版。Apple Silicon 走 Metal/MPS 加速，NVIDIA 走 CUDA，AMD Windows 可手动开启 ROCm。

Q：Docker 部署在 Apple Silicon 上拉镜像失败？ A：Linux 容器不能调用苹果 GPU，Apple Silicon 请直接用原生 macOS 应用；AMD64/ARM64 混合架构下拉普通标签可能报 no matching manifest，需改用 -cuda-arm64 标签。

Q：端口 3900 被占用怎么办？ A：Electron 托管后端会自动切换到下一个回环端口（步进 1000，最多 16 个备选），API 代理与健康检查自动跟随；Docker 模式则用 -p 自行映射。

Q：克隆别人的声音有什么注意事项？ A：项目基于 AGPL-3.0，源码可商用但有其条款；模型权重、分词器、音色与生成输出的授权是分开的。克隆声音必须获得本人许可，模型管理器会显示各模型来源的版本化授权说明。

Q：Tauri 版本还能用吗？ A：0.5.3 是最后一个 Tauri 发布版，Tauri 壳与旧界面入口已移除，现有 Tauri 用户需要单独安装 Electron 版本。

Q：第一次接触该从哪开始？ A：先在 macOS / Linux 上用一行命令安装，或在 Windows PowerShell 里跑 irm 脚本；打开后进入"Voice cloning"，选一个内置演示音色，输入一段文本点生成，按提示下载对应模型即可。不确定用哪块显卡时，先用 CPU 模式跑通，再到"设置 → 关于 → 运行自检"里确认 CUDA/MPS 是否生效。

Q：模型权重放在哪里、占多大空间？ A：模型权重在你首次安装某个模型时从 Hugging Face 拉取，存放在数据目录中；Docker 部署通过 -v omnivoice-data:/app/omnivoice_data 持久化。CPU 安装会额外拉约 5GB 的 PyTorch CPU 版，Docker 首次安装模型还会下载约 2.4GB 权重，磁盘不足时先在模型管理器里卸载不用的引擎。

八、跳转链接

• GitHub 仓库：debpalash/VoiceStudio
• 官方网站：voicestudio.sh
• 最新发布：Releases
• Docker 镜像：ghcr.io/debpalash/voicestudio
• 中文文档：README_CN
• 社区：Discord
• 问题反馈：GitHub Issues