ビデオガイドメーカースキル
生の画面録画を、洗練されたナレーション付きで動的に注釈が施されたユーザーガイド動画（.mp4 + .srt）に変換します。
基本ルール（常に従うこと）
- ユーザーによるJSON / 手動準備は一切不要： ユーザーは録画パス（例：
C:\recordings\demo.mp4またはフレームフォルダ）と、オプションのガイド/フローノートだけを提供します。あなたがフレームを抽出し、動画全体を分析し、レシピJSONを作成し、タイミングを検証し、レンダリングします。 - 編集前に3FPSの全フレームを分析： 例として、210秒の録画では 3 fps で約630フレーム が生成されます。FFmpegで3fpsのフレームをすべて抽出し、630フレームすべてをスキャンし、生成されたすべてのストーリーボードコンタクトシート（
storyboard_*.png）を検査し、フル解像度の0NNN_frame.pngフレーム（またはinspect_frame_slice）を、レシピステップを作成する前に検査します。 - 音声、トーン、編集前計画のゲート： 最終レンダリングの前に、
validate_recipe（--plan_only）を実行し、編集計画（ステップ数、時間、ドックゾーン、ナレーション）を提示し、ユーザーに確認を求め、音声とトーンを選択してもらいます。ただし、ユーザーが明示的に「auto proceed」（または「just render」）を指示した場合は除きます。 - 初回実行時の自動セットアップ： クローン後に
.venvがない場合は、python bootstrap.pyを1回実行するか（またはtool_executor.pyを直接実行します。自動的にブートストラップされます）。
ステップバイステップのエージェントワークフロー
ステージ 1 — 3FPSフレームの抽出と全フレームの分析
create_guide を（MCPまたはCLI tool_executor.py 経由で）実行します：
# CLI / Codex / Cursor / Antigravity shell 経由：
echo '{"tool":"create_guide","video_path":"<VIDEO_PATH>","user_flow_notes":"<OPTIONAL_NOTES>"}' | python tool_executor.py
これにより自動的に：
- 同梱のFFmpeg（
engine.py --extract_frames --fps_extracted 3）を使用して3 fpsのフレーム（0001_frame.png ... 0NNN_frame.png、例：210秒で630フレーム）を抽出します。 - 抽出されたフレームの100％（
0 .. N-1） を、グローバル差分と8×6空間ブロック検出器の両方を使用してスキャンします（ドロップダウン、ボタンクリック、チェックボックス、モーダルを見逃しません）。 - 以下を出力します：
storyboard_01.png,storyboard_02.png, ... — 動画全体をカバーするラベル付きコンタクトシートで、#frame、タイムスタンプ、イベントタグ（PAGE_TRANSITION/UI_ACTION/IDLE_HOLD）、およびシアン色の変更領域ボックスを含みます。analysis_3fps.json— 完全なタイムラインセグメント + 変更ピクセルの境界ボックス[x1, y1, x2, y2]+trim_candidateアイドルホールド。recipe_draft.json— スターターengine.pyレシピスキーマ。
ステージ 2 — ストーリーボードとキーフレームの視覚的検査（必須）
storyboard_pathsにリストされているすべてのstoryboard_*.png画像を開いて読み取ります。- ユーザーの完全な操作過程を最初から最後まで追跡します：ページ読み込み、フォーム入力、ポップアップ/モーダル、長い不要な一時停止（
trim_candidate: true）、削除すべき誤クリックに注意します。 - ハイライトする予定のステップについて、特定のフル解像度
0NNN_frame.png画像をframes_dirから開き（アクションが狭いフレーム範囲で素早く発生する場合はinspect_frame_sliceを呼び出します）、次のことを行います：- 正確なUIボタン/フィールド/メニューのテキストを読み取ります。
boxes、arrows、spotlight、zoomのための正確な[x1, y1, x2, y2]座標を測定します。
ステージ 3 — 最終 recipe.json の作成
schemas/recipe.schema.json に一致するクリーンな recipe.json を保存します（実際の例は examples/recipe_create_exam.json を参照）：
- 必須のトップレベルフィールド：
source_video、frames_dir、fps_extracted: 3.0、input_source: "auto"、branding_text、preset（tech_hud|clean_light|minimal|high_contrast）、tone（friendly|professional|energetic|calm|corporate）、default_voice、dock_mode: "auto"、total_duration: "auto"、audio_timing_mode: "auto_shift"、export_subtitles: true。- （
"theme"に文字列を設定しないでください —"preset"を使用します。）
- （
timeline_mapping：編集された出力セグメントを3FPSソースフレームにきれいにマッピングします（start_sec、end_sec、source_frame_start_3fps、source_frame_end_3fps）。退屈な一時停止はスキップし、反復的な入力を高速化します。steps：同期されたエントリ（id、start_time、active_start、active_end、step_num、step_title、narration、sub、boxes、arrows、オプションでspotlight/zoom）。boxes[].labelを密度の高いテーブルヘッダーに配置しないようにします。ピルが隣接する列ラベルを覆う可能性があります。narrationが各ステップの[active_start, active_end]ウィンドウに快適に収まるようにします。
ステージ 4 — プランの検証と音声/トーンの確認
事前フライト検証を実行します（Edge-TTSクリップを合成し、[AGENT:] プレースホルダーと重複をチェックし、動的ドックゾーンを表示します）：
python tool_executor.py --args '{"tool":"validate_recipe","recipe_path":"<PATH_TO_RECIPE_JSON>"}'
音声： en-IN-NeerjaNeural（インド女性）、en-IN-PrabhatNeural（インド男性）、en-US-JennyNeural（米国女性）、en-US-GuyNeural（米国男性）、en-GB-SoniaNeural（英国女性）、en-GB-RyanNeural（英国男性）。
トーン： friendly、professional、energetic、calm、corporate。
[OVERLAP WARNING]が表示された場合、またはhas_overlapsが true の場合、ステップウィンドウを拡大するか、ナレーションをトリミングして、重複が0になるまで再検証します。- ユーザーが自動進行を指示しない限り、短い編集前計画を共有し、レンダリング前に音声とトーンを確認します。
ステージ 5 — レンダリングと出力の視覚的検証
python tool_executor.py --args '{"tool":"render_guide","recipe_path":"<PATH_TO_RECIPE_JSON>","output_path":"<OUTPUT_MP4>","export_srt":true}'
FFmpegスナップショットチェックを介してレンダリングされた2〜3フレームを検査し、ボックス、矢印、ブランディングピル、HUDドックがUIテキストと衝突しないことを確認した後、.mp4 と .srt のパスを提供します。