mkt-full-video-with-11-hyperframe-heygen

mkt-full-video-with-11-hyperframe-heygen は何をしますか？

エンドツーエンドのオーケストレーター: スクリプト → 完成したTikTok/Reels MP4 9:16。

パイプラインには 2つのユーザーチェックポイント があります:

1. MP3チェックポイント (オーケストレーター) — フェーズ1完了後、ユーザーがボイスオーバーを確認。
2. シーンアウトラインチェックポイント (フェーズ3サブエージェント) — ユーザーがシーン構造とバリアントを確認してから、コンテンツライターを並列実行します。ユーザーが auto_scenes=true を指定した場合はスキップ可能。

使用するタイミング

• ユーザーがベトナム語または英語のスクリプト（最大5000文字）を持ち、完成したTikTok動画を希望する場合
• （オプションで）Bロール用の画像や動画とその使用目的が既にある場合
• スクリプトからStudioプレビューまでを一貫して処理したい場合

次の場合はこのスキルを使用しません:

• ユーザーが既にMP3を持っている場合 → heygen-mp3-to-mp4 を直接使用
• ユーザーが既にトーキングヘッドのMP4を持っている場合 → mkt-hyperframe-talking-head-video を直接使用
• HeyGenにテキストを直接読み上げさせたい場合（ElevenLabsを経由しない） → heygen-script-to-mp4 を使用
• スクリプトが5000文字を超える場合 → 意味的に分割して、各セグメントにパイプラインを呼び出し

パイプライン概要

Script (text + optional b-roll + tts_provider)
    │
    ▼
Phase 1 ── TTS (elevenlabs | minimax) ──► voiceover.mp3
    │                                         │
    │                                         ▼
    │                              CHECKPOINT #1 — user nghe + duyệt MP3
    │                                         │
    │                                         ▼ (OK)
Phase 2 ── heygen-mp3-to-mp4 ──────────► source.mp4 (9:16 lip-sync)
    │
    ▼
Phase 3 ── spawn agent mkt-full-video-phase3-packager (isolated context)
            │
            ├─ transcribe + clean + group captions
            ├─ detect scene boundaries + classify mockup_variant
            ├─ CHECKPOINT #2 — user duyệt scenes outline
            ├─ FAN-OUT N general-purpose sub-agents (1 per scene) parallel
            │   → mỗi sub-agent build content JSON theo variant schema
            ├─ merge → scenes.json
            ├─ parallel: scaffold sub-comps + copy SFX + inject captions
            ├─ generate root index.html
            └─ lint + preview Studio
    │
    ▼
User duyệt preview → "render" → final MP4

チェックポイントルール: オーケストレーターはチェックポイント#1（MP3）を管理します。フェーズ2と3は自動実行されます。チェックポイント#2（シーンアウトライン）はフェーズ3のサブエージェントが管理します。Studioでの最終レンダリングはユーザーが決定します。

入力

入力	必須	形式 / 例
Script text	はい	ファイルパス（.txt/.md）またはインライン文字列。最大5000文字。
Slug project	いいえ	スクリプトの最初の5単語から自動生成。小文字、ASCII、ハイフン。
B-roll list	いいえ	配列 [{path: "...", purpose: "Bài học 1 — minh họa X"}, ...]。
tts_provider	いいえ	elevenlabs（デフォルト — Hoàngの声、表現力豊か）または minimax（speech-2.8-hd、低コスト、ベトナム語が自然）。ユーザーが「minimax使って」/「eleven使って」と言った場合に設定。
Voice ID override	いいえ	デフォルトを .env からオーバーライド。ElevenLabsは ELEVENLABS_VOICE_ID、MiniMaxは MINIMAX_VOICE_ID を読み込み。CLIフラグ --voice_id は両方に使用可能。
Voice settings override	いいえ	ElevenLabs: {stability, similarity_boost, style}。MiniMax: {speed, vol, pitch}。
Avatar look	いいえ	HEYGEN_AVATAR_LOOKS 環境変数（.env、カンマ区切り）から取得した1つのID。未指定の場合はランダム選択。
auto_scenes	いいえ	デフォルト false。true にするとフェーズ3のシーンアウトラインチェックポイントをスキップ。

ワークスペース構成

workspace/content/YYYY-MM-DD/<slug>/
├── script.txt              # Phase 0
├── voiceover.mp3           # Phase 1
├── source.mp4              # Phase 2
├── broll/                  # User-provided b-roll (copy)
├── transcript.json         # Phase 3
├── caption-groups.json     # Phase 3
├── scenes-outline.json     # Phase 3 — pre-checkpoint outline
├── scenes/                 # Phase 3 — fan-out per-scene content writes here
│   ├── scene-1.json
│   └── ...
├── scenes.json             # Phase 3 — merged final
├── compositions/           # Phase 3 — HF sub-comps
├── sfx/                    # Phase 3 — 6 SFX
└── index.html              # Phase 3 — root composition

YYYY-MM-DD は本日の日付（UTC+7）。

ワークフロー

Step 0 — Setup

1. len(script_text) <= 5000 を検証。超えた場合は停止し、ユーザーに意味的な分割を依頼。
2. スラッグが不足している場合は導出: 最初の5単語 → 小文字 → アクセント除去 → スペース→ハイフン。
3. TTSプロバイダーの解決 — ユーザー入力から tts_provider を読み取り（デフォルト elevenlabs）。ユーザーが「minimax使って」/「minimaxに変更」と言った場合 → minimax。ユーザーが「eleven使って」/「elevenlabs」と言った場合 → elevenlabs。対応するAPIキーが .env にあるか検証:
   • elevenlabs → ELEVENLABS_API_KEY が必要（オプションで ELEVENLABS_VOICE_ID によりデフォルト K7ewtjKRNtwwt3lKQ6M0 をオーバーライド可能）。
   • minimax → MINIMAX_API_KEY が必要（オプションで MINIMAX_VOICE_ID によりデフォルト moss_audio_c56d6120-ef9c-11f0-9649-8ee40147f116 をオーバーライド可能）。 キーがない場合は停止し、ユーザーに .env へ追加するよう通知。
4. workspace/content/YYYY-MM-DD/<slug>/ を作成。script.txt を保存。
5. ユーザーがBロールを持っている場合: <folder>/broll/ を作成し、元のファイル名を保持してコピー。
6. ユーザーに通知: "ワークスペースを作成しました: <folder>。TTSプロバイダー: <elevenlabs|minimax>。フェーズ1を開始します。"

Step 1 — Phase 1: Script → MP3 (TTS)

tts_provider に応じて、2つの分岐のうち正しい方を実行:

分岐 A — ElevenLabs (デフォルト):

uv run .claude/skills/mkt-elevenlabs-tts-to-mp3/scripts/text_to_mp3.py \
  --file workspace/content/YYYY-MM-DD/<slug>/script.txt \
  -o workspace/content/YYYY-MM-DD/<slug>/voiceover.mp3

Voice ID: .env から ELEVENLABS_VOICE_ID を自動読み取り（フォールバックはデフォルトのHoàngブランドボイス）。CLIオーバーライド: --voice_id <id>。 Voice settings: ユーザーが調整を要求した場合、--stability / --similarity_boost / --style を追加。

分岐 B — MiniMax:

uv run .claude/skills/mkt-video-script-to-mp3/scripts/text_to_mp3.py \
  --file workspace/content/YYYY-MM-DD/<slug>/script.txt \
  -o workspace/content/YYYY-MM-DD/<slug>/voiceover.mp3

Voice ID: .env から MINIMAX_VOICE_ID を自動読み取り（フォールバックはデフォルト moss_audio_…）。CLIオーバーライド: --voice_id <id>。 Voice settings: --speed（デフォルト 1.08）、--vol、--pitch、--language_boost Vietnamese。

出力ファイル名は両分岐とも不変: voiceover.mp3。フェーズ2（HeyGen）が正しいパスを見つけられるようにするため。

完了後、（両方のプロバイダー共通で）再生時間を確認:

uv run .claude/skills/heygen-mp3-to-mp4/scripts/check_duration.py \
  workspace/content/YYYY-MM-DD/<slug>/voiceover.mp3

TOO_LONG → 停止。MP3が5分を超えていることをユーザーに通知し、スクリプトの短縮を依頼。

Step 2 — CHECKPOINT #1: user nghe MP3

オーケストレーターが管理する唯一の停止ポイント。 以下の正確な形式でユーザーに通知:

## Voiceover ready — duyệt giúp mình

**File:** `workspace/content/YYYY-MM-DD/<slug>/voiceover.mp3`
**Duration:** <X.X>s
**Size:** <Y.Y> MB
**Provider:** <`elevenlabs` | `minimax`>
**Voice:** <`ElevenLabs Brand Voice của Hoàng (K7ewtjKRNtwwt3lKQ6M0)`> hoặc <`MiniMax speech-2.8-hd (moss_audio_…)`> (lấy từ `.env` voice ID nếu user override)

Mở file nghe thử. Reply 1 trong:
- **`OK`** / **`tiếp`** → mình chạy Phase 2 (HeyGen avatar lip-sync)
- **`regen`** + (optional) lý do → mình tweak voice settings và regen MP3
- **`sửa script`** + nội dung mới → mình save script mới và rerun Phase 1

ツール呼び出しを停止。 ユーザーからの明確な返信を待ちます。

ユーザーが OK → フェーズ2へ。 ユーザーが regen → 現在のプロバイダーのTTSスクリプトを新しい設定で再実行し、チェックポイントに戻る。ユーザーが「minimaxに変更」/「elevenを試す」と言った場合 → tts_provider を交換し、フェーズ1を再実行。 ユーザーがスクリプトを修正 → script.txt を上書きし、フェーズ1を最初から再実行（同じプロバイダー）。

Step 3 — Phase 2: MP3 → HeyGen MP4 (auto)

サブスキル heygen-mp3-to-mp4 に従う:

1. アバターIDを選択 — .env から HEYGEN_AVATAR_LOOKS を読み取り（カンマ区切り）、ユーザーが指定しない場合はランダム選択:

   HEYGEN_AVATAR_LOOKS=$(grep '^HEYGEN_AVATAR_LOOKS=' .env | cut -d'=' -f2- | tr -d '"' | tr -d "'")
   echo "$HEYGEN_AVATAR_LOOKS" | tr ',' '\n' | awk 'BEGIN{srand()} {a[NR]=$0} END{print a[int(rand()*NR)+1]}'
   

   環境変数がないか空の場合 → 停止し、ユーザーに HEYGEN_AVATAR_LOOKS=<id1>,<id2> を .env に追加するよう通知。MCPを呼び出す前にユーザーに選択を促す。

2. MP3をHeyGenにアップロード（MCP経由、upload_asset、アセットタイプ audio）。https://upload.heygen.com/... へのcurlは使用しない。

3. アバタービデオを生成（MCP経由、generate_avatar_video）:

   character: { type: avatar, avatar_id: <picked>, scale: 1.0 }
   voice:     { type: audio, audio_asset_id: <from upload> }
   dimension: { width: 720, height: 1280 }   # 9:16
   title:     "<slug>-<timestamp>"
   

4. ステータスをポーリング（約10秒ごと）→ completed（最大10分）。failed → 停止し、エラーを表示。

5. MP4をダウンロード → workspace/content/YYYY-MM-DD/<slug>/source.mp4（ファイル名不変）:

   uv run .claude/skills/heygen-mp3-to-mp4/scripts/download_video.py \
     "<video_url>" "workspace/content/YYYY-MM-DD/<slug>/source.mp4"
   

6. ユーザーに1行で通知: "フェーズ2完了 — <path>（アバター <id>、秒、MB）。フェーズ3パッケージャーを起動中…"

ここでは停止しない。 フェーズ3に自動フロー。

Step 4 — Phase 3: Spawn packager sub-agent

subagent_type: "mkt-full-video-phase3-packager" でTaskツールを使用。エージェントが必要とする入力を含む自己完結型のプロンプトを渡します。例:

Workspace: workspace/content/2026-05-03/hom-nay-minh-chia-se/
Slug: hom-nay-minh-chia-se
Script: <full script text>
B-roll: [
  {"path": "workspace/content/2026-05-03/hom-nay-minh-chia-se/broll/alphabet.png", "purpose": "Bài học 1"},
  ...
]
auto_scenes: false
header_label: "3 BÀI HỌC AI"
footer_handle: "@tranvanhoang.com"

Run the full Phase 3 packaging pipeline per your agent definition. Return Studio URL when preview is open.

サブエージェントは:

• source.mp4 を文字起こし、シーンアウトラインを構築
• auto_scenes: true でない限り、ユーザーにアウトラインの承認を求めて停止（チェックポイント#2）
• N個のシーンコンテンツライターを並列実行
• マージ + スキャフォールド + lint + プレビューを開く
• Studio URLを返す

サブエージェントの実行中、オーケストレーターの唯一の仕事は、ユーザーの返信をサブエージェントに中継することです（シーンアウトラインチェックポイントでのユーザー返信はこの会話に届きます。サブエージェントがまだアクティブな場合はそれにルーティングし、そうでない場合はフォローアップ指示として扱います）。

Step 5 — Hand off

サブエージェントがStudio URLを返したら、最終レポートをフォーマット:

## Full video pipeline DONE — preview ready

**Workspace:** `workspace/content/YYYY-MM-DD/<slug>/`

**Phase 1 (`<elevenlabs|minimax>`):** voiceover.mp3 — <D1>s, <S1>MB (voice ID `<id>`)
**Phase 2 (HeyGen):** source.mp4 — avatar `<avatar_id>`, <D2>s, <S2>MB
**Phase 3 (HyperFrames):** <N> scenes (<list variants>), <K> caption groups, 6 SFX

**Studio URL:** http://localhost:3002

Mở browser scrub timeline. Nói **`render`** khi OK → mình chạy `npx hyperframes render` xuất MP4 1080×1920 30fps.

ここで停止。 自動レンダリングは行いません。ユーザーが確認してから npx hyperframes render を呼び出します。

重要なオーケストレーションルール

1. 2つのユーザーチェックポイント、1つのオーケストレーターゲート — オーケストレーターはMP3チェックポイント（Step 2）でのみ停止します。シーンアウトラインチェックポイントはフェーズ3のサブエージェントが管理します。Studioでのレンダリングゲートはユーザーが決定します。

2. パス規則は不変 — ボイスオーバーは voiceover.mp3、トーキングヘッドは source.mp4 でなければなりません。HFサブスキルは source.mp4 という名前を期待します。

3. HeyGen MCPのみ — https://api.heygen.com/... にcurlすることは絶対にしないでください。heygen-mp3-to-mp4 のハード制約です。

4. Voice IDは .env に保存、スキル内にハードコードしない。 ElevenLabsは ELEVENLABS_VOICE_ID を読み取り（フォールバック K7ewtjKRNtwwt3lKQ6M0）。MiniMaxは MINIMAX_VOICE_ID を読み取り（フォールバック moss_audio_…）。呼び出しごとのオーバーライドは --voice_id 経由。パイプラインはStep 0とチェックポイント#1で、選択されたプロバイダーとVoice IDを明確に通知します。

5. スクリプト長のハードキャップは5000文字 — Step 0.1で早期失敗。

6. MP3再生時間 ≤ 300秒 — HeyGenの単一動画制限。フェーズ1完了直後に確認。

7. プレビュー優先 — フェーズ3は自動レンダリングしません。feedback_hyperframes_workflow.md を記憶。

8. フェーズ3の分離 — フェーズ3は独立したサブエージェントコンテキストで実行。HFスキル本文と4つのリファレンスドキュメント（約40KB）はメインのオーケストレーターではなくサブエージェントに読み込まれます。

障害モードとフォールバック

症状	対応
Script > 5000 ký tự	停止、ユーザーに意味的な分割を依頼
ElevenLabs API fail	エラーを報告、.env 内の ELEVENLABS_API_KEY（オプションで ELEVENLABS_VOICE_ID）を確認するよう提案。または tts_provider=minimax に切り替えてフェーズ1を再実行
MiniMax API fail	エラーを報告、.env 内の MINIMAX_API_KEY（オプションで MINIMAX_VOICE_ID）を確認するよう提案。または tts_provider=elevenlabs に切り替えてフェーズ1を再実行
MP3 > 300s sau Phase 1	パイプラインを停止、heygen-short-video（チャンキング）を提案
HeyGen MCP not connected	停止、claude mcp list で確認するよう通知
HeyGen render failed	エラーを表示、mcp__heygen__get_current_user でクレジットを確認するよう提案
Phase 3 sub-agent fail	エラートレースを読み取り、mkt-hyperframe-talking-head-video スキルを使用してフェーズ3を単独で再実行するようユーザーに提案
Scene writer returns malformed JSON	サブエージェントがそのシーンを自動的に再生成（オーケストレーターの関知外）
User reject MP3 voice	ボイス設定を調整してフェーズ1に戻る

エンドツーエンドの例

ユーザー:

スクリプトがあるから、フルパイプラインでTikTok動画にして。レッスン1とレッスン2用のBロール画像2枚も添付するよ。 Script: "今日はAnthropicから3つの教訓を共有します。最初の教訓はAlphabet ship betaです。2つ目の教訓は24時間…" B-roll: alphabet.png（教訓1）、clock.png（教訓2）

パイプライン:

1. Step 0 — スラッグ hom-nay-minh-chia-se。フォルダ workspace/content/2026-05-03/hom-nay-minh-chia-se/。script.txt を保存、Bロールをコピー。
2. Step 1 — text_to_mp3.py → voiceover.mp3（45秒、0.7MB）。
3. Step 2 — CHECKPOINT #1 — ユーザーにパスと再生時間を通知。返信を待つ。
4. ユーザー: OK。
5. Step 3 — アバターを選択（HEYGEN_AVATAR_LOOKS からランダム、例 66e75e22…）。MP3をアップロード → asset_id。ビデオを生成 → ポーリング → source.mp4 をダウンロード（45秒、7.5MB）。
6. Step 4 — mkt-full-video-phase3-packager サブエージェントを起動。
7. サブエージェントが文字起こし（35秒）、アウトラインを作成（3つの教訓 + まとめ + CTA）、アウトラインを表示 → CHECKPOINT #2。
8. ユーザー: OK。
9. サブエージェントが5つのシーンライターを並列実行（約8秒の壁時計 vs 約40秒の直列）。
10. サブエージェントがマージ → scenes.json → スキャフォールド + SFX + キャプションを並列で作成。
11. サブエージェントが index.html を生成し、lintを実行、プレビューを開く。
12. Step 5 — オーケストレーターがStudio URLを表示。ユーザーがプレビューを確認し、「レンダリングして」と言う。
13. オーケストレーターが npx hyperframes render を実行 → final.mp4 (1080×1920 30fps)。

すべてのステップで /tmp/feedback_full_video_pipeline.md を更新することを忘れないでください。