動画ガイドメーカースキルは何をしますか？

生の画面録画を、磨き上げられたナレーション付き・動的アノテーション入りのユーザーガイド動画（.mp4 + .srt）に変換します。

基本ルール（常に従うこと）

ユーザーにJSONや手動準備を一切求めない： ユーザーは録画パス（例：C:\recordings\demo.mp4 またはフレームフォルダ）と、オプションのガイド・フローノートのみを提供します。あなたがフレームを抽出し、動画全体を分析し、レシピJSONを作成し、タイミングを検証し、レンダリングします。
編集前に全ての3FPSフレームを分析する： 例えば、210秒の録画の場合、@ 3 fps で約630フレームが生成されます。FFmpegですべての3fpsフレームを抽出し、生成されたすべてのストーリーボードコンタクトシート（storyboard_*.png）を走査し、フル解像度の0NNN_frame.pngフレームを検査してから（またはinspect_frame_sliceを使用して）、レシピステップを作成します。
音声、トーン、事前編集計画の確認： 最終レンダリングの前に、validate_recipe（--plan_only）を実行し、編集計画（ステップ数、時間、ドックゾーン、ナレーション）を提示し、ユーザーに確認または音声とトーンの選択を求めます。ただし、ユーザーが明示的に"自動続行"（または"そのままレンダリング"）を指示した場合は除きます。
初回自動セットアップ： クローン後に.venvがない場合は、python bootstrap.pyを1回実行するか（tool_executor.pyを直接実行しても自動ブートストラップされます）、実行します。

ステップバイステップのエージェントワークフロー

ステージ 1 — 3FPSフレームを抽出し、全フレームを分析

create_guideを実行します（MCP経由、またはCLI tool_executor.py経由）：

# CLI / Codex / Cursor / Antigravity シェル経由：
echo '{"tool":"create_guide","video_path":"<VIDEO_PATH>","user_flow_notes":"<OPTIONAL_NOTES>"}' | python tool_executor.py

これにより自動的に：

バンドルされたFFmpegを使用して3 fpsのフレーム（0001_frame.png ... 0NNN_frame.png、210秒で約630フレーム）を抽出します（engine.py --extract_frames --fps_extracted 3）。
抽出されたフレームの**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のパスを提供します。

動画ガイドメーカースキル