Bikash-Meher/video-guide-skill

Compétence de Création de Guide Vidéo

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

Règles Fondamentales (Toujours à Suivre)

1. Zéro JSON / Zéro Préparation Manuelle de la Part de l'Utilisateur : L'utilisateur fournit uniquement le chemin de l'enregistrement (ex. C:\enregistrements\demo.mp4 ou un dossier d'images) et des notes de flux optionnelles. Vous extrayez les images, analysez l'intégralité de la vidéo, écrivez le JSON de recette, validez les temps et effectuez le rendu.
2. Analyser TOUTES les Images à 3 ips Avant le Montage : Par exemple, un enregistrement de 210s produit ~630 images @ 3 ips. Extrayez chaque image à 3 ips via FFmpeg, analysez les 630 images, inspectez chaque Planche Contact Storyboard (storyboard_*.png) générée, et inspectez les images pleine résolution 0NNN_frame.png (ou utilisez inspect_frame_slice) avant d'écrire les étapes de la recette.
3. Porte Voix, Ton et Plan de 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 choisir la Voix et le Ton — sauf si l'utilisateur a explicitement ordonné "procéder automatiquement" (ou "rendu direct").
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 s'auto-configure).

---

Flux de Travail de l'Agent Étape par Étape

Étape 1 — Extraire les Images à 3 ips 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

Cela automatiquement :

1. Extrait les images 3 ips (0001_frame.png ... 0NNN_frame.png, ex. 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 (ainsi les listes déroulantes, les clics de boutons, les cases à cocher et les fenêtres modales ne sont jamais manqués).
3. Génère :
   • storyboard_01.png, storyboard_02.png, ... — des 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 boîtes de région modifiée en cyan.
   • analysis_3fps.json — segments de chronologie complets + boîtes englobantes des 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 page, les remplissages de formulaires, les popups/modales, les longues pauses mortes (trim_candidate: true) et les clics erronés à supprimer.
3. Ouvrez des images spécifiques en pleine résolution 0NNN_frame.png depuis 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 étroite d'images) afin de :
   • Lire le texte exact des boutons/champs/menus de l'interface.
   • Mesurer avec précision les coordonnées [x1, y1, x2, y2] pour les boîtes, flèches, projecteur et zoom.

---

Étape 3 — Rédiger la recipe.json Finale

Enregistrez une recipe.json propre correspondant au schemas/recipe.schema.json (voir des exemples réels 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 ips (start_sec, end_sec, source_frame_start_3fps, source_frame_end_3fps) — sautez les pauses ennuyeuses et accélérez les frappes répétitives !
• steps : Entrées synchronisées (id, start_time, active_start, active_end, step_num, step_title, narration, sub, boxes, arrows, spotlight / zoom optionnels).
  • Gardez boxes[].label éloigné des en-têtes de tableau denses où un pilule pourrait couvrir les étiquettes de colonne adjacentes.
  • Assurez-vous que narration tienne 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 pré-vol (synthétise les clips Edge-TTS, vérifie les espaces réservés [AGENT:] et les chevauchements, imprime les zones de dock dynamiques) :

python tool_executor.py --args '{"tool":"validate_recipe","recipe_path":"<CHEMIN_VERS_LE_FICHIER_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 que has_overlaps est vrai, élargissez les fenêtres d'étape / réduisez la narration et re-validez jusqu'à 0 chevauchement.
• Sauf si l'utilisateur a ordonné une procédure automatique, partagez le court Plan de Pré-Édition et confirmez la Voix et le Ton avant le rendu.

---

Étape 5 — Rendu et Vérification Visuelle de la Sortie

python tool_executor.py --args '{"tool":"render_guide","recipe_path":"<CHEMIN_VERS_LE_FICHIER_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, pilule de marque et le dock HUD n'entrent jamais en collision avec le texte de l'interface, puis fournissez les chemins des fichiers .mp4 et .srt.