captjt/skill-tts

文字轉語音

啟動器位於 ${CLAUDE_SKILL_DIR}/scripts/tts，即此技能目錄中的 scripts/tts。以下簡稱為 tts。首次執行會下載約 7 MB 的二進位檔並檢查其 SHA-256 值後再執行。

每個 tts 指令應作為獨立的 Bash 呼叫執行。不要以 ;、&& 或管道串聯，以確保其處於技能預先核准的權限範圍內。

有兩種工作類型：

• 影片旁白： tts render。產生檔案及時間資訊清單，供後續影片處理流程使用。
• 即時朗讀： tts "文字"。透過揚聲器播放並立即返回。

影片旁白

1. 編寫腳本

每個場景或鏡頭放置一個段落，並重複使用影片的場景 ID，以確保音訊與視覺同步：

{
  "provider": "elevenlabs",
  "voice": "JBFqnCBsd6RMkjVDRZzb",
  "instructions": "溫暖、自信的產品敘述者",
  "pause": 0.5,
  "segments": [
    {"id": "01-intro",   "text": "歡迎使用全新的 Insights 儀表板。"},
    {"id": "02-filters", "text": "一鍵篩選任何圖表：按團隊、按服務或按版本。"},
    {"id": "03-alerts",  "text": "只需設定一次警示，我們便會在指標偏離時立即通知您。", "pause": 1.0},
    {"id": "04-outro",   "text": "Insights 現已上線，適用於所有方案。"}
  ]
}

• 頂層欄位（provider、voice、model、instructions、speed、pause）適用於所有段落。每個段落可覆寫 voice、model、instructions、speed 及 pause，其中 pause 代表該段落之後在合併音軌中的靜音長度。
• 整支影片使用同一個提供者與聲音，聽起來才會像同一位敘述者。
• 為聽覺而寫： 使用簡短的句子，數字以口語方式呈現（如「百分之四十」、「版本二」），避免使用 Markdown。如果產品名稱發音不正確，請在 text 中以語音拼寫。
• 選擇提供者與聲音。 如果腳本未設定提供者，且 tts config show 中沒有 voiceover_provider，請詢問使用者要使用哪個提供者與聲音。為了讓他們比較，可使用 tts -o sample-NAME.wav -p PROVIDER -v VOICE "腳本中的一行文字。" 渲染簡短的樣本。提供將選擇儲存起來的選項：tts config set voiceover_provider NAME 和 tts config set NAME.voice VOICE。Kokoro 和 system 是免費且本機的；其餘則需付費。ElevenLabs、帶有 instructions 的 OpenAI 以及 Gemini 聽起來最自然。

2. 渲染

"${CLAUDE_SKILL_DIR}/scripts/tts" render script.json -o voiceover/

這會產生：

• voiceover/<id>.wav：每個段落的音檔，已移除開頭與結尾的靜音，使時長精確。
• voiceover/voiceover.wav：所有段落以暫停間隔合併後的完整音軌。
• voiceover/voiceover.srt：字幕檔。
• voiceover/manifest.json：同時會輸出到標準輸出：

{"provider": "elevenlabs", "sample_rate": 24000, "channels": 1, "duration": 17.08,
 "combined": {"file": "/abs/voiceover/voiceover.wav", "duration": 17.08},
 "captions": "/abs/voiceover/voiceover.srt",
 "segments": [{"id": "01-intro", "file": "/abs/voiceover/01-intro.wav", "duration": 3.872,
               "start": 0, "end": 3.872, "text": "...", "voice": "...", "cached": false}, ...]}

渲染選項：

• --format mp3|m4a：設定合併音軌的格式。
• --no-combine：僅產生各別段落的檔案。
• -p/-v/-i/-s：設定腳本未指定的預設值。
• --jobs N：設定平行處理數量。

render 會使用每個提供者的最高保真度模型，除非已設定：eleven_multilingual_v2 和 gemini-3.8-flash-tts。

3. 使用時間資訊

• 場景長度： 每個場景的長度至少應與其段落的 duration 相同。可再加入一些呼吸空間，或延長場景以與之對齊。
• 放置音訊： 將每個段落的音檔放置在其場景的開始時間，或使用 voiceover.wav 作為單一音軌，並以 start/end 作為偏移量。
• 使用 ffmpeg 混音：
  • 整軌：ffmpeg -i video.mp4 -i voiceover/voiceover.wav -map 0:v -map 1:a -c:v copy -c:a aac -shortest out.mp4
  • 單一段落（例如在 4.47 秒處）：加入輸入 -i voiceover/02-filters.wav，然後 -filter_complex "[1]adelay=4470:all=1[a]" -map 0:v -map "[a]"。

4. 迭代

編輯腳本後再次執行相同指令。文字、聲音、模型、風格與速度未改變的段落會沿用上次渲染的結果（"cached": true）。僅有變更的段落會被重新渲染並計費。使用 --force 強制重新渲染所有內容。如果某些段落失敗，其他段落會被保留，重新執行時只會重試失敗的部分。

即時朗讀

"${CLAUDE_SKILL_DIR}/scripts/tts" "建置成功，214 項測試全部通過。"
"${CLAUDE_SKILL_DIR}/scripts/tts" <<'EOF'
較長的文字，或包含引號的內容，可透過標準輸入傳入。
EOF

此指令在音訊開始播放時返回，播放會在背景繼續。新的語音會打斷當前語音；使用 -q 可將其排隊等候，而 tts stop 則可靜音所有內容。

其他選項：

• -p 提供者、-v 聲音、-i "風格"、-s 速度。
• -w 等待播放結束。
• -o FILE [--json] 將音訊寫入檔案而非播放。--json 會輸出檔案時長與路徑。

朗讀時：

• 摘要，而非逐字朗誦。 除非要求朗讀全文，否則使用兩到四句口語句子。
• 以口語描述程式碼，而非直接讀出。Markdown 與程式碼區塊會自動被移除。
• 保持通知簡短，並對一系列通知使用 -q。

提供者、成本與隱私

• 使用已設定的預設值（tts config show）。僅在使用者或腳本指定提供者時才傳遞 -p。
• system 和 kokoro 保留在本機上且完全免費。其他提供者會將文字發送至該公司並向使用者帳戶收費。未經詢問，切勿變更預設提供者。
• 切勿將機密、憑證或私人資料傳送給雲端提供者。
• 付費提供者拒絕單次指令超過 20,000 個新字元。請縮短文字，或在使用者需要完整內容時傳遞 --max-chars N。

設定與疑難排解

• tts doctor 顯示音訊輸出、預設提供者以及哪些提供者已就緒。
• tts providers 和 tts voices -p NAME [filter] 列出提供者與聲音。
• tts config set KEY VALUE 設定預設值。可用的鍵包含 provider、voiceover_provider、max_chars 以及 NAME.voice|model|speed|instructions|base_url。
• 缺少 API 金鑰： 告訴使用者在他們自己的終端機中設定環境變數（例如 ELEVENLABS_API_KEY）或執行 tts auth set elevenlabs。切勿要求使用者將金鑰貼入對話中，也絕對不要將金鑰置於命令列上。
• 未經測試的雲端提供者： openai、gemini、cartesia 和 deepgram 尚未經過其即時 API 測試。僅 system、kokoro 和 elevenlabs 已測試過。如果其中一個失敗，並顯示關於請求本身的錯誤（未知欄位、無效參數或非預期回應），這很可能是此技能的錯誤，而非使用者的問題。請向使用者顯示確切的錯誤訊息，建議他們在 github.com/captjt/skill-tts/issues 回報，並提供 kokoro 或 system 作為備用方案。不要持續使用猜測的參數重試。認證（401/403）與配額（429）錯誤如同往常由使用者自行處理。
• Kokoro 無法連線： 使用 docker run -d --name kokoro -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-cpu:v0.9.0 啟動。
• 無音訊裝置（SSH、容器）：使用 render 或 -o；它們不需要揚聲器。

每個提供者的聲音、模型與選項詳見 references/providers.md。