HyperFrames パイプライン — マルチテナントブランド説明ビデオ
URLを受け取り、完成したブランド説明/プロモーションMP4を生成するエンドツーエンドパイプラインです。ColdStart(coldstartb2b.com)上で構築および検証されています。最小限のテナントごとの設定で、あらゆるB2Bブランドにスケールできるよう設計されています。
呼び出しタイミング
- ユーザーが「Hyper Frames」/「hyperframes」とURLまたはブランド名を言った場合
- ユーザーが特定のビジネス向けの説明/プロモーションビデオを依頼した場合
- ユーザーが「<ブランド>のビデオを作って」などと言った場合
- ユーザーが「新しいURLで試してみよう」と言った場合
必要な環境変数($PIPELINE_ROOT/.env内 — .env.exampleをコピー)
KIE_AI_API_KEY=... # KIE.AI経由のNano Banana 2 + Seedance 2
HEYGEN_API_KEY=... # HeyGenアバター生成
ELEVENLABS_API_KEY=... # 11Labs音声+音楽
ELEVENLABS_VOICE_ID=... # デフォルトナレーター音声
HEYGEN_TALKING_PHOTO_ID=... # デフォルトアバタールック
プロジェクトレイアウト
$PIPELINE_ROOT/ # このリポジトリのルート
brands/
<brand>/ # ブランドごとのディレクトリ(brand-bookで作成)
brand.json
colors.md
typography.md
voice-tone.md
reference.png
template-16x9/ # アクティブなコンポジション(単一の作業ディレクトリ;ブランドごとにアセットを交換)
index.html
styles/
brand.css # ブランドインターフェース — ブランド固有のCSSのみを含むファイル
template.css # ブランド非依存のモーション
layouts.css # 10レイアウトシステム
assets/
voice.mp3 # 11Labs出力(パディング済み)
avatar.webm # HeyGen出力(クロマキー処理+パディング済み)
music.mp3 # 11Labs Music背景音楽
broll-*.png # Nano Banana B-roll
renders/
マルチテナント本番運用では、将来のステージ0でtemplate-16x9/をブランドごとにコピーする必要があります。現時点では、レンダリングごとにアセットをその場で交換します。
パイプラインステージ
ステージ1 — ブランド抽出
ターゲットURLに対してbrand-bookスキルを呼び出します。以下を生成します:
brands/<ブランド>/brand.json— パレット、タイポグラフィ、音声/トーンのサマリーbrands/<ブランド>/css-variables.json— ライブサイトのすべてのCSS変数brands/<ブランド>/reference.png— ホームページのスクリーンショット
下流のすべてのステージを駆動する2つの固定カラーを取得します:
bg:ブランドの背景色(通常はほぼ黒、例:#050508)accent:ブランドのシグナルカラー(通常は彩度の高い色相、例:#8b9cf7)
これらはB-rollプロンプトとstyles/brand.cssの置換変数になります。
ステージ2 — サイトを読み、ビジネスを理解する
WebFetchを使用して、ホームページおよび主要ページ(サービス、チーム、価格、概要)を読み取ります。以下を合成します:
- 彼らが何を販売しているか
- 誰に販売しているか(ICP)
- 最も際立った差別化要因1〜2つ
- 望ましいCTA(電話予約、トライアル開始など)
これがスクリプトの内容になります。
ステージ3 — スクリプト
要求された時間のスクリプトを作成します。ペーシングルール:1秒あたり約2.7ワードの音声(multilingual_v2ケイデンス)。したがって、22秒≈60ワード、45秒≈120ワード、60秒≈160ワードになります。
構成(22秒の5シーンテンプレート;より長い場合は比例して拡大):
- フック(時間の10〜15%)— パンチの効いた3〜6ワードのライン
- ボディ1 — 問題(約30%)— 何が壊れているか/ボトルネック
- ボディ2 — 統計または証拠(約15%)— 規模(B-rollにテンプレート2チャートを使用)
- ボディ3 — 私たちの働き方(約25%)— 差別化要因
- 終了/CTA(約15%)— 招待+ブランドワードマーク
より長いビデオ(45秒以上)の場合は、ボディ1とボディ2の間に追加のボディシーンを追加します(例:「ボディ1a — 特定のペインポイント」、「ボディ1b — 不作為のコスト」)。
11Labs eleven_multilingual_v2の韻律: 句読点がペーシングを駆動します(カンマ=マイクロポーズ、ピリオド=完全なポーズ、emダッシュ=ビート)。SSMLや感情タグは気にしないでください — multilingual_v2はそれらを尊重しません。自然な句読点で会話的な散文を書くだけです。
トレーサビリティのためにスクリプトをtemplate-16x9/script.txtに保存します。
ステージ4 — 音声(11Labs)
eleven_multilingual_v2で11Labs TTSを呼び出します。デフォルトの音声:.envの$ELEVENLABS_VOICE_ID(またはユーザーが指定/ブランドが好むもの — 不明な場合は質問してください)。
source .env && curl -s -X POST "https://api.elevenlabs.io/v1/text-to-speech/$ELEVENLABS_VOICE_ID" \
-H "xi-api-key: $ELEVENLABS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text":"<script>","model_id":"eleven_multilingual_v2"}' \
--output assets/voice_raw.mp3
FFmpegで音量を92%に後処理(パイプライン標準):
ffmpeg -y -i voice_raw.mp3 -af "volume=0.92" -c:a libmp3lame -b:a 192k voice.mp3
ステージ5 — アバター(HeyGen)
talking_photo_id(ルックID)を選択します。デフォルトは.envの$HEYGEN_TALKING_PHOTO_ID(HeyGenアカウントの任意のtalking-photoルック)から取得されます。
常にキャラクターレベルでuse_avatar_v_model: trueを設定してください。ルックがVに登録されていない場合、HeyGenは静かにAvatar IVにフォールバックします(登録されていないルックはIVにフォールバック。レンダリングには影響ありません)。
音声をアップロード→talking_photoレンダリングを送信→ポーリング→ダウンロード→クロマキー:
# オーディオをアップロード
AUDIO_ID=$(curl -s -X POST "https://upload.heygen.com/v1/asset" \
-H "X-Api-Key: $HEYGEN_API_KEY" -H "Content-Type: audio/mpeg" \
--data-binary @assets/voice.mp3 | python3 -c "import json,sys;print(json.load(sys.stdin)['data']['id'])")
# レンダリングを送信
VID=$(curl -s -X POST "https://api.heygen.com/v2/video/generate" \
-H "X-Api-Key: $HEYGEN_API_KEY" -H "Content-Type: application/json" \
--data-binary @- <<EOF | python3 -c "import json,sys;print(json.load(sys.stdin)['data']['video_id'])"
{
"video_inputs": [{
"character": {
"type": "talking_photo",
"talking_photo_id": "$HEYGEN_TALKING_PHOTO_ID",
"use_avatar_v_model": true
},
"voice": { "type": "audio", "audio_asset_id": "$AUDIO_ID" },
"background": { "type": "color", "value": "#00FF00" }
}],
"dimension": { "width": 720, "height": 1280 }
}
EOF
)
# 完了するまでポーリング(IVでは通常60〜90秒、新しいルックでの初回レンダリングではVで5〜20分)
# GET https://api.heygen.com/v1/video_status.get?video_id=$VID → data.status == "completed"
# その後、data.video_urlをassets/avatar_green.mp4にダウンロード
ステージ6 — クロマキー+対称パディング
HeyGenグリーンスクリーンMP4を透明なVP9 webmに変換し、両端に0.5秒のフリーズフレームパッドを追加します:
# クロマキー+デスピル→生の透明webm
ffmpeg -y -i avatar_green.mp4 \
-vf "chromakey=0x00FF00:0.10:0.05,despill=type=green:mix=0.6:expand=0" \
-c:v libvpx-vp9 -pix_fmt yuva420p -auto-alt-ref 0 -b:v 0 -crf 30 -an \
avatar.raw.webm
# 両端に0.5秒のフリーズフレームをパッド(アルファを保持)
ffmpeg -y -c:v libvpx-vp9 -i avatar.raw.webm \
-vf "tpad=start_duration=0.5:start_mode=clone:stop_duration=0.5:stop_mode=clone" \
-c:v libvpx-vp9 -pix_fmt yuva420p -auto-alt-ref 0 -b:v 0 -crf 30 -an \
avatar.webm
voice.mp3の両端に0.5秒の無音を対称的にパディングして、オーディオオフセットがアバターのタイミングと一致するようにします:
ffmpeg -y -f lavfi -i anullsrc=r=44100:cl=stereo -t 0.5 -c:a libmp3lame -b:a 192k silence.mp3
ffmpeg -y -f concat -safe 0 -i <(printf "file '%s/silence.mp3'\nfile '%s/voice_raw.mp3'\nfile '%s/silence.mp3'\n" "$PWD" "$PWD" "$PWD") \
-c:a libmp3lame -b:a 192k voice.mp3
これにより、タイミングルールが実現されます:アバター表示→音声開始→音声終了→アバターフェードアウト。(ルールは0.5秒リード+0.5秒テールで、すべてのGSAPシーンキューが+0.5秒シフトされ、最終フェードアウトは音声終了から0.1秒後に開始されます)。
ステージ7 — Object-positionキャリブレーション
フレーム内のアバターの顔の位置はソース写真に依存するため、ルックIDごとに再キャリブレーションします:
ffmpeg -y -ss 0.7 -i avatar.webm -vframes 1 avatar-frame-check.png
フレームを読み取り、顔の中心のy座標(1280ピクセルの高さで)を測定します。レイアウトごとにobject-positionを計算します:
object_position_y_pct = ( (face_y_px / 1280) * scaled_height_for_layout - layout_slot_height/2 ) / (scaled_height_for_layout - layout_slot_height) * 100
実際には:顔がフレームの上部3分の1(face_y ~380)にある場合 → タイトなスロットでは'50% 30%'、フルフレームスロットでは'50% 50%'を使用します。index.htmlのLAYOUT_AVATAR_SLOTSを更新します。決して推測しないでください — 常に抽出したフレームからキャリブレーションします。
ステージ8 — B-roll画像(KIE.AI経由のNano Banana 2)
2つの固定テンプレート。ブランドカラーはプロジェクトごとに交換されます(brand.jsonからBG_HEXとACCENT_HEXを置換)。
テンプレート1 — 純粋な抽象彫刻(雰囲気、ムード、ナラティブビート):
ソリッドな
[BG_HEX]の背景上の抽象的な3D彫刻的レンダリング。[FORM_DESCRIPTION]、[MOTION_INTENT]を示唆。[ACCENT_HEX]の光がフォルムを透過・周囲に屈折し、サブサーフェススキャッタリングを伴い、微妙に反射する暗い床に柔らかなコースティクスを落としている。ソフトな指向性スタジオ照明。ハイパーリアルなOctaneレンダリング。プレミアムテックキーノートの美学。中央のフォルムにシャープなフォーカス、端に向かって影に落ちる深度フォールオフ。テキスト、ロゴなし。
テンプレート2 — ガラスチャート(統計、比較、成長、比率、「X倍」、「Y%」に言及するライン):
ソリッドな
[BG_HEX]の背景上の抽象的な3Dデータ可視化。[CHART_TYPE]が完全に浮遊する半透明のガラスフォルムとしてレンダリングされ、[DATA_CONCEPT]を描写。ベースライン要素はマットなグレーのガラス。焦点要素は[ACCENT_HEX]のサブサーフェススキャッタリングと屈折で輝き、微妙に反射する暗い床に柔らかなコースティクスを落としている。細いオフホワイトの軸線。ソフトな指向性スタジオ照明。ハイパーリアルなOctaneレンダリング。プレミアムテックキーノートの美学。ミニマルなエディトリアル構成で、十分なネガティブスペース。テキスト、数字、ラベル、ロゴなし。
シーンごとの決定ルール:スクリプトラインが数字/統計/比較に言及している場合 → テンプレート2。それ以外 → テンプレート1。
送信パターン(デフォルトは1:1アスペクト、任意のアスペクト対応)。常にHTTPコード+本文をキャプチャして、4xxエラーを自己診断できるようにします:
source .env && RESPONSE=$(curl -sS -w "\nHTTP_CODE:%{http_code}" -X POST "https://api.kie.ai/api/v1/playground/createTask" \
-H "Authorization: Bearer $KIE_AI_API_KEY" -H "Content-Type: application/json" \
--data-binary @- <<EOF
{"model":"nano-banana-2","input":{"prompt":"<TEMPLATE WITH SLOTS FILLED>","output_format":"png","image_size":"1:1"}}
EOF
)
echo "$RESPONSE"
[[ "$RESPONSE" == *"HTTP_CODE:200"* ]] || { echo "KIE送信失敗 — 上記の本文を確認してください"; exit 1; }
https://api.kie.ai/api/v1/playground/recordInfo?taskId=<id> を4秒ごとにポーリングし、data.state == "success" になるまで待ち、data.resultJson(JSON文字列 — json.loads() で解析)を解析し、URLをダウンロードして assets/broll-N.png に保存します。
複数のB-roll生成を並行して実行します — KIE.AIは同時タスクを適切に処理します。
400エラーの一般的な原因:プロンプトセーフティフィルター。 Nano Banana 2は、法的/暴力/紛争に関連すると解釈されるプロンプト(例:「法廷」、「法的闘争」、「原告対被告」)を拒否します。常に2つの抽象テンプレートの範囲内に留めてください — 意味を幾何学/色でエンコードし、決してリテラルな主題ではエンコードしないでください。2026-04-28に検証済み:最小限の抽象プローブは同じ認証/スキーマで200を返すため、ここでの400はほぼ常にプロンプトの内容が原因です。
ステージ9 — 背景音楽(11Labs Music)
source .env && curl -s -X POST "https://api.elevenlabs.io/v1/music?output_format=mp3_44100_128" \
-H "xi-api-key: $ELEVENLABS_API_KEY" -H "Content-Type: application/json" \
-d '{
"prompt": "<MUSIC PROMPT>",
"music_length_ms": 22000,
"force_instrumental": true,
"model_id": "music_v1"
}' --output assets/music_raw.mp3
同期的にオーディオバイトを返します。music_length_ms はコンポジションの長さに一致します(範囲3000〜600000ms)。
B2Bアドバトリアル背景音楽のデフォルトプロンプト(2026-04-27に検証済み):
B2Bビジネスアドバトリアルのためのアップビートで楽観的なインストゥルメンタルアンダースコア。明るくモダンなピアノが、鋭いスタッカートノートで前進するリズミカルなパターンを奏で、微妙な高揚感のあるシンthパッドと組み合わさる。軽やかで優しいパルス — ソフトなシェイカーやミュートされたリズミカルなクリックが安定した前進の勢いを提供。大きなドラム、キック、クラッシュ、シンバルなし。ボーカルなし。自信に満ちた、元気な、エネルギッシュな、楽観的な感触。モダンでクリーン、テクノロジー志向、プロフェッショナルでコンテンポラリーなコーポレート。テンポ約115 BPM。明るいメジャーキー、晴れやかだが甘ったるくはない。全体を通して均一なダイナミクス — スウェル、ドロップ、クライマックス、フェードはなし — ただし安定したリズミカルな勢いは持続。モダンなSaaS製品ローンチビデオの背景音楽のようなサウンド。
プロンプトで避けるべきアンチパターン:
- 「シネマティック」/「ムーディー」/「アンビエント」→ 感傷的な引きずりを生み出し、アドバトリアルに不適
- テンポが90 BPM未満 → 眠すぎる
- スウェル、クライマックス、ダイナミクスの変化に言及 → 音声と競合する
- 「ボーカルなし」を忘れる → ElevenLabsがハミングを追加する可能性あり
-20dBにミックスし、短いフェードを追加して、音声の下に目立たないように配置します:
ffmpeg -y -i music_raw.mp3 \
-af "volume=-20dB,afade=t=in:st=0:d=0.4,afade=t=out:st=<end-0.6>:d=0.6" \
-c:a libmp3lame -b:a 192k music.mp3
ステージ10 — コンポジションアセンブリ
template-16x9/index.html が作業用コンポジションです。レンダリングごとに:
- ルート、音声、アバター、音楽要素の
data-durationをターゲット長に一致するように更新 styles/brand.cssのブランドカラーを更新(変数--bg、--accentなど)- ブランドが異なるフォントファミリーを使用している場合は、
brand.cssのフォントを更新 - GSAPタイムラインのシーン遷移をスクリプトビートに一致するように再調整
- 4つのタイミング要素(アバタービデオ、音声オーディオ、音楽オーディオ、ルートコンポジション)すべてに、
data-startとdata-durationが揃っていることを確認
オーディオトラックインデックス:avatar=1、voice=2、music=3。すべて class="clip"。すべて data-start="0"。
ステージ11 — レンダリング
cd "$PIPELINE_ROOT/template-16x9" && \
npx hyperframes lint && \
npx hyperframes render --output renders/<brand>-v<n>.mp4
重要:レンダリングはフォアグラウンドで実行してください。 バックグラウンドモードのレンダリングは、フレームキャプチャが開始された後、CPU 0%でハングします。timeout: 300000 を指定したフォアグラウンドのBash呼び出しを使用してください。レンダリングには22秒のコンポジションで約1〜2分、45秒で約3〜4分かかります。
レンダリングが完了したら、open -a "QuickTime Player" renders/<brand>-v<n>.mp4 で確認します。
イテレーションループ
ほとんどのレンダリングは1〜3回のパスが必要です:
- v1:適切なデフォルトでチェーン全体をエンドツーエンドで動作させる
- v2:明らかな問題を修正(顔のトリミング、音楽がうるさすぎる、遷移が…
…[翻訳のため切り詰められました]