doggy8088 Gemini TTS CLI
Overview
使用本指南快速掌握 gemini-tts 的指令、參數與常見流程，完成文字轉語音、批次處理、合併 WAV 與基本排錯。
Quick Start
設定 API key（PowerShell）：
$env:GEMINI_API_KEY = "your-api-key-here"
設定 API key（CMD）：
set GEMINI_API_KEY=your-api-key-here
設定 API key（bash/zsh）：
export GEMINI_API_KEY="your-api-key-here"
單句轉語音：
gemini-tts -t "Hello world"
指定指令與聲音：
gemini-tts -i "Read aloud in a warm, professional and friendly tone" -s zephyr -t "Hello" -o hello.wav
批次檔案（合併輸出）：
gemini-tts -f "input.txt" -s achird -c 5 -m -o merged.wav
列出所有聲音：
gemini-tts list-voices
合併 WAV：
gemini-tts merge "*.wav"
Commands
gemini-tts：主命令，單句或批次文字轉語音。gemini-tts list-voices：列出可用聲音。gemini-tts merge <pattern>：合併 WAV，支援 glob pattern。
Core Options
-t,--text：要轉語音的文字。與--file擇一。-f,--file：批次輸入檔案路徑（僅.txt或.md）。與--text擇一。-i,--instructions：指令提示，預設為Read aloud in a warm, professional and friendly tone。-s,--speaker1：聲音名稱，大小寫不敏感，預設隨機。-o,--outputfile：輸出 WAV 名稱，預設output.wav。單句模式可用-輸出到 stdout。-c,--concurrency：批次併發數，預設1。-m,--merge：批次完成後合併成單一 WAV。--no-cache：關閉快取並強制重新生成。
Input Rules
--text與--file只能擇一，且必須提供其一。-t參數若以@或"@開頭，會被視為檔案參考，例如-t @input.txt或-t "@input with spaces.txt"。- 批次檔案僅支援
.txt或.md，檔案必須存在。 - 會忽略空行與只含符號的行，至少要有一行包含字母或數字。
Output Behavior
- 單句模式輸出單一 WAV，
-o -會把 WAV 直接寫到 stdout，可用管線輸出。 - 批次模式未啟用
--merge時，輸出為basename-01.wav、basename-02.wav…（基底來自--outputfile）。 - 批次模式啟用
--merge時，先產生暫存檔再合併成--outputfile。 merge子命令在目前工作目錄比對 pattern，pattern 必須包含.wav。
Merge Pattern Defaults
*.wav預設輸出merged.wav。**/*.wav預設輸出all-merged.wav。trial03-*.wav預設輸出trial03-merged.wav。
Voices
Female: achernar, aoede, autonoe, callirrhoe, despina, erinome, gacrux, kore, laomedeia, leda, sulafat, zephyr, pulcherrima, vindemiatrix
Male: achird, algenib, algieba, alnilam, charon, enceladus, fenrir, iapetus, orus, puck, rasalgethi, sadachbia, sadaltager, schedar, umbriel, zubenelgenubi
Cache
- 預設會使用快取避免重複生成，快取 key 由
instructions + voice + text組成並儲存在系統暫存目錄。 - 需要強制重新生成時，使用
--no-cache。
Examples
單句輸出到 stdout：
gemini-tts -t "Hello world" -o - > output.wav
以檔案參考批次處理：
gemini-tts -t @input.txt -s zephyr -c 3
批次輸出不合併（產生編號檔案）：
gemini-tts -f "input.txt" -s zephyr -c 3
合併指定模式：
gemini-tts merge "trial03-*.wav" -o trial03-merged.wav
Troubleshooting
- 出現缺少 API key 錯誤時，設定
GEMINI_API_KEY環境變數。 - 出現無效聲音錯誤時，先執行
gemini-tts list-voices確認名稱。 - 批次檔案錯誤時，確認副檔名為
.txt或.md，且檔案存在。 - 合併找不到檔案時，確認 pattern 包含
.wav且在目前工作目錄可匹配。