mkt-hyperframe-talking-head-video は何をしますか？
MP4 9:16 トーキングヘッドから、キャプション、SFX、ズームフック、リッチエフェクト付きBロール、CTAを備えたHyperFramesプレビュープロジェクトを構築するパイプラインです。
使用するタイミング
- ユーザーが9:16のフェイスカム動画（TikTok/Reels/Shorts）を録画済みで、キャプション、ビジュアルフック、SFXを追加したい場合
- ユーザーが追加の画像や動画Bロールを（使用目的と共に）埋め込みたい場合
- ユーザーがMP4レンダリング前にプレビュースタジオでビジュアルを確認したい場合
以下の場合はこのスキルを使用しないでください:
- ユーザーがまだ動画を録画していない場合 — 事前に
mkt-create-script-short-videoを使用してスクリプトを作成するか、AIナレーション＋アバター動画作成には別のスキルを使用してください - ユーザーが既存のHyperFramesプロジェクトを持っており、微調整のみを行いたい場合 — 再生成ではなく、ファイルを直接編集してください
- ユーザーが既存のプロジェクトからMP4をレンダリングしたい場合 —
npx hyperframes renderを直接実行してください
パイプライン概要
MP4 9:16 トーキングヘッド + (オプション) Bロールファイル
│
▼
1. MP4を検査 ────────── ffprobe → 長さ、解像度、FPS
│
▼
2. 構造を計画 ───────── ユーザー入力または文字起こしから自動でレッスンマーカーを検出
│
▼
3. 文字起こし ────────── npx hyperframes transcribe --model medium --language vi
│
▼
4. 文字起こしをクリーニング ──── VN Whisperエラー辞書を適用 (alphabit→Alphabet など)
│
▼
5. キャプションをグループ化 ──── 3〜5単語/グループ、0.45秒以上のギャップで分割、タイミング保持
│
▼
6. Bロールをマッピング ──────── ユーザーに目的を確認 → レッスンシーンに割り当て
│
▼
7. プロジェクトを生成 ──────── workspace/video-projects/<slug>/
├── index.html (ルート)
├── source.mp4
├── transcript.json + caption-groups.json
├── compositions/
│ ├── captions.html
│ ├── fs-lesson-N.html (レッスンごとに1つ、エフェクトは変化)
│ ├── recap-card.html (該当する場合)
│ └── fs-cta.html
└── sfx/ (6つの効果音)
│
▼
8. Lint ──────────────── npx hyperframes lint → エラー修正
│
▼
9. プレビューを開く ──────── npx hyperframes preview (バックグラウンド) → Studio URL
│
▼
10. ユーザーに引き継ぐ ──── MP4は自動レンダリングしない
プレビュー優先ルール（必須）: スキルはステップ9で終了し、Studio URLを提供します。MP4レンダリングは、ユーザーがプレビュー後に明示的に確認した場合のみ実行します。
ステップ 1: 入力確認と計画
ユーザーは以下を提供します:
| 入力 | 必須 | 形式 |
|---|---|---|
| MP4フェイスカム9:16 | はい | ファイルパス |
| スラッグ / プロジェクト名 | いいえ | ファイル名から自動生成、指定も可 |
| Bロールリスト | いいえ | [{path: "screenshot.png", purpose: "レッスン1 — 実験の図解"}, ...] |
| 動画構成 | いいえ | "3レッスン＋イントロ＋CTA" / "5つのコツ" など — 指定がなければ自動検出 |
MP4を検査してから次に進みます:
ffprobe -v error -show_entries format=duration:stream=codec_type,width,height,r_frame_rate \
-of json "<mp4_path>"
確認事項:
- 解像度が9:16であること (例: 1080x1920, 1440x2560) — 横向きの場合は警告しますが、処理は続行します（object-fit:coverでクロップされます）
- 長さが180秒未満が理想的、180秒超でも処理は可能ですが、TikTokのアルゴリズムは90秒以下を好むと警告します
- FPS 24/25/30/60 は全てOK — 出力はデフォルト30fps
スラッグ: ファイル名から生成、小文字、ベトナム語記号→ASCII、スペース→ダッシュ。例 "3 bài học .mp4" → 3-bai-hoc。ユーザーは上書き可能です。
出力ディレクトリ: workspace/video-projects/<slug>/
ステップ 2: 文字起こしとクリーニング
cd workspace/video-projects/<slug>/
cp <user_mp4> source.mp4
npx hyperframes transcribe source.mp4 --model medium --language vi
ベトナム語音声に対しては 決して --model medium.en や small.en を使用しないでください — .en モデルは文字起こしではなく英語に翻訳します。ベトナム語音声には常に --language vi を使用してください。
完了後、文字起こしをクリーニング:
python3 .claude/skills/mkt-hyperframe-talking-head-video/scripts/clean_transcript.py \
transcript.json
# 出力: transcript.json (インプレースクリーニング) + caption-groups.json (自動グループ化)
このスクリプトはVN Whisperのエラー置換（alphabit→Alphabet、Cod→Code、dụng/dùng 文脈認識、đ��ng→đắc など）を適用し、0.45秒以上のギャップで3〜5単語のキャプションフレーズに自動グループ化します。
重要なキャプション同期ルール: タイミングは単語レベルの文字起こしから正確に保持しなければなりません。タイミングを手動編集しないでください。テキスト修正が必要な場合はテキストのみを編集してください — clean_transcript.py スクリプトが処理済みです。よくあるバグ: テキストを手動編集した際に誤ってタイミングを変更し、動画途中でキャプションが5秒ずれる問題が発生します。
ステップ 3: シーン構造を検出
python3 .claude/skills/mkt-hyperframe-talking-head-video/scripts/detect_scenes.py \
transcript.json
# 出力: scenes.json
スクリプトは文字起こしから以下のマーカーを検索:
- "Bài học đầu tiên / thứ 2 / thứ 3 / thứ N" → レッスンシーン
- "Tips số 1 / Tip 1 / Số 1" → ヒントシーン
- "Tổng kết lại / Recap / Kết luận" → まとめの瞬間
- "Comment / Đăng ký / Like / Theo dõi" → CTAの瞬間
出力 scenes.json:
{
"type": "lessons",
"scenes": [
{ "kind": "lesson", "num": 1, "start": 9.4, "end": 13.0, "kicker": "Bài học #1", "heading": "..." },
{ "kind": "lesson", "num": 2, "start": 34.5, "end": 38.0, ... },
{ "kind": "lesson", "num": 3, "start": 61.5, "end": 65.5, ... },
{ "kind": "recap", "start": 84.9, "end": 99.0 },
{ "kind": "cta", "start": 99.0, "end": 106.94 }
]
}
自動検出で明確な構造が見つからない場合（例: 自由形式のVlog）、結果をユーザーに提示して確認を求めます。ユーザーはタイムスタンプを上書きできます。
ステップ 4: Bロールをマッピング
ユーザーがBロールファイルを目的と共に提供する場合:
[
{ path: "alphabet-screenshot.png", purpose: "レッスン1 — Alphabet ship beta" },
{ path: "clock-icon.mp4", purpose: "レッスン2 — 24時間の図解" },
{ path: "team-meeting.png", purpose: "レッスン3 — チームの壁を取り除く" }
]
マッピングロジック:
- 各Bロールは、目的内のテキスト "レッスンN" に基づいて1つのシーンとマッチング
- 画像 → そのシーンの全画面背景として使用（テキストのみの生成シーンを置き換え）
- 動画 → 全画面シーン背景またはピクチャーインピクチャーオーバーレイとして使用（デフォルト: 全画面）
- デフォルトのシーンエフェクト（パルスリング、コーナーマークなど）は、Bロール画像/動画の上にレイヤーされます
ユーザーがBロールを提供しない場合は、テキストのみのシーン（参考プロジェクト 3-bai-hoc/ と同様）を使用します — タイトル、大きな数字、サブテキストで構成されたテキストカードを生成します。
ステップ 5: プロジェクトファイルを生成（インフォグラフィックスタイル — デフォルト）
コンテンツ駆動型のモックアップBロールには infographic v2 ジェネレーターを使用します（Hostinger インスパイアスタイル: ダークガラスモーフィズム + ネオングロー + UIモックアップ + フローティングデータバッジ）:
python3 .claude/skills/mkt-hyperframe-talking-head-video/scripts/scaffold_infographic_v2.py \
--output workspace/content/YYYY-MM-DD/<slug>/compositions/ \
--scenes scenes.json
scenes.json スキーマ（シーンごと、mockup_variant + content を含む）:
{
"scenes": [
{
"kind": "lesson",
"num": 1,
"start": 12.71,
"end": 26.40,
"kicker": "AIコンサル",
"heading": "1つの業界に対するAIコンサル",
"accent_words": [2],
"mockup_variant": "post-stack",
"content": { "posts": [...] },
"badges": [
{ "pos": "tr", "color": "orange", "icon": "📅", "num": "30", "label": "日間" }
]
},
{ "kind": "recap", "mockup_variant": "team-grid", "content": {...} },
{ "kind": "cta", "mockup_variant": "comment-box", "content": {...} }
]
}
7つのモックアップバリアント — シーンのセマンティクスに合うものを選択:
| シーンタイプ | バリアント | 使用シーン |
|---|---|---|
| パーソナルブランディング / 投稿 | post-stack | 3つのソーシャルカードスタック、上部ハイライト、エンゲージメント表示 |
| AI検索 / GEO | ai-window | ChatGPTスタイルウィンドウ、関連カードハイライト |
| 音声 / 電話 / 通話 | phone-call | iPhoneモックアップ、波形＋エージェントバブル＋スロットグリッド |
| 分析 / ダッシュボード | dashboard | 統計、クリエイティブグリッド、折れ線グラフ付きガラスカード |
| プロダクト / SaaSローンチ | app-card | アイコン、統計、オプションのメタファー行付きアプリカード |
| 前後比較のまとめ | team-grid | 40ドットグリッドモーフ、アニメーションカウントダウン＋乗数 |
| CTA「コメントX」 | comment-box | コメントボックスモックアップ＋2つのギフトカード＋CTAピル |
完全なコンテンツスキーマ＋デザイントークン: references/infographic-design-system.md を参照。
共通シェル要素（全シーンに自動適用）: ラジアルグラデーション背景＋シアングリッド線＋10個のSVGパーティクル（ドリフトループ）＋ビネット＋トピックピル（オレンジグロー）＋ブランドタイトル110px（単語ごとにスラムイン、アクセントグラデーション）。
フローティングバッジ（シーンあたり1〜4個、オプション）: ヒーローモックアップの周囲に130pxの円形バッジ、アイコン＋数字＋ラベル、カラーコード（シアン/紫/オレンジ/緑）、対応するグロー、画面外からアニメーション＋ボブループ。
レガシージェネレーター（非推奨）
scaffold_project.py（リング/コーナー/ライトスイープの抽象装飾） — 後方互換性のために維持されていますが、新規動画には推奨しません。新しい動画には scaffold_infographic_v2.py を使用してください。
各シーンには:
.scene-contentへのパンチズームエントランス（交互にズームイン1.12 / ズームアウト0.92）- エレメントエントランス: アイブロウ → 番号 → タイトル（単語ごとにスラムイン） → サブテキスト
- シーン中のアンビエントエフェクト（パルスリング、ブレス、ドリフトなど）
- 終了アニメーションなし — クリップ終了、フレームワークが非表示
サブコンポジションルール: 内部タイムラインは RELATIVE 0 → data-duration、絶対値ではありません。data-composition-src="compositions/<name>.html" data-start = scene.start でルートにマウント。
ステップ 6: SFXをコピー
mkdir -p workspace/video-projects/<slug>/sfx
SFX_SRC="$(git rev-parse --show-toplevel)/.claude/skills/mkt-hyperframe-talking-head-video/assets/sfx"
cp "$SFX_SRC"/{camera-flash.mp3,"búng tay.mp3","Whoosh sound effect (1).mp3",Laser.mp3,ting.mp3,"Discord Notification - Sound Effect.mp3"} workspace/video-projects/<slug>/sfx/
6つのSFX標準マッピング:
| 時間 | ファイル | 音量 | タイミング |
|---|---|---|---|
| 0.0s | camera-flash.mp3 | 0.32 | フックオープナー — ソース動画パンチズーム @0s と同期 |
| レッスン1開始 − 0.05s | búng tay.mp3 (スナップ) | 0.30 | レッスン1表示 |
| レッスン2開始 − 0.05s | Whoosh sound effect (1).mp3 | 0.22 | レッスン2トランジション |
| レッスン3開始 − 0.05s | Laser.mp3 | 0.28 | レッスン3パンチ |
| まとめ開始 − 0.05s | ting.mp3 | 0.20 | まとめ表示 |
| CTA開始 | Discord Notification - Sound Effect.mp3 | 0.28 | CTA通知感 |
SFX音量ルール（references/sfx-library.md による）: フック 0.25-0.35、トランジション 0.15-0.2、CTA 0.25。SFXは最大5〜6個、1.5秒以上の間隔を空ける。
ステップ 7: Lint + プレビューを開く
cd workspace/content/YYYY-MM-DD/<slug>/
npx hyperframes lint
警告は許容:
composition_file_too_large— 情報のみ、ルートでは無視して問題ありませんcomposition_self_attribute_selector— 情報のみ、インフォグラフィックモックアップはスコープ化された[data-composition-id="..."]セレクターを使用
エラーは拒否:
gsap_animates_clip_element— クリップの visibility/display をアニメーションさせないでください — opacity のみアニメーション可能root_composition_missing_data_start— サブコンポは内部 div にdata-start="0"が必要media_missing_data_start—<audio>SFX はdata-start属性を持つ必要があります（HFネイティブスケジューリング、JSトリガーは使用不可）- キャプション同期の問題 — clean_transcript.py スクリプトを再実行
重要: キャプションのZオーダー
キャプションサブコンポは、レッスンサブコンポ（全画面の暗い背景を持つ）の上にレンダリングされるように、最も高い data-track-index でマウントする必要があります。そうしないと、キャプションがBロールの背後に隠れます。
<!-- レッスン/まとめ/CTA マウント: track-index 40-47 -->
<div class="clip split-mount" data-composition-src="compositions/fs-lesson-1.html" data-start="..." data-track-index="40"></div>
<!-- ... -->
<!-- キャプションは最後に track 60 + インラインz-index で -->
<div class="clip captions-mount"
data-composition-src="compositions/captions.html"
data-start="0" data-duration="..." data-track-index="60"
style="z-index: 100;"></div>
ステップ 7.5: スプリットスクリーン＋全顔ブレスレイアウト（トーキングヘッド＋Bロールに推奨）
トーキングヘッドとBロールモックアップの両方を表示する必要がある動画にはこれを使用してください — Bロールが顔を覆い隠す全画面表示の代わりに。
アーキテクチャ:
- 顔動画はイントロ中はデフォルトで全画面
- Bロール出現時: 顔は下半分（1080x960）に縮小、Bロールは上半分（スケール0.5）にレンダリング
- 各Bロール終了時（次のシーンの1.5秒前）: 顔が全画面に拡大（「ブレス」モーメント） → 感情的な決めゼリフを捉える
- キャプションは中央（分割モード）と下部（全顔モード）で自動的にアニメーション
スプリットスクリーンが組み込まれたルートindex.htmlを生成:
python3 .claude/skills/mkt-hyperframe-talking-head-video/scripts/generate_root_index.py \
--output workspace/content/YYYY-MM-DD/<slug>/index.html \
--scenes scenes.json \
--total-duration 108.92 \
--header-label "6 AI BUSINESS 2026" \
--footer-handle "@tranvanhoang.com"
scenes.json にはシーンごとに brollEnd + hasBreath を含める必要があります。編集ルール（全画面 vs 分割のタイミング）、CSSについては references/split-screen-pacing.md を参照してください。
ステップ 8: ルート合成を構築
最終的なindex.html構造（スプリットスクリーン推奨、ステップ7.5）:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="hyperframes-spec" content="v1.0.0" />
<title>3-bai-hoc — HyperFrames Preview</title>
<link rel="stylesheet" href="https://unpkg.com/hyperframes/dist/hyperframes.css" />
<link rel="stylesheet" href="compositions/global.css" />
</head>
<body>
<!-- フェイスカムレイヤー（全画面デフォルト、Bロール中は下半分にトリミング） -->
<div class="clip" data-src="source.mp4" data-start="0" data-duration="108.92"
data-track-index="30" data-geometry="fullscreen" data-picture-in-picture="source:split-full"
style="z-index: 1; object-fit: cover;"></div>
<!-- レッスン/まとめ/CTA モックアップ（トラック40〜47） -->
<div class="clip split-mount" data-composition-src="compositions/fs-lesson-1.html" data-start="12.71" data-duration="13.69" data-track-index="40" data-geometry="split-top"></div>
<div class="clip split-mount" data-composition-src="compositions/fs-lesson-2.html" data-start="26.40" data-duration="15.13" data-track-index="41" data-geometry="split-top"></div>
<div class="clip split-mount" data-composition-src="compositions/fs-lesson-3.html" data-start="41.53" data-duration="14.69" data-track-index="42" data-geometry="split-top"></div>
<div class="clip split-mount" data-composition-src="compositions/fs-recap.html" data-start="56.22" data-duration="13.99" data-track-index="43" data-geometry="split-top"></div>
<div class="clip split-mount" data-composition-src="compositions/fs-cta.html" data-start="70.21" data-duration="38.71" data-track-index="44" data-geometry="split-top"></div>
<!-- SFXオーディオ（トラック50） -->
<div class="clip" data-src="sfx/camera-flash.mp3" data-start="0" data-duration="3" data-track-index="50" data-volume="0.32"></div>
<!-- ... -->
<!-- キャプション（トラック60、常に上部） -->
<div class="clip captions-mount" data-composition-src="compositions/captions.html" data-start="0" data-duration="108.92" data-track-index="60" style="z-index: 100;"></div>
</body>
</html>
トラックインデックスガイドライン:
| レイヤー | トラックインデックス範囲 | Z範囲 |
|---|---|---|
| フェイスカムソース | 30〜39 | 1〜10 |
| Bロール/モックアップシーン | 40〜47 | 11〜50 |
| SFXオーディオ | 50〜59 | (該当なし) |
| キャプション | 60+ | 100〜 |
ステップ 9: ハンドオフ
✅ プロジェクト準備完了: workspace/video-projects/<slug>/
📊 プレビュースタジオを開いています...
npx hyperframes preview
プレビュースタジオURLが準備できました:
http://localhost:3000/?project=workspace/video-projects/<slug>/
📋 ユーザーへの指示:
1. ブラウザでプレビュースタジオを開く
2. 各シーンのタイミングとキャプションの同期を確認
3. 問題がなければ: `npx hyperframes render` を実行してMP4をエクスポート
4. 調整が必要なら: ファイルを直接編集するか、新しいプロンプトで依頼
references/infographic-design-system.md — インフォグラフィックモックアップのデザイントークンとコンテンツスキーマの完全なリファレンス。 references/split-screen-pacing.md — 全画面 vs 分割モードの編集ルール。 references/sfx-library.md — SFX音量ガイドラインと配置ルール。