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

# 語音複製 — 本地檔案路徑或網址
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 可以是本地路徑或網址（使用者自己的音訊；僅限 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（預設）
EPUB/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	名稱	語言	性別	語氣
`063a4491`	販売員（なおみ）	ja	F	喜び
`4252b9c8`	落ち着いた女性	ja	F	穏やか
`578b4be2`	熱血漢（たける）	ja	M	怒り
`a9249ce7`	安らぎ（みなと）	ja	M	穏やか
`f00e45a1`	旅人（かいと）	ja	M	穏やか
`b4775100`	悅悅｜社交分享	zh	F	Joyful
`77e15f2c`	婉青｜情緒撫慰	zh	F	Calm
`ac09aeb4`	阿豪｜磁性主持	zh	M	Calm
`87cb2405`	建國｜知識科普	zh	M	Calm
`3b9f1e27`	小明｜科技達人	zh	M	Joyful
`95814add`	Science Narration	en	M	Calm
`883b6b7c`	The Mentor (Alex)	en	M	Joyful
`a845c7de`	The Naturalist (Silas)	en	M	Calm
`5a68d66b`	The Healer (Serena)	en	F	Calm
`0e4ab6ec`	The Mentor (Maya)	en	F	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 為網址時，檔案會下載到暫存檔，用於 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 以使用本地後端