OmniVoice 語音工作室

透過 OmniVoice Studio MCP 伺服器提供本地 TTS、語音複製、語音設計與影片配音功能（開放原始碼的 ElevenLabs 替代方案；資料不離開機器，支援 MPS/CUDA/CPU）。

OmniVoice 語音工作室是什麼？

OmniVoice 是一套完整的本地語音合成技能，作為開放原始碼的 ElevenLabs 替代方案，確保所有音訊處理皆在本機端完成，無需 API 金鑰或雲端費用。技能提供 `generate_speech`、`list_voices`、`list_personalities`、`list_languages` 與 `check_health` 等 MCP 工具，可將文字轉換為 646 種語言（ISO 639 代碼或自動偵測）、從 3 至 10 秒的參考片段複製語音、透過性別/年齡/口音/音高/風格描述詞設計語音，並支援批次處理與內容管線。核心取樣模型 (~2.4 GB) 首次使用時從 HuggingFace 下載並快取，支援 MPS/CUDA/CPU 加速。技能同時提供 macOS 腳本 `record-reference.sh`，透過音頻提示（`say` 與系統提示音）引導使用者錄製乾淨的語音複製片段，並透過 `silenceremove` 與 `atrim` 自動修剪。若使用者僅需快速英文旁白，建議使用 `kokoro-tts`（更輕量）；若需最高品質且不計成本，則建議 ElevenLabs。

相容平台~Claude Code~Codex CLI~Cursor✓Antigravity

npx skills add https://github.com/broomva/skills/tree/HEAD/skills/audio/omnivoice

說明文件

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        # exit 0 if up
scripts/start-backend.sh       # boot in background (MPS/CUDA auto-detected)

首次合成呼叫時會延遲下載 k2-fsa/OmniVoice 模型（約 2.4 GB）來自 HuggingFace — 後續啟動時會快取。

任務索引 — 選擇正確的工具

任務	工具	備註
確認後端正在執行	`check_health`	回傳 `{"status":"ok","device":"mps
文字 → 音訊（使用已儲存的語音）	`generate_speech(text, profile_id)`	回傳 base64 WAV。`profile_id="demo0001"` 是內建的示範語音
文字 → 音訊（不進行語音複製，語音設計）	`generate_speech(text, instruct="…")`	省略 `profile_id`；傳入 `instruct` 如 `"溫暖的中年女性旁白，平靜的語氣"`
多語言旁白	`generate_speech(text, language="es")`	任何 ISO 639 代碼或 `"Auto"`
列出現有語音	`list_voices`	回傳 id、name、type、personality
列出人格預設	`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. 使用示範語音進行一次性旁白

# As called through the MCP client (your agent will do this for you):
result = generate_speech(
    text="你好 — 這是 OmniVoice 在本機端產生語音。",
    profile_id="demo0001",
    language="English",
    steps=16,                   # 8 = fast/draft · 16 = balanced · 32 = quality
)
# result is JSON with 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)            # parse JSON the tool returns
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 伺服器不公開 profile 建立功能 — 它僅讀取現有 profile。有兩種方式可建立：

方式 A — 內建輔助腳本（macOS，建議用於新語音複製）：

scripts/record-reference.sh ~/Downloads/my-ref.wav 12 1
# args: output_path raw_duration_sec mic_index
# 預設 mic_index=1（MacBook 內建麥克風）；列出裝置請使用：
#   ffmpeg -f avfoundation -list_devices true -i ""

該腳本透過 macOS say 及 /System/Library/Sounds/Ping.aiff 提供可聽見的倒數與開始/結束提示，讓使用者知道何時說話（終端機 stdout 有緩衝 — 文字提示「請說話」到達太晚）。它會錄製較長的原始視窗，然後透過 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   # max should be > -20 dB
afplay ref.wav

POST 到 /profiles（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
# returns { "id": "abc12345", "name": "carlos-clone" }

建立後，將 profile_id 傳遞給 generate_speech（透過 MCP）或直接透過 POST /generate。Profiles 會持久儲存於 SQLite 及參考音訊檔案 ~/Library/Application Support/OmniVoice/voices/<id>.<ext>（後端保留上傳的副檔名 — 若上傳 WAV 則為 .wav、MP3 則為 .mp3 等）。狀態在後端重啟後仍會保留。

明顯影響品質的參考片段技巧：

因素	為何重要
單一說話者	混合說話者會模糊嵌入
乾淨語音，無音樂/噪音	模型也會嵌入噪音
自然韻律（避免拗口句子）	擴散取樣會複製韻律，而不僅是音色
3-10 秒是最佳區間	< 3 秒缺乏資訊；> 10 秒增加計算量卻無品質增益
`ref_text` 要與錄製內容一致	改善對齊，尤其在噪音參考片段時
`language` 設定正確	錯誤語言 → 跨語言轉換產生物件
響度峰值 ≥ -15 dB	音量小的參考片段可運作但歸一化效果較差

4. 語音設計（無需參考片段）

省略 profile_id；提供描述目標語音的 instruct 字串：

generate_speech(
    text="歡迎來到代理系統的未來。",
    instruct="溫暖的中年女性旁白，沉穩權威的語氣，紀錄片風格",
)

可透過 list_personalities 取得預製的 instruct 字串，並複製符合需求的項目（narrator、casual、news-anchor 等）。

5. 影片配音（僅限網頁 UI）

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 — 透過對綁定 PID 執行 kill -TERM 進行乾淨關機
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）。

OmniVoice 語音工作室