Bikash-Meher/antigravity

Compétence de création de guides vidéo

Transformez n'importe quel enregistrement d'écran en une vidéo de guide utilisateur soignée, commentée et dynamiquement annotée (.mp4 + .srt).

Règles essentielles (à suivre impérativement)

1. Zéro JSON / Zéro préparation manuelle de l'utilisateur : L'utilisateur fournit uniquement un chemin d'enregistrement (par exemple C:\enregistrements\demo.mp4 ou un dossier d'images) et des notes de guide/flow facultatives. Vous extrayez les images, analysez l'intégralité de la vidéo, écrivez le JSON de recette, validez le minutage et effectuez le rendu.
2. Analyser TOUTES les images à 3 FPS avant de monter : Par exemple, un enregistrement de 210s produit ~630 images @ 3 fps. Extrayez chaque image à 3 fps via FFmpeg, analysez la totalité des 630 images, inspectez chaque planche contact storyboard générée (storyboard_*.png) et inspectez les images en résolution complète 0NNN_frame.png (ou utilisez inspect_frame_slice) avant d'écrire une étape de recette.
3. Voix, Ton et Validation pré-édition : Avant le rendu final, exécutez validate_recipe (--plan_only), présentez votre plan d'édition (nombre d'étapes, durée, zones de dock, narrations) et demandez à l'utilisateur de confirmer ou de choisir Voix et Ton — sauf si l'utilisateur a explicitement ordonné "continuer automatiquement" (ou "rendre seulement").
4. Configuration automatique au premier lancement : Si .venv est manquant après le clonage, exécutez python bootstrap.py une fois (ou exécutez directement tool_executor.py, qui se configure automatiquement).

---

Workflow étape par étape de l'agent

Étape 1 — Extraire les images à 3 FPS et analyser toutes les images

Exécutez create_guide (via MCP ou CLI tool_executor.py) :

# Via CLI / Codex / Cursor / Shell Antigravity :
echo '{"tool":"create_guide","video_path":"<CHEMIN_VIDEO>","user_flow_notes":"<NOTES_OPTIONNELLES>"}' | python tool_executor.py

Ceci automatiquement :

1. Extrait les images à 3 fps (0001_frame.png ... 0NNN_frame.png, par exemple 630 images pour 210s) via FFmpeg intégré (engine.py --extract_frames --fps_extracted 3).
2. Analyse 100% des images extraites (0 .. N-1) en utilisant à la fois une différence globale et un détecteur de blocs spatiaux 8×6 (afin que les menus déroulants, clics de boutons, cases à cocher et modales ne soient jamais manqués).
3. Produit :
   • storyboard_01.png, storyboard_02.png, ... — planches contact étiquetées couvrant l'intégralité de la vidéo avec #image, horodatage, étiquette d'événement (PAGE_TRANSITION / UI_ACTION / IDLE_HOLD) et cadres de zones modifiées en cyan.
   • analysis_3fps.json — segments de timeline complets + boîtes englobantes de pixels modifiés [x1, y1, x2, y2] + trim_candidate pour les pauses inactives.
   • recipe_draft.json — schéma de recette engine.py de démarrage.

---

Étape 2 — Inspecter visuellement les storyboards et les images clés (obligatoire)

1. Ouvrez et lisez chaque image storyboard_*.png listée dans storyboard_paths.
2. Retracez le parcours complet de l'utilisateur du début à la fin : notez les chargements de pages, les remplissages de formulaires, les popups/modales, les longues pauses mortes (trim_candidate: true) et les éventuels clics erronés à supprimer.
3. Ouvrez les images spécifiques en résolution complète 0NNN_frame.png du dossier frames_dir pour les étapes que vous prévoyez de mettre en évidence (et appelez inspect_frame_slice si une action se produit rapidement dans une plage d'images étroite) afin de pouvoir :
   • Lire le texte exact des boutons/champs/menus de l'interface.
   • Mesurer avec précision les coordonnées [x1, y1, x2, y2] pour les boxes, arrows, spotlight et zoom.

---

Étape 3 — Rédiger le recipe.json final

Enregistrez un recipe.json propre correspondant à schemas/recipe.schema.json (voir des exemples concrets dans examples/recipe_create_exam.json) :

• Champs obligatoires de premier niveau : 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.
  • (Ne définissez jamais "theme" comme une chaîne — utilisez "preset".)
• timeline_mapping : Mappez proprement les segments de sortie édités aux images source à 3 FPS (start_sec, end_sec, source_frame_start_3fps, source_frame_end_3fps) — sautez les pauses ennuyeuses et accélérez la frappe répétitive !
• steps : Entrées synchronisées (id, start_time, active_start, active_end, step_num, step_title, narration, sub, boxes, arrows, éventuellement spotlight / zoom).
  • Gardez boxes[].label hors des en-têtes de tableaux denses où une pastille pourrait chevaucher les étiquettes de colonnes adjacentes.
  • Assurez-vous que la narration tient confortablement dans la fenêtre [active_start, active_end] de chaque étape.

---

Étape 4 — Valider le plan et confirmer la voix/le ton

Exécutez la validation de pré-vol (synthétise les clips Edge-TTS, vérifie les placeholders [AGENT:] et les chevauchements, imprime les zones de dock dynamiques) :

python tool_executor.py --args '{"tool":"validate_recipe","recipe_path":"<CHEMIN_VERS_RECIPE_JSON>"}'

Voix : en-IN-NeerjaNeural (IN Femme), en-IN-PrabhatNeural (IN Homme), en-US-JennyNeural (US Femme), en-US-GuyNeural (US Homme), en-GB-SoniaNeural (UK Femme), en-GB-RyanNeural (UK Homme).
Tons : friendly, professional, energetic, calm, corporate.

• Si un [AVERTISSEMENT DE CHEVAUCHEMENT] apparaît ou si has_overlaps est vrai, élargissez les fenêtres des étapes / réduisez la narration et revalidez jusqu'à ce qu'il n'y ait aucun chevauchement.
• Sauf si l'utilisateur a ordonné de continuer automatiquement, partagez le court plan de pré-édition et confirmez la voix et le ton avant le rendu.

---

Étape 5 — Rendre et vérifier visuellement le résultat

python tool_executor.py --args '{"tool":"render_guide","recipe_path":"<CHEMIN_VERS_RECIPE_JSON>","output_path":"<SORTIE_MP4>","export_srt":true}'

Inspectez 2 à 3 images rendues via une vérification instantanée FFmpeg pour confirmer que les boîtes, flèches, pastille de marque et dock HUD n'entrent jamais en collision avec le texte de l'interface, puis fournissez les chemins .mp4 et .srt.