speech

語音技能概覽

語音技能的用途

語音技能會把文字轉成可聆聽的音訊，適合旁白、配音、IVR 提示、無障礙朗讀，以及批次語音生成。當你需要的是可重現、可控的輸出，而不是「幫我把它念得好聽一點」這種自由發揮式需求時，它最合適。

誰適合使用

如果你的語音技能安裝是為了真正嵌入工作流程而來，就很適合：像是產品示範、App onboarding、無障礙素材，或是把結構化文字批次轉成很多段短音檔。當你在意聲線選擇、語速、輸出格式，以及多次執行都能維持一致時，它是很好的選擇。

這個技能有何不同

語音指南是以 OpenAI Audio API 和內建 CLI 為核心，因此偏向可預期、可重現的使用方式，而不是臨時丟一句提示詞來試效果。它使用內建聲音，支援單檔或批次工作，且在實際生成時需要 OPENAI_API_KEY。自訂聲音建立不在其範圍內。

如何使用語音技能

安裝並找到工作流程

使用 npx skills add openai/skills --skill speech 安裝。安裝後，先讀 SKILL.md，再看 references/cli.md 了解指令細節、references/audio-api.md 了解模型與參數限制，並參考 references/prompting.md 或 references/voice-directions.md 學習更好的指令寫法。若要快速掌握上下文，可再查看 agents/openai.yaml 和 references/sample-prompts.md。

把粗略目標轉成可用提示詞

語音技能的使用模式，最適合你把要朗讀的精確文字、目標聲線、表達風格、輸出格式，以及任何發音限制都說清楚。像這樣的需求就很強： “Generate a 45-second product demo voiceover from this script, use cedar, keep it warm and steady, output mp3, and emphasize the product name on first mention.” 這比「讓它聽起來專業一點」更有效，因為它給了技能具體的合成控制條件。

單檔與批次工作流程

這個技能設計成兩條路：單一音檔或多個音檔。如果你有多行文字、提示或檔案，就應該視為批次處理，先在 tmp/ 下準備暫時用的 JSONL 檔，然後一次執行 CLI，完成後刪除該 JSONL。如果只有一段腳本，就走單檔流程。這個判斷很重要，因為技能的結構與驗證步驟會隨輸出量而改變。

執行前要確認什麼

為了得到最佳結果，請確認文字是逐字正確，而不只是主題方向。也要確認聲線、檔案格式、語速，以及輸出是否必須偏中性、偏表情豐富，還是以無障礙優先。實際執行時主要要檢查的 repository 檔案是 scripts/text_to_speech.py；除非 repository 維護者明確指示，否則不要修改它。

語音技能常見問題

語音技能只適合旁白嗎？

不是。語音技能也適合配音、無障礙朗讀、IVR 提示，以及短音訊提示。它比較不適合自訂聲音複製或創意聲線設計，因為這個 repo 並未涵蓋這些內容。

使用語音技能一定要 CLI 嗎？

若要穩定使用語音技能，是的。內建 CLI 是預期的實際生成路徑，而 --dry-run 則適合在不呼叫 API 的情況下檢查指令形狀。如果你只寫一段通用提示詞，就會失去讓這個技能可重現的結構。

這對初學者友善嗎？

是的，只要你能提供精確文字和基本的聲線方向。語音安裝本身不複雜，但輸出品質取決於你把語速、語氣、格式和發音說得多清楚。初學者通常從短音檔和單一聲線開始，成功率會更高。

什麼情況下不該用這個技能？

如果你需要自訂聲音建立、重度後製，或是工作流程必須修改內建腳本，就不要用語音技能。如果你無法使用連網的 OpenAI API 呼叫，或沒有 OPENAI_API_KEY，它也不適合你。

如何改進語音技能

降低模糊空間

語音技能輸出品質提升最大的關鍵，就是把猜測空間降到最低。請提供精確文字，不要只給摘要；說明預期聽眾；並明確指出這段朗讀應該像旁白、客服訊息、無障礙朗讀，還是 IVR 提示。如果某個詞不好唸，就直接拼出唸法，或補上發音註記。

一次只調一個變數

當第一次結果已經接近，但還不夠理想時，只改一個項目：聲線、語速，或指令寫法。這樣比整段重寫提示詞更適合迭代。舉例來說，如果節奏太趕，就保持文字和聲線不變，只把速度從 1.0 調到 0.95。

使用真正重要的輸出限制

語音指南在限制條件是具體、可執行時表現最好，而不是抽象形容詞。可以明確寫成「mp3 方便快速播放」、「wav 供審閱」、或「穩定、中性，適合無障礙」。如果是批次工作，請讓每一行的範圍盡量單一，這樣技能才能在多個輸出之間維持一致的表達。

先讀對的參考文件

如果你想在 Design Implementation 情境下讓語音技能效果更好，優先看 references/accessibility.md 了解中性朗讀、references/voiceover.md 了解簡報式表達，以及 references/sample-prompts.md 了解提示詞格式。這些檔案能幫你寫出 CLI 和 API 可以直接執行、而不需要額外猜測的指令。