Demo Narrator
管線:幀 → 理解 → 草擬腳本 → 用戶審核關卡 → 音效 + TTS → 渲染 → 驗證。
輸出:output_final.mp4(H.264/AAC,−16 LUFS,字幕燒錄)+ subtitles.srt。
SKILL="<包含此 SKILL.md 的目錄的絕對路徑>" # 例如 ~/.claude/skills/demo-narrator 或 ./.claude/skills/demo-narrator
PY="$SKILL/.venv/bin/python"
在開始時解析 SKILL 一次(它取決於技能的安裝位置),之後全部使用絕對路徑。
0. 飛行前檢查
- 如果
$PY不存在,告知用戶安裝過程會安裝 ffmpeg + espeak-ng(Homebrew/apt)、Python 3.12 虛擬環境、PyTorch 以及約 400 MB 的免費模型權重;如果同意,執行bash "$SKILL/setup.sh"(需要幾分鐘;在背景執行)。 - 在影片旁選擇一個工作目錄:
WORK="<影片目錄>/demo-narrator-work/<影片主檔名>"。永遠不要寫入技能目錄。 - 詢問(一條訊息,僅詢問未知資訊):產品名稱及其功能、觀眾、語氣(預設:友善、自信、簡潔)、語音偏好(預設
af_heart),以及任何必須說明的內容(CTA、網址)。如果用戶已經說「直接做」,則不要詢問 — 從影格推斷。
1. 提取影格 + 檢查時長
"$PY" "$SKILL/scripts/extract_frames.py" "<video>" --out "$WORK"
- 列印時長/解析度,每 2 秒取樣 1 幀,偵測場景變化,建立 3×3 聯絡表。
- 拒絕時長 < 3 秒或 > 15 分鐘的影片(使用
--force/--max-duration覆蓋;對長影片使用--interval 4)。 - 首先檢視
$WORK/sheets/*.jpg(每個都標有時間戳)。僅在需要細節時(小 UI 文字、點擊發生的精確時刻)才開啟單個$WORK/frames/*.jpg。 $WORK/frames.json→duration、scene_changes(最適合加入呼嘯聲的位置)、影格列表。
建構一個節拍列表:每個時刻螢幕上的內容、發生的動作(點擊、輸入、頁面切換、成功狀態),以及觀眾應得到的要點。
2. 草擬 $WORK/script.json
{
"video": "/abs/path/to/demo.mp4",
"voice": "af_heart",
"speed": 1.0,
"approved": false,
"segments": [
{"id": 1, "start": 0.4, "end": 4.6, "text": "Meet Relay, the fastest way to turn customer calls into tickets."},
{"id": 2, "start": 5.0, "end": 10.8, "text": "Drop in a recording, and Relay pulls out every bug, request, and follow-up for you."}
],
"sfx": [
{"name": "whoosh", "at": 4.8},
{"name": "pop", "at": 7.2, "gain_db": -12},
{"name": "ding", "at": 10.4}
]
}
時間規則
- 每段落的單字預算 ≈
(end − start) × 2.5個字(Kokoro 在速度 1.0 時約 150 wpm)。保持在預算內。 - 段落之間留 ≥ 0.3 秒;第一句從約 0.3–0.8 秒開始;在重要時刻後讓影片有呼吸空間。
- 將
start錨定在所述內容出現的時刻,而不是之前。旁白可以領先動作約 0.3 秒。 - 段落不得超出影片範圍;最後一段應在影片結束前 ≥ 1 秒結束。
為聽覺而寫
- 口語化、第二人稱(「你」)、縮寫、主動動詞。一個段落一個想法。
- 描述正在發生的事情的好處,而不是畫素。永遠不要出現「在這裡我們看到…」/「如你所見…」。
- 按照應該的發音拼寫單詞:「two-x faster」、只有需要拼讀時才用「A-P-I」、「dot com」。避免使用符號、表情符號、帶斜線的 URL 和括號。
- 短句。如果用戶提供了 CTA,則以明確的 CTA 結尾。
音效(whoosh、whoosh_soft、pop、click、ding)— at 是絕對影片時間。
whoosh用於頁面/螢幕轉場(使用scene_changes),whoosh_soft用於面板/模態框滑入,pop用於元素/提示出現,click用於關鍵按鈕按下,ding用於成功/完成。- 克制:最多約每 4–6 秒 1 個提示。提示之間不要少於 0.3 秒。預設電平比語音低 −9 dB;對細微的提示設定
gain_db(例如 −14)。
語音(Kokoro):af_heart(溫暖美式女性,預設)、af_bella、am_michael / am_fenrir(美式男性)、bf_emma(英式女性)、bm_george(英式男性)。其他語音在首次使用時下載一次。
3. ⛔ 腳本審核關卡 — 強制
在用戶明確批准腳本之前,不得生成任何音訊。
-
以表格形式呈現腳本並停止:
# 時間 字數 / 預算 旁白 音效 1 0:00.4–0:04.6 11 / 10 ⚠ Meet Relay, … — 用 ⚠ 標記超出預算的段落。提及語音 + 總旁白長度。結尾: 「批准此腳本,或告訴我要更改什麼。」
-
結束你的回合並等待。 沉默、「看起來不錯?」或對先前草稿的批准不等同於對當前草稿的批准。
-
編輯時:更新
script.json,重新呈現變更的行,再次等待。 -
僅在對當前文字明確說「是」(「批准」、「是」、「開始」、「發送」)之後,才蓋章:
"$PY" "$SKILL/scripts/generate_tts.py" "$WORK/script.json" --approve此印章是旁白文字的摘要。
generate_tts.py和render_video.py拒絕在未蓋章的腳本或蓋章後文字有任何更改的腳本上執行 — 你必須重新通過此關卡。永遠不要手動設定approved/approved_digest。時間(start/end)和sfx的編輯不需要重新批准。
4. 生成音效 + 旁白
"$PY" "$SKILL/scripts/generate_sfx.py" --out "$WORK/sfx"
"$PY" "$SKILL/scripts/generate_tts.py" "$WORK/script.json"
- TTS 寫入
$WORK/audio/seg_###.wav+tts.json。引擎:Kokoro,自動回退到 Piper(使用--engine piper強制)。 - 每個片段被調整到其時段(直到下一個段落開始);超出的部分會以最高
--max-speed 1.25的速度重新合成。 - 如果表格仍然顯示
OVER,則優先移動start/end或後續段落(無需重新批准)。如果文字必須縮短,那是文字更改 → 回到審核關卡。 - 重新製作單個段落:
--only 3 5。不同的音效變體:--seed 7。
5. 渲染
"$PY" "$SKILL/scripts/render_video.py" "$WORK/script.json"
- 將片段放置在其
start時間,永不重疊;小幅度超出會進行保持音高的atempo壓縮(≤ 1.12×),剩餘部分會後移後續片段(列印為漂移)。如果旁白時間超過影片,則保持最後一幀。 - 混合語音 + 音效,響度歸一化至 −16 LUFS,燒錄字幕(使用 Pillow 渲染卡片 + FFmpeg
overlay,因此無需 libass),寫入$WORK/output_final.mp4和subtitles.srt。 - 可選背景音樂(原始、本地合成、無需授權):
"$PY" "$SKILL/scripts/generate_bgm.py" --duration <影片秒數> --out "$WORK/bgm.wav"(風格:positive(預設)= 原聲吉他 16 分音符撥奏,搭配響亮的開放弦、每拍溫暖的和弦重擊、強勁的底鼓、切分的拍手/拍擊、離拍低音、柔和撥奏主旋律、111 BPM、中段中斷,基於 B2B 示範參考建模;demo-bright/demo-dorian= SaaS 示範律動,基於庫存產品示範曲目建模:110 BPM、溫暖的和弦以八分音符脈動並隨柔和底鼓抽吸、第 2 和第 4 拍拍手、八分鈸、低音在根音、持續的高音線、輕柔撥奏旋律、前奏 → 律動 → 中段 8 小節中斷 → 律動 → 乾淨結尾;uke、marimba、pluck、kalimba= 明亮的軟體示範背景,一個撥奏/槌子動機,搭配簡單的柔和底鼓 + 拍掌/拍手 + 沙錘節奏和一點低音,100–112 BPM,大調;lofi(預設)= 帶有鼓的 chill 搖擺節拍;keys= 電鋼琴;upbeat= 底鼓 + 琶音;ambient= 僅 pad。--bpm、--key(明亮風格)、--mood(其他風格)、--seed N用於變體)。使用--duration 40製作 30–40 秒的預覽,讓用戶自行選擇,然後使用--bgm "$WORK/bgm.wav"渲染。--bgm也接受用戶提供的音軌(mp3/m4a/wav):它會自動調整到相同的參考電平,如果比影片短則以 2.5 秒淡入淡出循環,並在結尾淡出。要求用戶確認他們擁有其所提供任何音軌的權利。音樂會自動在語音下閃避;使用--bgm-db(預設 −2.5)和--duck-db(預設 −5)調整。 - 有用的標記:
--out <路徑>、--orig-volume 0.15(安靜地保留原始音訊)、--sfx-gain-db -12、--no-subs(仍會寫入subtitles.srt;當影片底部附近已有螢幕上字幕時使用)、--font <ttf>、--font-scale 0.05、--crf 20。
6. 驗證後再回報
- 檢查渲染輸出:漂移欄位約為 0,無保持幀警告(或解釋它)。
- 抽檢字幕:在 2–3 個段落中點執行
ffmpeg -ss <t> -i "$WORK/output_final.mp4" -frames:v 1 "$WORK/check_<t>.jpg",然後檢視影像 — 字幕可讀,不遮蓋關鍵 UI。如果遮蓋了重要內容,考慮使用--font-scale或告知用戶。 - 回報:輸出路徑、時長、使用的引擎/語音、被加速或移位的段落,以及如何調整(編輯
script.json→ 重新執行步驟 4–5;文字編輯需重新經過審核關卡)。
疑難排解
| 症狀 | 修復 |
|---|---|
kokoro unavailable … trying fallback | 再次執行 setup.sh;檢查 .venv 中的 Python 是否為 3.10–3.12。Piper 輸出沒問題,但較不自然。 |
| 錯誤發音的字/名稱 | 在 text 中按發音重新拼寫(例如「Kubernetes」→「koo-ber-net-eez」),獲得批准,使用 --only 重新生成該段落。 |
| 語速感覺太快 | 將 speed 降低至 0.95,加寬段落時間窗口,或減少單詞。 |
| 字幕太小/太大 | --font-scale 0.035–0.06。 |
| 顏色錯誤 / VFR 抖動 | 新增 --fps 30。 |
| 影片有你想保留的音樂 | --orig-volume 0.12–0.2。 |
一次性模型下載後,所有操作均可離線執行。許可證:Kokoro-82M Apache-2.0,Piper GPL-3.0(piper-tts ≥1.3),語音依模型卡,FFmpeg LGPL/GPL。