神經網路旁白生成
路徑：
${CLAUDE_PLUGIN_ROOT}是此插件根目錄。若此變數未定義， 根目錄位於此技能「Base directory」的上兩層 (<raiz>/skills/<skill>)。若技能 已直接複製到~/.claude/skills，請使用~/.claude/skills取代${CLAUDE_PLUGIN_ROOT}/skills。
腳本：${CLAUDE_PLUGIN_ROOT}/skills/narracao-voz/scripts/narracao.py。需要 pip install edge-tts 以及
網路連線：文字會傳送至 Microsoft 語音服務（免費且無需金鑰）。請勿在腳本中放入使用者不想傳輸到外部的內容。
使用方法
N=${CLAUDE_PLUGIN_ROOT}/skills/narracao-voz/scripts/narracao.py
python $N <資料夾> # audio/cena01.mp3 ... + cena01.json (單字時間戳)
python $N <資料夾> --mostrar # 顯示已套用發音替換的文字（不生成音檔）
python $N <資料夾> --so 3 7 # 只重新生成第 3 和第 7 場景
python $N <資料夾> --tempos 3 # " 2.41s chave" ... 用於同步動畫
python $N <資料夾> --voz pt-BR-FranciscaNeural --rate +0%
python $N --vozes # 列出葡萄牙語可用的語音
輸入：<資料夾>/roteiro.json，一個字串列表（每個場景一句對白）。語音與語速可設定於
video.json（"voz"、"rate"）。預設值：pt-BR-AntonioNeural、+8%。
獨立語句（片頭、提示、通知、語音測試），無需資料夾或腳本：
python $N --texto "各位好！今天的主題是 Docker。" --saida C:/tmp/vinheta.mp3
python $N --texto "..." --saida C:/tmp/f.mp3 --voz pt-BR-FranciscaNeural --rate +0%
基礎發音映射在此處同樣適用。若有多句獨立語句，建議使用包含 roteiro.json 的資料夾：每個對白會生成一個 MP3 檔案。
實用的 pt-BR 語音：pt-BR-AntonioNeural（男聲，影片常用）、pt-BR-FranciscaNeural（女聲）、
pt-BR-ThalitaMultilingualNeural（女聲，處理英語術語較佳）。完整清單：--vozes。
此外也有葡萄牙語 (pt-PT-...) 及其他語言的語音。
撰寫口語化腳本
腳本是給機器朗讀的。請用口語方式書寫，而非書面語：
| 螢幕/書面呈現 | 腳本中應寫 |
|---|---|
| 1995 | 一千九百九十五 |
| port 22 | 埠號二十二 |
| SCP, AWS (逐字母拼讀的縮寫) | S C P, A W S (字母分開) |
git push -u origin main | git push, 減號 u, origin main |
feat/login | feat 斜線 login |
.gitignore, .env | 點 gitignore, 點 env |
~/.ssh/known_hosts | known hosts 檔案 |
<, >, = | 小於, 大於, 等於 |
- 句子要簡短。逗號會形成停頓：用它來創造節奏（「連線、金鑰交換、以及驗證。」）。
- 對話語氣：「我們來了解」、「你知道那個...？」、「最棒的是：」、「總而言之：」。
- 每個場景 25–45 個單詞（在 +8% 語速下約 10–16 秒）。
- 避免使用括號和破折號：語音無法正確處理它們。
英語術語的發音
pt-BR 語音會將英語單字讀成葡萄牙語發音。修正方式是將術語替換為聽起來正確的拼寫， 僅在音檔中生效（腳本與螢幕仍保留原始單字）。
- 基礎映射表包含約 70 個開發術語：
scripts/pronuncia_base.json（git、commit、push、GitHub、branch、 Docker、deploy、API、JSON、frontend、Python、npm...）。 - 專案特定術語：
<資料夾>/pronuncia.json，格式相同。優先於基礎映射表。 若要停用 基礎映射中的某個替換，請將該術語映射回自身：{"status": "status"}。 - 替換是針對完整單字，不區分大小寫，且較長的術語會優先被替換（"Pull Request" 先於 "pull"）。
如何找到正確的拼寫：
- 想像一個巴西人會如何大聲朗讀，並在重音音節加上重音符號：commit → "comít", push → "púch", GitHub → "guít-râb", release → "rilís", cache → "kéch"。
- 使用連字符分隔各部分："és-és-êitch" (SSH), "ci-él-ái" (CLI)。
- 只生成該場景 (
--so N)，聆聽並調整。如果使用者說某處聽起來不對，請在 該專案的pronuncia.json中修正。如果是常見的開發術語，也請一併加入pronuncia_base.json，這樣後續的影片就能自動正確發音。
與動畫同步
每個 audio/cenaNN.json 包含 [{"t": 2.41, "palavra": "chave"}, ...]，時間以場景起始點為準，單位為秒。
請使用此 t 值（或提前 0.2 秒）作為表示該單字元素的進入時間。
單字會以已替換的拼寫顯示（例如 "comít"），這屬於正常現象。
常見問題
| 症狀 | 原因 / 解決方案 |
|---|---|
No module named edge_tts | 執行 python -m pip install edge-tts |
| 連線錯誤 / 403 | 無網路連線，或 Microsoft 有所變動：執行 pip install -U edge-tts |
| 語速過快或過慢 | 使用 --rate +0%（較慢）或 +15%（較快） |
| 術語發音錯誤 | 使用 pronuncia.json（如上所述） |
| 場景過長 (> 20 秒) | 將對白拆分為兩個場景 |