Bikash-Meher/antigravity

Habilidad de Creador de Videos Guía

Transforma cualquier grabación de pantalla en un video guía pulido, narrado y con anotaciones dinámicas (.mp4 + .srt).

Reglas Principales (Siempre Seguir)

1. Sin JSON / Sin Preparación Manual del Usuario: El usuario solo proporciona una ruta de grabación (ej., C:\grabaciones\demo.mp4 o una carpeta de fotogramas) y notas opcionales de guía/flujo. Tú extraes los fotogramas, analizas el video completo, escribes el JSON de la receta, validas la temporización y renderizas.
2. Analiza TODOS los Fotogramas a 3 FPS Antes de Editar: Por ejemplo, una grabación de 210s produce ~630 fotogramas a 3 fps. Extrae cada fotograma a 3 fps mediante FFmpeg, escanea los 630 fotogramas, inspecciona cada Hoja de Contacto del Storyboard generada (storyboard_*.png) e inspecciona los fotogramas de resolución completa 0NNN_frame.png (o usa inspect_frame_slice) antes de escribir cualquier paso de la receta.
3. Voz, Tono y Puerta de Plan Previo a la Edición: Antes del renderizado final, ejecuta validate_recipe (--plan_only), presenta tu plan de edición (número de pasos, duración, zonas dock, narraciones) y pide al usuario que confirme o elija Voz y Tono — a menos que el usuario haya ordenado explícitamente "auto proceed" (o "just render").
4. Configuración Automática en Primera Ejecución: Si falta .venv después de clonar, ejecuta python bootstrap.py una vez (o ejecuta tool_executor.py directamente, que arranca automáticamente).

---

Flujo de Trabajo del Agente Paso a Paso

Etapa 1 — Extraer Fotogramas a 3 FPS y Analizar Todos los Fotogramas

Ejecuta create_guide (a través de MCP o CLI tool_executor.py):

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

Esto automáticamente:

1. Extrae fotogramas a 3 fps (0001_frame.png ... 0NNN_frame.png, ej., 630 fotogramas para 210s) mediante FFmpeg empaquetado (engine.py --extract_frames --fps_extracted 3).
2. Escanea el 100% de los fotogramas extraídos (0 .. N-1) usando tanto una diferencia global como un detector de bloques espaciales 8×6 (para que nunca se pierdan menús desplegables, clics en botones, casillas de verificación y modales).
3. Emite:
   • storyboard_01.png, storyboard_02.png, ... — hojas de contacto etiquetadas que cubren el video completo con #frame, marca de tiempo, etiqueta de evento (PAGE_TRANSITION / UI_ACTION / IDLE_HOLD), y recuadros de región cambiada en cian.
   • analysis_3fps.json — segmentos completos de la línea de tiempo + cuadros delimitadores de píxeles cambiados [x1, y1, x2, y2] + trim_candidate de pausas inactivas.
   • recipe_draft.json — esquema inicial de receta para engine.py.

---

Etapa 2 — Inspeccionar Visualmente Storyboards y Fotogramas Clave (Obligatorio)

1. Abre y lee cada imagen storyboard_*.png listada en storyboard_paths.
2. Traza el recorrido completo del usuario de principio a fin: nota cargas de página, llenado de formularios, ventanas emergentes/modales, pausas muertas largas (trim_candidate: true), y cualquier clic erróneo que deba recortarse.
3. Abre imágenes específicas de resolución completa 0NNN_frame.png de frames_dir para los pasos que planeas resaltar (y llama a inspect_frame_slice si una acción ocurre rápidamente en un rango estrecho de fotogramas) para que puedas:
   • Leer el texto exacto de botones/campos/menús de la interfaz.
   • Medir coordenadas precisas [x1, y1, x2, y2] para boxes, arrows, spotlight y zoom.

---

Etapa 3 — Crear la recipe.json Final

Guarda una recipe.json limpia que coincida con schemas/recipe.schema.json (mira ejemplos reales en examples/recipe_create_exam.json):

• Campos obligatorios de nivel superior: 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.
  • (Nunca establezcas "theme" como cadena — usa "preset").
• timeline_mapping: Mapea segmentos de salida editados limpiamente a fotogramas fuente a 3 FPS (start_sec, end_sec, source_frame_start_3fps, source_frame_end_3fps) — ¡salta pausas aburridas y acelera la escritura repetitiva!
• steps: Entradas sincronizadas (id, start_time, active_start, active_end, step_num, step_title, narration, sub, boxes, arrows, opcionales spotlight / zoom).
  • Mantén las etiquetas de boxes[].label alejadas de encabezados de tabla densos donde una cápsula podría cubrir etiquetas de columna adyacentes.
  • Asegúrate de que la narration quepa cómodamente en la ventana [active_start, active_end] de cada paso.

---

Etapa 4 — Validar el Plan y Confirmar Voz/Tono

Ejecuta la validación previa al vuelo (sintetiza clips de Edge-TTS, verifica marcadores de posición [AGENT:] y superposiciones, imprime zonas dock dinámicas):

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

Voces: en-IN-NeerjaNeural (IN Female), en-IN-PrabhatNeural (IN Male), en-US-JennyNeural (US Female), en-US-GuyNeural (US Male), en-GB-SoniaNeural (UK Female), en-GB-RyanNeural (UK Male). Tonos: friendly, professional, energetic, calm, corporate.

• Si aparece [OVERLAP WARNING] o has_overlaps es true, expande las ventanas de paso / recorta la narración y vuelve a validar hasta que haya 0 superposiciones.
• A menos que el usuario haya ordenado auto-proceder, comparte el breve Plan Previo a la Edición y confirma Voz y Tono antes de renderizar.

---

Etapa 5 — Renderizar y Verificar Visualmente la Salida

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

Inspecciona 2–3 fotogramas renderizados mediante una verificación de instantánea con FFmpeg para confirmar que las cajas, flechas, cápsula de marca y el dock HUD nunca colisionen con el texto de la interfaz, luego entrega las rutas del .mp4 y .srt.