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. 事前準備
$PYが存在しない場合、ユーザーに説明します: セットアップではffmpeg + espeak-ng(Homebrew/apt)、Python 3.12仮想環境、PyTorch、および約400 MBのモデル重みがインストールされます。「はい」の場合、bash "$SKILL/setup.sh"を実行してください(数分かかります。バックグラウンドで実行してください)。- 動画の隣に作業ディレクトリを作成:
WORK="<動画ディレクトリ>/demo-narrator-work/<動画のファイル名(拡張子なし)>"。スキルディレクトリには絶対に書き込まないでください。 - 質問する(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. ⛔ スクリプト承認ゲート — 必須
ユーザーが明示的にスクリプトを承認するまで、音声を生成しないでください。
-
スクリプトを表として表示し、停止:
# 時間 単語数 / 予算 ナレーション SFX 1 0:00.4–0:04.6 11 / 10 ⚠ 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. 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. 報告前の確認
- レンダリングの出力を確認: ドリフト列が約0であること、ホールドフレーム警告がないこと(またはその説明があること)。
- 字幕をスポットチェック:
ffmpeg -ss <t> -i "$WORK/output_final.mp4" -frames:v 1 "$WORK/check_<t>.jpg"を2~3のセグメント中間点で実行し、画像を表示 — キャプションが読みやすく、重要なUIを覆っていないことを確認。重要なものを覆っている場合は、--font-scaleを検討するか、ユーザーに伝えてください。 - 報告: 出力パス、時間、使用したエンジン/音声、速度を上げたりシフトしたセグメント、および調整方法(
script.jsonを編集 → ステップ4〜5を再実行。テキスト編集は再度ゲートを通過)。
トラブルシューティング
| 症状 | 修正 |
|---|---|
kokoro unavailable … trying fallback | setup.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。