tts 是做什麼的？
將任何文字轉換為語音音訊。支援兩種後端（Kokoro 本地、Noiz 雲端）、兩種模式（簡單或時間軸精確），以及分段語音控制。
觸發條件
- 文字轉語音 / tts / 朗讀 / 說
- 語音克隆 / 配音
- epub 轉音訊 / srt 轉音訊 / 轉換為音訊
- 语音 / 说 / 讲 / 说话
簡單模式 — 文字轉音訊
speak 是預設子命令，可省略不寫：
# 基本用法（speak 為隱含命令）
python3 skills/tts/scripts/tts.py -t "Hello world" # 加上 -o 路徑可儲存
python3 skills/tts/scripts/tts.py -f article.txt -o out.mp3
# 語音克隆 — 本地檔案路徑或 URL
python3 skills/tts/scripts/tts.py -t "Hello" --ref-audio ./ref.wav
python3 skills/tts/scripts/tts.py -t "Hello" --ref-audio https://example.com/my_voice.wav -o clone.wav
# 語音訊息格式
python3 skills/tts/scripts/tts.py -t "Hello" --format opus -o voice.opus
python3 skills/tts/scripts/tts.py -t "Hello" --format ogg -o voice.ogg
第三方整合（飛書/Telegram/Discord）請參閱 ref_3rd_party.md。
時間軸模式 — SRT 轉時間對齊音訊
適用於需要精確分段時機的場景（配音、字幕、影片旁白）。
步驟 1：取得或建立 SRT 檔案
如果使用者沒有現成 SRT，可從文字產生：
python3 skills/tts/scripts/tts.py to-srt -i article.txt -o article.srt
python3 skills/tts/scripts/tts.py to-srt -i article.txt -o article.srt --cps 15 --gap 500
--cps = 每秒字元數（中文預設 4，英文約 15）。代理程式也可手動編寫 SRT。
步驟 2：建立語音映射檔案
JSON 檔案，控制預設及每段語音設定。segments 鍵支援單一索引 "3" 或範圍 "5-8"。
Kokoro 語音映射：
{
"default": { "voice": "zf_xiaoni", "lang": "cmn" },
"segments": {
"1": { "voice": "zm_yunxi" },
"5-8": { "voice": "af_sarah", "lang": "en-us", "speed": 0.9 }
}
}
Noiz 語音映射（新增 emo、reference_audio 支援）。reference_audio 可以為本機路徑或 URL（使用者自己的音訊；僅 Noiz 支援）：
{
"default": { "voice_id": "voice_123", "target_lang": "zh" },
"segments": {
"1": { "voice_id": "voice_host", "emo": { "Joy": 0.6 } },
"2-4": { "reference_audio": "./refs/guest.wav" }
}
}
動態參考音訊切片：
如果您正在翻譯或配音一段影片，且希望每個句子自動使用原始影片中相同時間戳記的音訊作為參考音訊，請改用 --ref-audio-track 參數，而不是在映射檔中設定 reference_audio：
python3 skills/tts/scripts/tts.py render --srt input.srt --voice-map vm.json --ref-audio-track original_video.mp4 -o output.wav
完整範例請參閱 examples/。
步驟 3：渲染
python3 skills/tts/scripts/tts.py render --srt input.srt --voice-map vm.json -o output.wav
python3 skills/tts/scripts/tts.py render --srt input.srt --voice-map vm.json --backend noiz --auto-emotion -o output.wav
何時選擇哪一種
| 需求 | 建議 |
|---|---|
| 單純朗讀文字，不複雜 | Kokoro（預設） |
| EPU/PDF 有聲書含章節 | Kokoro（原生支援） |
語音混合（"v1:60,v2:40"） | Kokoro |
| 從參考音訊進行語音克隆 | Noiz |
情感控制（emo 參數） | Noiz |
| 每個片段精確的伺服端時長 | Noiz |
當使用者需要同時使用情感控制 + 語音克隆 + 精確時長時，Noiz 是唯一支援全部三者的後端。
訪客模式（無 API 金鑰）
當未設定 API 金鑰時，tts.py 會自動降級為訪客模式——一個不需要認證、功能受限的 Noiz 端點。訪客模式僅支援 --voice-id、--speed 和 --format；語音克隆、情感、時長與時間軸渲染均不可用。
# 訪客模式（未設定 API 金鑰時自動偵測）
python3 skills/tts/scripts/tts.py -t "Hello" --voice-id 883b6b7c -o hello.wav
# 明確指定後端改用 kokoro
python3 skills/tts/scripts/tts.py -t "Hello" --backend kokoro
可用的訪客語音（15 種內建）：
| voice_id | name | lang | gender | tone |
|---|---|---|---|---|
063a4491 | 販売員（なおみ） | ja | 女 | 喜び |
4252b9c8 | 落ち着いた女性 | ja | 女 | 穏やか |
578b4be2 | 熱血漢（たける） | ja | 男 | 怒り |
a9249ce7 | 安らぎ（みなと） | ja | 男 | 穏やか |
f00e45a1 | 旅人（かいと） | ja | 男 | 穏やか |
b4775100 | 悅悅｜社交分享 | zh | 女 | Joyful |
77e15f2c | 婉青｜情緒撫慰 | zh | 女 | Calm |
ac09aeb4 | 阿豪｜磁性主持 | zh | 男 | Calm |
87cb2405 | 建國｜知識科普 | zh | 男 | Calm |
3b9f1e27 | 小明｜科技達人 | zh | 男 | Joyful |
95814add | Science Narration | en | 男 | Calm |
883b6b7c | The Mentor (Alex) | en | 男 | Joyful |
a845c7de | The Naturalist (Silas) | en | 男 | Calm |
5a68d66b | The Healer (Serena) | en | 女 | Calm |
0e4ab6ec | The Mentor (Maya) | en | 女 | Calm |
安全性與資料揭露
此技能在執行時會進行以下檔案與網路操作：
- 憑證儲存：當您執行
config --set-api-key時，金鑰會儲存至~/.config/noiz/api_key（權限0600）。也可使用NOIZ_API_KEY環境變數作為替代。 - 舊金鑰遷移：如果
~/.noiz_api_key存在而~/.config/noiz/api_key不存在，金鑰會被複製（非刪除）到新位置。會印出提示訊息；舊檔案保持不變，供您手動移除。 - 網路呼叫（Noiz 後端）：文字與選擇性的參考音訊會上傳至
https://noiz.ai/v1/進行合成。除非您執行 Noiz 命令，否則不會傳送任何資料。 - 參考音訊下載：當
--ref-audio為 URL 時，檔案會下載至暫存檔，用於 API 呼叫後刪除。若未提供 voice-id 或 ref-audio，會從storage.googleapis.com或noiz.ai下載預設參考音訊。 - 暫存檔：合成過程中可能建立暫存音訊/文字檔，使用後即清除。
- ffmpeg：僅在時間軸
render模式中呼叫，以組合最終音訊。
不會修改輸出路徑和 ~/.config/noiz/ 以外的任何檔案。Kokoro 後端完全離線執行，無網路存取。
需求
ffmpeg在 PATH 環境變數中（僅時間軸模式需要）requests套件：uv pip install requests（Noiz 後端需要）- 在 Noiz Developer 取得您的 API 金鑰，然後執行
python3 skills/tts/scripts/tts.py config --set-api-key YOUR_KEY（訪客模式無需金鑰即可運作，但功能有限） - Kokoro：若已安裝，傳入
--backend kokoro即可使用本地後端
Noiz API 驗證
僅使用 Base64 編碼的 API 金鑰作為 Authorization——無需前綴（例如不要加 APIKEY 或 Bearer ）。任何前綴都會導致 401 錯誤。
有關後端詳細資訊與完整參數說明，請參閱 reference.md。