官方把硬件要求拆成「最小」与「推荐」两列，并强调需求随引擎变化，这组数字覆盖的是默认本地工作流。真正卡住大多数人的是两条：操作系统版本和显存。

1. 平台——macOS 13.3 及以上的 Apple Silicon；Windows 10/11 x64；Linux x86_64 需要 glibc 2.39 及以上。Intel Mac 跑不了本地 Python 后端（当前 PyTorch wheel 不可用），官方给的出路是连远程 backend。
2. 内存与磁盘——RAM 最小 8 GB、推荐 16 GB 以上；磁盘最小 10 GB 可用空间、推荐 20 GB 以上 SSD。模型权重是要落到你硬盘上的。
3. 算力——GPU 是可选的，CPU 模式受支持。要用 GPU：加速工作的 VRAM 下限 4 GB，默认多阶段工作流建议 8 GB 以上，较大的可选引擎会要 12 到 16 GB 甚至更多。CUDA、Apple Silicon 的 MPS/MLX、Linux 上的 ROCm、CPU 都能路由；ROCm 仅 Linux 且需显式开启，Windows 上的 AMD/Ryzen AI 走 CPU。
4. 源码运行才需要——Node 20 及以上或 Bun，外加 Python 3.11 及以上（推荐 3.11 或 3.12）。装桌面应用的话这些都不用碰。

官方推荐的路径只有一句：从 latest release 下包，再看对应平台的安装指南。三种装法各有适用场景，Docker 那条命令是原文照抄。

docker run -d -p 127.0.0.1:3900:3900 -v omnivoice-data:/app/omnivoice_data --name voicestudio palashdeb/omnivoice-studio:stable

git clone https://github.com/debpalash/VoiceStudio.git
cd VoiceStudio
bun install
bun run desktop

Voice 工作区一开始就是三个标签页，分别对应三条独立工作流，每个标签页下方把「Synthesize Audio」或「Convert」固定在滚动表单之外。顶栏的 Engines 面板把引擎选择、已加载模型、卸载与 flush 控制整合在一处，快捷键 Ctrl/Cmd+E 打开——换引擎不用重启应用。

1. From audio（克隆）——打开 Voice Cloning，放一段干净的人声样本。官方说明 3 秒就能用，5 到 15 秒通常给出更好的提示效果；然后输入文本、选语言、Generate。
2. By design（造音色）——不参考任何真人，用年龄、口音、音高、风格与演绎指令描述出一个音色，适合旁白、播报这类需要稳定人设的场景。
3. Convert（语音到语音）——把一段已有录音转成另一个音色，保留原有节奏与说法。

先把最容易误读的一处说清：646 种语言是「目录」层面的覆盖，官方明确注明实际覆盖与质量取决于所选引擎。落到具体引擎，差距非常大——默认引擎（由 k2-fsa/OmniVoice 驱动）与 OmniVoice GGUF 标称 600+ 语言并支持克隆与指令控制；CosyVoice 3 是 9 种语言加 18 种方言；VoxCPM2 约 30 种；GPT-SoVITS 只有 5 种；KittenTTS 仅英文且不支持克隆。ASR 侧同理：默认的 WhisperX 约 100 种语言、适合配音与字幕的词级时间戳，FunASR 标称 50+，Moonshine 只支持英文但低功耗低延迟。引擎支持是按能力划分的，官方要求选型前先核对克隆、语言、平台、显存与许可这五项。

还有一条容易被忽略的行为约定：不支持克隆的引擎遇到配音或固定音色的批量任务时，VoiceStudio 会直接拒绝任务，而不是悄悄换一个引擎——宁可失败，也不给你一条音色被偷换的成品。

既然算力由你出，官方按硬件给了推荐组合，这基本就是选型答案卷：

WhisperX 与 Faster-Whisper 在拿不到 float16 时会退回 int8；只有自动选择仍然失败时才需要手动固定 ASR_COMPUTE_TYPE。显存紧张时系统会按需把负载卸到 CPU，慢就慢一点，不至于直接不可用。

桌面壳是 Tauri v2（Rust），UI 是 React + Vite，两者走 IPC；UI 再用 localhost:3900 上的 HTTP、SSE 与 WebSocket 打给 FastAPI 后端，状态落在 SQLite（Alembic 迁移）与 omnivoice_data/ 目录里。

Tauri v2 desktop shell (Rust)
        │ IPC
React + Vite UI
        │ HTTP · SSE · WebSocket on localhost:3900
FastAPI backend
        ├── TTS / ASR engine registries
        ├── dubbing / audio / long-form pipelines
        ├── OpenAI-compatible API and MCP server
        └── SQLite + Alembic → omnivoice_data/

README 里「Network boundary」这一节值得逐条读，它是判断「本地」这个词含金量多少的依据：桌面端只与 localhost:3900 的回环后端通信；回环 API 调用不需要任何服务端密钥，而一旦要远程访问，就必须提供 share PIN 或 API key；远程 worker 与 OpenAI 兼容 ASR 都是显式开启的可选项，回环 ASR 可以走 HTTP 且音频留在机器上，非回环端点则强制 HTTPS 且不跟随重定向；分析统计在你同意之前一直是关闭的，即使开启也只发送白名单内、不含内容的用量元数据，绝不会发送文本、音频、文件名或项目。

接口层面，它同时是一台本地语音平台和一个 OpenAI 兼容端点：

把 OpenAI 客户端的 base_url 从云端换成回环地址即可接管：

from openai import OpenAI

client = OpenAI(base_url="http://localhost:3900/v1", api_key="local")

with client.audio.speech.with_streaming_response.create(
    model="tts-1",
    voice="<profile-id>",
    # 音色档位与引擎分别由 voice / model 指定
    input="Made on my own hardware.",
    response_format="wav",
) as response:
    response.stream_to_file("speech.wav")

# Quick test via cURL
curl http://localhost:3900/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"model": "tts-1", "input": "Made on my own hardware.", "voice": "default", "response_format": "wav"}' \
  --output speech.wav

完整 API 参考内置在应用里，路径是 Settings → OpenAPI Reference。如果要走局域网、Tailscale 或代理暴露后端，官方要求先读 API 认证文档再动手。

VoiceStudio 在 http://localhost:3900/mcp 挂载了一个 MCP 服务，供 Claude Desktop、Cursor 及其他 AI agent 使用，暴露的工具是 generate_speech、clone_voice、transcribe，并支持不同的文件流式模式。多数客户端一段 URL 配置就够：

{
  "mcpServers": {
    "voicestudio": {
      "url": "http://localhost:3900/mcp"
    }
  }
}

只接受 stdio 传输的客户端，可以用仓库自带的本地 shim（配置在 docs/mcp.json）：

{
  "mcpServers": {
    "voicestudio": {
      "command": "python",
      "args": ["-m", "backend.mcp_shim"],
      "cwd": "/path/to/VoiceStudio"
    }
  }
}

另一条入口是 skills：一条 npx skills add debpalash/VoiceStudio 就能把两个技能装进 Claude Code、Codex、Cursor 等兼容 skills.sh 的 agent——omnivoice 负责通过本地 VoiceStudio 合成语音与转写音频，oss-maintainer 是仓库自身的开源维护工作流。再往上一层是可选的远程 worker：带鉴权的远程算力与任务传输，模型可以安装到已注册的远程 worker 上并显示实时进度，算是给「本地控制 + 借别人的算力」留的一扇门。

装完先跑自检，别急着排错。README 的「If setup fails」给了固定顺序。

1. 自检——Settings → About → Run self-check，或命令行走深度诊断。
2. 查安装排错文档与引擎指南——重型引擎有各自独立的显存与平台限制，先看引擎指南再拉模型。
3. 提 issue 前打包诊断信息——从应用里保存一份脱敏过的 diagnostic bundle。
4. 生成太慢——对照官方实测 benchmarks 与 performance 设置调引擎，而不是盲目换硬件。
5. 彻底清理——macOS/Linux 用 scripts/uninstall.sh，Windows 用 scripts\uninstall.ps1，两者都会先显示一次 dry run 再删除。

uv run python backend/main.py --diagnose --deep