use-screenkite-advanced-b-roll

use-screenkite-advanced-b-roll

目的

ScreenKite の録画の画面＋カメラの構成に、短いアニメーション付きの B ロール映像を重ねます。画面録画がメインコンテンツのままで、B ロールは短いアクセント（隅に表示する 4〜6 秒の PiP）として表示され、視聴者が読める時間を設けた後、magicMove で消えます。

パイプライン（7 フェーズ）

1. Locate mic audio in .skbundle
2. Transcribe with ElevenLabs Scribe  → word-level JSON
3. Pack to phrase view  + proofread via web search
4. Propose visual idea menu with density bundles
5. Scaffold N Hyperframes projects (one per visual slot)
6. Dispatch parallel sub-agents → each writes one index.html
7. Render each to MP4  →  apply setSceneLayout DSL with magicMove

前提条件（開始前に確認）

• ScreenKite.app が /Applications/ScreenKite.app にあること（macOS）。
• Node ≥ 22 と FFmpeg が PATH にあること。
• uv（推奨）— 高速な Python スクリプトランナーです。利用可能な場合は python3 より uv run を優先してください。PEP 723 のインラインメタデータを使用して依存関係を自動的に用意するため、手動で pip install する必要はありません。インストール方法：curl -LsSf https://astral.sh/uv/install.sh | sh。uv がインストールされていない場合は python3 にフォールバックします（transcribe_mic.py を実行するには、手動で pip install requests が必要です）。
• プロジェクトの .env に ELEVEN_LABS_API_KEY があること（注意：ELEVENLABS_API_KEY ではありません。このリポジトリではアンダースコア付きの形式を使用します）。キーがない場合、または .env が存在しない場合は、続行する前にユーザーにキーを提供するよう依頼してください。 失敗を黙って無視したり、文字起こしをスキップしたりしないでください。
• Hyperframes CLI — npx hyperframes 経由で実行します（初回使用時に自動インストールされます）。リポジトリ：https://github.com/heygen-com/hyperframes
• Hyperframes エージェントスキル（任意ですが、サブエージェントに役立ちます）：npx skills add heygen-com/hyperframes — hyperframes、hyperframes-cli、gsap スキルを登録します。
• video-use ヘルパー（scripts/transcribe_mic.py と scripts/pack_transcripts.py にバンドルされたコピーがあります。上流リポジトリ：https://github.com/browser-use/video-use）。

不足しているものがある場合は、続行する前にインストールするようユーザーに案内してください。references/external-tools.md を参照してください。

フェーズ 1 — マイク音声を特定する

ScreenKite の .skbundle はディレクトリです。マイク音声は <bundle>/media/microphone_*.m4a、画面映像は <bundle>/media/screen_*.mp4、カメラ映像は <bundle>/media/camera_*.mov、システム音声は <bundle>/media/system_audio_*.m4a にあります。

ScreenKite でプロジェクトが開いていることを確認してください（後続の CLI 呼び出しで現在のプロジェクトを使用できるようにするためです）。

'/Applications/ScreenKite.app/Contents/MacOS/ScreenKite' agent project open --path '<bundle path>' --json
'/Applications/ScreenKite.app/Contents/MacOS/ScreenKite' agent project current --json

フェーズ 2 — 文字起こし

ELEVEN_LABS_API_KEY をプロジェクトの .env から読み込み、ソースごとにキャッシュする ElevenLabs Scribe の薄いラッパーである scripts/transcribe_mic.py を使用します。PEP 723 のインラインメタデータで requests を自動インストールする uv run を優先してください。requests がすでにインストールされていれば、python3 も使用できます。

実行前に： プロジェクトの .env に ELEVEN_LABS_API_KEY があることを確認してください。ない場合は、停止してユーザーにキーを依頼してください。続行する前に、.env に ELEVEN_LABS_API_KEY=<key> として書き込んでください。

uv run scripts/transcribe_mic.py \
  '<bundle>/media/microphone_dji-mic-mini.m4a' \
  --edit-dir '.' \
  --language zho \
  --num-speakers 1

--edit-dir の既定値は現在のワークスペースディレクトリ（.）です。そのため、文字起こし、まとめたビュー、B ロールはすべてエージェントの作業ツリーと同じ場所に保存されます。代わりに --edit-dir '<bundle-parent>/<project-slug>-edit' を渡すと、出力を .skbundle の隣にまとめて保存できます。

出力：<edit-dir>/transcripts/microphone_*.json（単語レベル、話者分離済み、音声イベントを含む。3 分で約 155KB）。

キャッシュ済みの場合：出力が存在すれば、再アップロードをスキップします。

フェーズ 3 — まとめて校正する

3a. フレーズ単位のビューにまとめる

uv run scripts/pack_transcripts.py --edit-dir '<edit-dir>'

<edit-dir>/takes_packed.md を生成します。0.5 秒以上の無音区間でフレーズが区切られます。生の JSON より 10 倍コンパクトです。

3b. 校正 — 英語の製品名・固有名詞が含まれる場合は必須

ASR は、話者が言語を混ぜて話すと、固有名詞を誤認識することがよくあります。ある派生セッションでは、中国語の録音で「Claude」が一貫して「Cloud」と認識されていました。このような誤認識はすべて、生成される映像に引き継がれます。

ルール： Phase 4 の前に、パック済みトランスクリプトを確認し、製品名と思われる英単語がないか調べます。それぞれについて、WebSearch を使って次の点を確認してください。

• その綴りと完全に一致する実在の製品ですか？
• 文脈（公開日、機能、位置付け）と一致していますか？
• 正式な大文字・小文字の表記は何ですか？

修正した内容を <edit-dir>/takes_packed_proofread.md に書き込み、何を修正したか、なぜ修正したかを示す簡単な差分表を添えてください。

明らかに見えても、この手順を省略しないでください。 製品名を間違えた映像が 7 本あると、レンダリング時間が 15 分以上無駄になります。

Phase 4 — ビジュアル案メニューと密度

1. メニューを提案します。 references/visual-ideas-menu.md を読み、ビートに適したビジュアルの一覧を確認してください。ビートごと（イントロ／ツール名／たとえ／機能の強調／価格／アウトロなど）に整理してメニューを提案します。

2. 密度のセットを提示します。

密度	数	間隔	用途
少なめ	4	約 40 秒ごと	ドキュメンタリー調
中程度	7	約 24 秒ごと	デフォルト — バランス重視
多め	11–13	約 13 秒ごと	解説動画らしい勢い
超高密度	15+	フレーズ単位	ショート動画の視聴維持を最大化

ユーザーから別の指定がない限り、デフォルトは「中程度（7）」にします。Bロールは画面録画チュートリアルのアクセントであり、主役ではありません。

3. 確認を待ちます。 ユーザーがセットを承認するまで、スキャフォールドを作成しないでください。

Phase 5 — N 個の Hyperframes プロジェクトをスキャフォールドする

各スロットに Hyperframes プロジェクトを 1 つずつ作成し、すべて <video-project-root>/broll/slot_XX/ の下に配置します。

broll/
├── slot_01/
│   ├── hyperframes.json
│   ├── index.html          (written in Phase 6)
│   └── assets/              (logos, images referenced by index.html)
├── slot_02/ ... slot_NN/

uv run scripts/scaffold_slots.py <broll-dir> <count> を使って、hyperframes.json のスタブを含むディレクトリを作成します。スロットにロゴやアセットファイルが必要な場合（例：ScreenKite の自己紹介用）は、適切な slot_XX/assets/ フォルダーにコピーしてください。

Phase 6 — 並列サブエージェントで各 index.html を作成する

N 個のサブエージェントを1 つのメッセージで起動します（1 回の応答内で Agent ツールを呼び出すごとに並列実行されます）。各エージェントへの指示は、単独で完結している必要があります。テンプレートには references/subagent-brief-template.md を使ってください。以下のすべての必須ルールが含まれています。

すべての指示に含める必須ルール

完全な一覧は references/hyperframes-contract.md を参照してください。特に重要な点は次のとおりです。

1. コンテンツは 1920×1080 の MP4 フレーム全体に表示します。 MP4 自体が PiP です。ScreenKite が placeSelf="topRight" width="40%" で配置すると、フレーム全体が隅に表示されます。MP4 の隅の一部だけにコンテンツを配置しないでください（隅の中の隅に埋もれてしまいます）。暖色系のクリーム色で全面を覆う背景にし、コンテンツを中央に配置して画面いっぱいに表示します。

2. タイムラインの構成：登場 → 静止状態で表示 → 内部で退場させない。 退場は ScreenKite の magicMove が処理します。コンポジション自体に退場アニメーションがあると、視聴者には二重に退場するように見えます。次のように構成します。

   • 0.0 – 1.5s：登場アニメーション（ポップ、スライド、バウンス）
   • 1.5 – end：静止状態で表示。ビジュアルが完全に読み取れる状態で、環境に応じた動きは最小限にします。
   • 最後の 0.5 秒にフェードアウトや縮小を追加しないでください。

3. コンポジションの長さは、DSL のウィンドウの長さに読み取り用の静止時間を 1.5～2 秒加えた長さ以上にします。 登場アニメーションの完了後、視聴者が読む時間が必要です。DSL のウィンドウが 5 秒なら、登場後の静止時間は少なくとも 3.5 秒必要です。ビジュアルを一瞬で流さないでください。

4. タイムラインは同期実行とし、一時停止状態で window.__timelines["main"] に登録します。 async、setTimeout、Promise は使用しません。Math.random、Date.now、repeat: -1 も使用しません。繰り返し回数には有限の値のみを指定します：repeat: Math.ceil(holdLen / cycleLen) - 1。

5. 単独のコンポジションにします（<template> で囲みません）。 ルート div は <body> の直下に配置します。ひな形については references/dsl-cookbook.md を参照してください。

6. 完了を報告する前に lint を実行します。 各エージェントはスロットのディレクトリから npx hyperframes lint --json を実行し、エラーを修正して警告を報告します。

サブエージェントの起動

N 個の Agent ツール呼び出しをすべて run_in_background: true にして、1 つのメッセージで起動します。各プロンプトには次を指定します。

• 絶対出力パス：<broll>/slot_XX/index.html
• スロットの内容仕様（表示する内容、テキスト、アイコン）
• パレット（16 進数値。「色を選ぶ」は不可）
• フォントサイズ（大きめに指定 — 表示テキストは 160〜220px、本文は 48〜72px）
• 尺とタイムライン上のビート
• 該当する場合はアセットのパス（ロゴ、画像）
• 上記の厳守事項
• 「質問しないでください。不明な点がある場合は、最もわかりやすく温かみのあるかわいらしい解釈を選んでください。」

フェーズ 7 — レンダリングと DSL の適用

7a. 順番にレンダリングする

npx hyperframes render を実行するたびに Chrome が起動します。並列実行すると競合が発生します。順番に実行すれば問題ありません。30 秒のコンポジションは 30〜50 秒でレンダリングできます。

for i in $(seq -w 01 07); do
  ( cd broll/slot_$i && npx hyperframes render --output renders/slot_$i.mp4 --quality standard )
done

品質設定：レビューには standard、最終納品には high、高速な反復には draft を使用します。

7b. DSL ウィンドウを計画する（短い表示＋読み取り用ホールド）

N=7 の場合のデフォルト配置ローテーション：

• スロット 1：bottomLeft 40%（ローワーサード）、3.6 秒
• スロット 2、3、5、7：topRight 38〜45%、5〜5.5 秒
• スロット 4、6：topLeft 40〜42%、4.5〜6 秒

連続性を保つため、カメラはすべてのスロットで bottomRight 22% aspect=3:4 に固定します。

各スロットの表示ウィンドウは、コンポジション全体の尺ではなく、登場＋読み取り用ホールドにします。コンポジションが 12 秒（登場 1.5 秒＋長いホールド）の場合、5 秒の表示ウィンドウでは登場後 3.5 秒間ホールドが表示され、その後 magicMove が引き継ぎます。

7c. setSceneLayout を適用する

scripts/apply_broll_dsl.py を使用します。プラン JSON を読み込み、ScreenKite CLI 経由で各設定を適用した後、古い残り区間をクリアします。

uv run scripts/apply_broll_dsl.py <plan.json>

plan.json のスキーマと、そのままコピーできる DSL スニペットについては、references/dsl-cookbook.md を参照してください。

7d. 残り区間をクリアする際の注意点

setSceneLayout は既存のセグメントを分割します。置き換えるわけではありません。以前 22 秒の詳細セグメントを適用し、同じ開始位置に 5 秒のセグメントを再適用した場合、新しい 5 秒のセグメントに加えて、詳細モードのまま表示される 17 秒の残り区間が残ります。各残り区間の範囲に mode: "pictureInPicture" を指定して setSceneLayout を呼び出し、クリアする必要があります。

apply_broll_dsl.py がこれを自動で処理します。新しい B ロールウィンドウを適用した後、レイアウト状態を読み取り、意図したプランと一致しない advanced セグメントを見つけて、PiP に戻します。

7e. 確認する

'/Applications/ScreenKite.app/Contents/MacOS/ScreenKite' agent tool call \
  --name getProjectState --input-json '{"scope":"layout"}' --json

意図した範囲に advanced セグメントが正確に N 個あり、それ以外のすべての範囲が pictureInPicture であることを確認します。ScreenKite を開き、スクラブして目視で確認してください。

反復作業

ビジュアルに問題がある場合（内容、タイミング、配置）：

1. broll/slot_XX/index.html を編集します（または対象を絞ったサブエージェントで再生成します）
2. 再レンダリングします：cd broll/slot_XX && npx hyperframes render --output renders/slot_XX.mp4
3. plan.json を更新し、apply_broll_dsl.py を再実行します（べき等性があるため、残り区間は再度クリアされます）

ScreenKite DSL は絶対パスで MP4 を参照するため、タイミングを変えない反復作業ではファイルを置き換えるだけで十分です。

リファレンス（必要に応じて読み込む）

• references/external-tools.md — すべての前提条件のインストール方法／リポジトリ URL
• references/dsl-cookbook.md — 配置ごとの DSL スニペット＋plan.json スキーマ
• references/hyperframes-contract.md — コンポジション作成に関するすべての厳守事項
• references/visual-ideas-menu.md — ビートごとのアイデアカタログ＋密度バンドル
• references/subagent-brief-template.md — 並列エージェント向けの自己完結型ブリーフテンプレート

スクリプト（トークン効率化）

uv run の使用を推奨します（依存関係を自動で準備し、仮想環境は不要です）。利用できない場合は python3 にフォールバックします。requests が必要なのは transcribe_mic.py のみで、ほかのスクリプトは標準ライブラリのみを使用します。

• scripts/transcribe_mic.py — キャッシュ機能付きの ElevenLabs Scribe ラッパー。ELEVEN_LABS_API_KEY を使用
• scripts/pack_transcripts.py — 生の Scribe JSON からフレーズ単位でパッキング
• scripts/scaffold_slots.py — hyperframes.json のスタブを含む N 個のスロットディレクトリを作成
• scripts/apply_broll_dsl.py — プラン JSON から setSceneLayout を適用し、残り区間をクリア
• scripts/find_skbundle_mic.py — .skbundle 内のマイク音声を検索

アンチパターン

• 校正の手順を省略しないでください。 Scribeは中国語／ZH-TWの録音で英語の固有名詞を誤るため、「Claude」ではなく「Cloud」と表示されたビジュアルを生成する前に確認してください。
• MP4の隅にコンテンツを配置しないでください。 MP4全体が隅です。コンテンツはフレームいっぱいに表示します。
• コンポジションの退出アニメーションを、そのフレーム内で再生しないでください。 退出はmagicMoveが処理します。内部で退出させると、フェードが二重になります。
• テールをクリアせずにsetSceneLayoutを再適用しないでください。 ゾンビ化したBロールが元のウィンドウの全期間にわたって再生されることになります。
• 並列でレンダリングしないでください。 Chromeの競合が発生します。逐次処理でも十分速いです。
• キャッシュ済みのソースを再文字起こししないでください。 不変の入力からは不変の出力が得られます。Scribeは有料です。
• ユーザーが密度とバンドルの選択を確定する前に、レンダリングを開始しないでください。 やり直しにはコストがかかります。
• Hyperframesがすでにインストールされている場合は、ここでRemotionを使わないでください。このスキルではツールを1つに絞ってください。