Communitygithub.com

demo-narrator

將無聲的產品示範或螢幕錄影轉換為具有自然人聲旁白、乾淨的UI音效(呼嘯聲、彈出聲、點擊聲、叮噹聲)、可選背景音樂以及字幕(燒錄或.srt)的配音影片。包含腳本審核步驟,100%本地且免費。

demo-narrator 是什麼?

此技能(Demo Narrator)專為開發者與AI代理設計,能將無聲的產品示範影片或螢幕錄影自動轉換為專業配音影片。它支援多種輸入格式(.mp4/.mov/.webm/.mkv),並在本地執行所有處理,無需任何API金鑰或付費服務。技能流程包含:幀提取與場景分析、自動生成旁白腳本、強制用戶審核腳本(在音訊生成前必須獲得明確批准)、合成音效與文字轉語音(TTS,預設使用Kokoro-82M模型,必要時可回退至Piper),最後輸出包含燒錄字幕的H.264/AAC影片(output_final.mp4)與獨立字幕檔案(subtitles.srt)。它特別注重腳本的「口語化」撰寫(使用第二人稱、縮寫、主動動詞),並提供精確的時間軸控制、多種語音選擇、可調整的背景音樂(多種風格,也可使用用戶提供的音軌),以及豐富的渲染參數(如音量、字體大小、幀率)。所有處理皆可在離線環境完成,僅需一次性下載約400MB的模型權重。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/GarvitSolanki/audio-generator/tree/main/skills/demo-narrator

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

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. 飛行前檢查

  1. 如果 $PY 不存在,告知用戶安裝過程會安裝 ffmpeg + espeak-ng(Homebrew/apt)、Python 3.12 虛擬環境、PyTorch 以及約 400 MB 的免費模型權重;如果同意,執行 bash "$SKILL/setup.sh"(需要幾分鐘;在背景執行)。
  2. 在影片旁選擇一個工作目錄:WORK="<影片目錄>/demo-narrator-work/<影片主檔名>"。永遠不要寫入技能目錄。
  3. 詢問(一條訊息,僅詢問未知資訊):產品名稱及其功能、觀眾、語氣(預設:友善、自信、簡潔)、語音偏好(預設 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. 以表格形式呈現腳本並停止:

    #時間字數 / 預算旁白音效
    10:00.4–0:04.611 / 10 ⚠Meet Relay, …—

    用 ⚠ 標記超出預算的段落。提及語音 + 總旁白長度。結尾: 「批准此腳本,或告訴我要更改什麼。」

  2. 結束你的回合並等待。 沉默、「看起來不錯?」或對先前草稿的批准不等同於對當前草稿的批准。

  3. 編輯時:更新 script.json,重新呈現變更的行,再次等待。

  4. 僅在對當前文字明確說「是」(「批准」、「是」、「開始」、「發送」)之後,才蓋章:

    "$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. 驗證後再回報

  1. 檢查渲染輸出:漂移欄位約為 0,無保持幀警告(或解釋它)。
  2. 抽檢字幕:在 2–3 個段落中點執行 ffmpeg -ss <t> -i "$WORK/output_final.mp4" -frames:v 1 "$WORK/check_<t>.jpg",然後檢視影像 — 字幕可讀,不遮蓋關鍵 UI。如果遮蓋了重要內容,考慮使用 --font-scale 或告知用戶。
  3. 回報:輸出路徑、時長、使用的引擎/語音、被加速或移位的段落,以及如何調整(編輯 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。

相關技能