tutorial-voiceover-style

name	tutorial-voiceover-style
description	Tutorial 影片寫 voiceover 的工作順序(先鎖圖再寫配音、先預覽再 render)、內容規範、ElevenLabs 模型 / 速度設定。任何要動 intro / step.voiceovers / outro 字串、或要跑 generate-tutorial-voiceover.ts / render:tutorial 的 AI 都應該先讀。

Tutorial 配音風格與模型規範

這支 skill 規範寫教學片配音字串的三件事:何時動配音、講什麼、怎麼合成。

---

1. 工作流程順序

兩條順序規則,合在一起就是教學片完整工作流程。

1.1 先鎖圖,後寫配音

強制順序: 先把 step 所有 image / code / callout block 鎖定(視覺骨架先定死,圖檔名都填進 steps.json)→ 才動 voiceovers / intro.voiceover / outro.voiceover 字串 → 才跑 generate-tutorial-voiceover.ts。

Why: 內容規則(2.1)要求「畫面上看得到的重點全部要點到」—— 不知道畫面是什麼,寫不出對的配音。圖如果之後再改,配音多半要重寫,ElevenLabs credit 燒兩次。

1.2 圖鎖好直接產 wav,先驗配音、配音 OK 才上字幕,字幕也 OK 才 render

強制順序(兩輪預覽,字幕分開驗):

1. 圖鎖好 → voiceover 字串寫完 → 直接跑 generate-tutorial-voiceover.ts 產 wav(不插無音訊視覺預覽)
2. 第一輪預覽:帶配音、不上字幕 → 跑 npm run dev,使用者驗 step 對位 / pageBreak 時機 / 配音停頓 / 排版 / 圖片對焦
3. 配音不對 → 改字串 → 重產對應 clip 的 wav → 重新預覽(可能多輪)
4. 使用者確認配音定稿 → 才把字幕打開(<SubtitleOverlay>)
5. 第二輪預覽:帶配音 + 字幕 → 驗字幕不擋關鍵畫面 / 無換行錯誤 / 無超框 / 句子不過長
6. 字幕不對 → 改 SubtitleOverlay 設定(切句邏輯 / 字級 / 位置)→ 再預覽
7. 兩輪都 OK + 使用者明確說「render / 出片 / ship / OK 出片」 → 才跑 npm run render:tutorial

Why(為什麼字幕等配音 OK 才上): 字幕直接從 voiceover 字串切出來。配音還在調(改字 / 拆 pageBreak / 換詞 / 重產 wav 改 timing)的時候上字幕,字幕會跟著動 —— 等於每改一次配音就要重驗字幕,工白做。先把配音鎖死,字幕只驗排版層(切句長度、遮不遮畫面),一次到位。

Why(為什麼不先視覺預覽再產 wav): scene duration 是 max(預設 frames, audio frames + tail)。wav 沒生時 Sequence 還是預設時長,studio 看到的 timing / pageBreak 節奏 / 配音停頓位置跟成片不一樣,等於白看。先產 wav 把 duration 鎖死,預覽才有鑑別力。

Why(為什麼不能直接 render): render 一次 5–10 分鐘,沒預覽就 render 通常要重來。AI 不要自己決定 render 時機。

目前實作限制: TutorialComposition.tsx 一律渲染 <SubtitleOverlay>,沒 toggle。第一輪「不上字幕」目前要靠手動把那一行註解掉(或加 config flag,例如 TUTORIAL_CONFIG.subtitles: boolean 預設 false 配音 OK 後翻 true)。實作前看使用者偏好。

1.3 完整 How to apply

1. 排定 step 所有 image / code / callout block,圖檔名填進 steps.json(實檔放進 public/screenshots/<videoName>/)
2. 對著定好的 block 寫 voiceover 字串
3. 跑 npx tsx scripts/generate-tutorial-voiceover.ts <videoName>(只跑改過的 clip,別全部重生燒 credit)
4. 第一輪預覽:帶配音、字幕關閉 —— 跑 npm run dev 給使用者看,驗 step 對位 / pageBreak 時機 / 配音停頓 / 排版 / 圖片
5. 配音 ⇄ 調整迴圈(可能多輪):改 voiceover 字串 → 重產對應 clip 的 wav → 重新預覽。場景太空就拆 pageBreak(用 tutorial-auto-pagebreak skill),不要為了拉長 audio 加廢話(規則 2.2)
6. 使用者確認配音定稿 → 才把 <SubtitleOverlay> 開啟(看下面實作限制)
7. 第二輪預覽:帶配音 + 字幕 —— 驗字幕不擋關鍵畫面 / 無換行錯誤 / 無超框 / 句子不過長
8. 字幕 ⇄ 調整迴圈:改 SubtitleOverlay 設定(切句邏輯 / 字級 / 位置)→ 再預覽
9. 兩輪都 OK + 使用者明確說「render / ship / 出片 / OK 出片」 → 才跑 npm run render:tutorial

「等 render」的明確定義:使用者沒說「render」「出片」「ship」「OK 出片」這類字,就視為還在調整中,即使預覽看起來沒問題也不要動 npm run render:tutorial。寧可問一句「都 OK 可以 render 了嗎」,不要自己跳進去燒 5–10 分鐘。

字幕開關目前實作:TutorialComposition.tsx 一律 render <SubtitleOverlay>,沒 toggle。第一輪「字幕關閉」靠手動把那一行註解掉(配音定稿後再解開)。要走得更乾淨可加 TUTORIAL_CONFIG.subtitles?: boolean(預設 false,定稿後翻 true)—— 寫教學的人決定。

durations.json 會自動更新,TutorialComposition 會根據新長度自動把 Sequence 拉長(max(預設 frames, audio frames + tail) 邏輯)。

---

2. 內容原則

2.1 必講:畫面上看得到的「重點」全部要點到

教學片觀眾常常邊看邊操作,畫面上有出現的關鍵動作 / 關鍵字 / 警示,配音都要對應講到一次,不要假設觀眾自己會讀。

「重點」指的是:

• 該頁的動作指令(複製、貼上、按 Enter、開哪個選單)
• 該頁的 行為相關 callout(會影響觀眾預期的提示):
  • ✅ 念:「沒有輸出是正常的」(否則觀眾會以為失敗)
  • ✅ 念:「看到紅字錯誤的話重跑一次」(行動指引)
• code 區塊裡的關鍵差異(不是逐字念,但要讓觀眾知道這行做什麼)
• 該頁出現的關鍵字(指令名 / 平台名 / 檔名)

例外 — 視覺確認型 callout 不用念: 畫面上純粹是「打開後會看到 X」、「跑完會看到 Y」這種純視覺結果描述、觀眾自己看畫面就知道有沒有達成、不影響觀眾下一步行動的 callout,可以省略不念,以免變成在念稿。判斷標準:這句話如果不念,觀眾會做錯事 / 誤判失敗嗎?不會 → 省略。

2.2 禁:為了「場景看起來太短」硬塞廢話

不要為了讓 audio 拉長到滿足某種視覺停留時間,而加無資訊量的鋪陳:

• ❌「整個過程大約一到兩分鐘,中間會看到一堆下載進度跑過去,讓它跑完就好。」 → ✅「下載安裝大概一到兩分鐘,讓它跑完。」(資訊量同,字數砍半)
• ❌「歡迎來到 Claude Code 安裝教學,這集會用 Mac 環境,三個步驟把 Claude Code 裝起來。」 → ✅「Claude Code 安裝教學,Mac 版。」(intro 通常只要主題 + 平台一句話)
• ❌「下一集,我們來裝幾個讓 Claude Code 跑得更順的開發工具,記得繼續看下去。」 → ✅「下一集,開發工具安裝教學。」(outro 只要成果 + 下一集是什麼)

2.3 場景如果太短

配音講完還剩很多畫面時間,選項:

1. 拆 pageBreak 多塞一張圖 給配音對應的視覺(用 tutorial-auto-pagebreak skill 自動拆)
2. 把 step 拆成多個 step(每個 step 自己一頁配音)
3. 接受場景就是這麼短 ——『重點講完就切下一場』比『硬塞贅字撐時間』好

絕對 不要 反向延長配音去配合視覺。

2.4 風格細節

• intro:主題 + 平台 / 受眾,1 句話結束。例:「Claude Code 安裝教學,Mac 版。」
• outro:成果一句 + 下一集標題,可加感嘆詞。例:「恭喜!Claude Code 安裝完成。下一集,開發工具安裝教學。」
• step:第 N 步先講動作,再講警示 / 例外。例:「第三步,設定 PATH 環境變數,讓你之後直接打 claude 就能用。複製指令貼上按 Enter。這行跑完不會有輸出,沒看到紅字就代表設定完成。」

---

3. 中文 TTS 發音地雷詞（ElevenLabs V3）

ElevenLabs V3 對以下詞彙有發音問題，寫 voiceover 字串時必須替換：

原文	替換成	原因
SQL	SEQUEL	念成字母拼讀
PostgreSQL	Postgre SEQUEL	同上
GB（容量）	G B（字母間加空格）	念成 "G bye"
Zeabur	Zee-bur	zea = sea 音改 z；bur = number 的 ber
Linode	Lin-node	確保念成 Lin + node 兩音節
.dev（域名）	點 D E V	避免念成英文 "dot dev"
MIT 授權	M I T license	「授權」被念成「俱全」類似音

規則：只改 voiceover 字串，不改 paragraph / code / callout 顯示文字。

---

4. ElevenLabs 模型 / 速度

3.1 模型固定 V3(eleven_v3)

• ❌ 不要用 eleven_multilingual_v2(語氣 / 停頓相對平,讀技術內容像念稿)
• ✅ eleven_v3 中文停頓自然、口氣比較像真人講解教學

scripts/generate-tutorial-voiceover.ts 的預設值已經是 eleven_v3(透過 ELEVENLABS_MODEL env override 才換),不要改回 v2 預設。

3.2 語速(ELEVENLABS_SPEED)

• 範圍 0.5 ~ 2.0,1.0 = 原速
• 教學片建議 0.85(略慢於原速,讓觀眾跟得上)
• 設在 .env 的 ELEVENLABS_SPEED=0.85

3.3 個別 clip 重生

只重生有問題的單一 clip,不要每次都全部重生(浪費 ElevenLabs credit):

# 全部重生
npx tsx scripts/generate-tutorial-voiceover.ts <videoName>

# 只重生某幾個 clip
npx tsx scripts/generate-tutorial-voiceover.ts <videoName> outro
npx tsx scripts/generate-tutorial-voiceover.ts <videoName> ch1-s2-p1 ch1-s2-p2