Communitygithub.com

demo-narrator

デモ動画や画面収録に、自然な音声ナレーション、UIサウンドエフェクト、BGM、字幕を追加するオフラインツールです。

demo-narrator とは?

demo-narratorは、製品デモや画面収録の動画に、人間らしい自然な音声ナレーション、クリーンなUIサウンドエフェクト(ウィッシュ、ポップ、クリック、ディング)、オプションのBGM、そして字幕(動画埋め込みまたは.srtファイル)を追加するための完全オフライン・無料のAIエージェントスキルです。Claude CodeやCodexなどのAIエージェントが使用することを想定して設計されており、**スクリプト承認ゲート**という重要な特徴を持っています。これは、音声生成の前にユーザーがスクリプトを確認・承認するステップを必須とすることで、意図しないナレーションの生成を防ぎます。仕組みとしては、動画からフレームを抽出し、内容を解析してスクリプトとSEFの配置を自動提案します。ユーザーの承認後、Kokoro-82M TTSエンジン(フォールバックとしてPiper)で音声を生成し、FFmpegとPython(numpy/scipy)を用いて動画をレンダリングします。全ての処理がローカルで完結するため、APIキーや有料サービスは一切不要です。対応フォーマットは.mp4、.mov、.webm、.mkvです。

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

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

Demo Narrator(デモナレーター)

パイプライン: フレーム → 理解 → スクリプト草案 → ユーザー承認ゲート → SFX + 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. 質問する(1メッセージで、不明な点のみ): 製品名とその機能、視聴者、トーン(デフォルト: フレンドリー、自信、簡潔)、音声の好み(デフォルト af_heart)、必ず伝えなければならないこと(CTA、URL)。ユーザーが既に「とにかくやって」と言っている場合は、これをブロックせず、フレームから推測してください。

1. フレーム抽出 + 時間確認

"$PY" "$SKILL/scripts/extract_frames.py" "<動画>" --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": "Relayをご紹介します。顧客からの電話をチケットに変換する最速の方法です。"},
    {"id": 2, "start": 5.0, "end": 10.8, "text": "録音をドロップするだけで、Relayがあらゆるバグ、リクエスト、フォローアップを抽出します。"}
  ],
  "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秒以上前に終了する必要があります。

耳で聞くための書き方

  • 会話調で、二人称(「あなた」)、短縮形、能動的な動詞を使用。セグメントごとに1つのアイデア。
  • 起こっていることの 利点 を説明し、ピクセルを説明しないでください。「ここでは…が表示されます」「ご覧のとおり…」は決して使用しないでください。
  • 発音通りに綴る: 「ツーエックス ファスター」、「エーピーアイ」は綴る必要がある場合のみ、「ドットコム」。記号、絵文字、スラッシュを含むURL、括弧は避けてください。
  • 短い文。ユーザーから与えられた場合は、明確なCTAで終了してください。

SFX(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. スクリプトを表として表示し、停止:

    #時間単語数 / 予算ナレーションSFX
    10:00.4–0:04.611 / 10 ⚠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. SFX + 音声の生成

"$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。SFXのバリエーションを変更: --seed 7。

5. レンダリング

"$PY" "$SKILL/scripts/render_video.py" "$WORK/script.json"
  • クリップを start の位置に配置し、重なりを防ぎます。小さなオーバーランはピッチを保持した atempo 圧縮(≤ 1.12倍)を行い、残りは後続のクリップをずらします(ドリフトとして表示)。ナレーションが動画より長い場合は、最後のフレームを保持します。
  • 音声 + SFXをミックスし、ラウドネスを−16 LUFSに正規化し、字幕を焼き付け(Pillowでレンダリングしたカード + FFmpegの overlay を使用。libassは不要)、$WORK/output_final.mp4 と subtitles.srt を書き込みます。
  • オプションのBGM(オリジナル、ローカルで合成、ライセンス不要): "$PY" "$SKILL/scripts/generate_bgm.py" --duration <動画の秒数> --out "$WORK/bgm.wav"(スタイル: positive(デフォルト)= アコースティックギターの16分音符ピッキングと響く開放弦、各ビートに温かいコードストローク、4つ打ちキック、シンコペーションのリム/クラップ、オフビートのベース、柔らかいプルークリード、111 BPM、トラック中盤にブレイク、B2Bデモのリファレンスをモデル化; demo-bright / demo-dorian = SaaSデモのグルーヴ、製品デモトラックをモデル化: 110 BPM、8分音符で脈動し柔らかいキックでポンピングする温かいコード、2拍目と4拍目にクラップ、8分音符のハイハット、コードルートのベース、持続するトップライン、軽やかなプルークメロディ、イントロ → グルーヴ → トラック中盤の8小節ブレイク → グルーヴ → クリーンエンド; uke、marimba、pluck、kalimba = 明るいソフトウェアデモ用BGM、シンプルなソフトキック + スナップ/クラップ + シェイカービートと少しのベースの上に1つのプルーク/マレットモチーフ、100–112 BPM、メジャーキー; lofi(デフォルト)= スウィングしたビートとドラムの落ち着いた感じ; keys = エレクトリックピアノ; upbeat = 4つ打ち + アルペジオ; ambient = パッドのみ。--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. 字幕をスポットチェック: ffmpeg -ss <t> -i "$WORK/output_final.mp4" -frames:v 1 "$WORK/check_<t>.jpg" を2~3のセグメント中間点で実行し、画像を表示 — キャプションが読みやすく、重要なUIを覆っていないことを確認。重要なものを覆っている場合は、--font-scale を検討するか、ユーザーに伝えてください。
  3. 報告: 出力パス、時間、使用したエンジン/音声、速度を上げたりシフトしたセグメント、および調整方法(script.json を編集 → ステップ4〜5を再実行。テキスト編集は再度ゲートを通過)。

トラブルシューティング

症状修正
kokoro unavailable … trying fallbacksetup.sh を再実行。.venv 内のPythonが3.10~3.12であることを確認。Piperの出力は問題ないが、自然さは劣ります。
単語/名前の発音が間違っているtext で発音どおりに綴り直す(例: 「Kubernetes」→「クーバーネティーズ」)、承認を得て、--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。

関連スキル