Video Guide Maker Skill

Habilidad de Creador de Guías de Video

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

Reglas Principales (Seguir Siempre)

1. Cero JSON / Cero Preparación Manual del Usuario: El usuario solo proporciona la ruta de grabación (ej., C:\recordings\demo.mp4 o una carpeta de fotogramas) y notas opcionales de guía/flujo. Tú extraes fotogramas, analizas el video completo, escribes el JSON de la receta, validas la sincronización y renderizas.
2. Analiza TODOS los Fotogramas a 3 FPS Antes de Editar: Por ejemplo, una grabación de 210s produce ~630 fotogramas @ 3 fps. Extrae cada fotograma a 3 fps usando FFmpeg, escanea los 630 fotogramas, inspecciona cada Hoja de Contacto de Guión Gráfico generada (storyboard_*.png), e inspecciona los fotogramas en resolución completa 0NNN_frame.png (o usa inspect_frame_slice) antes de escribir cualquier paso de la receta.
3. Voz, Tono y Plan de Pre-Edición: Antes del renderizado final, ejecuta validate_recipe (--plan_only), presenta tu plan de edición (número de pasos, duración, zonas del dock, narraciones) y pide al usuario que confirme o elija Voz y Tono — a menos que el usuario haya ordenado explícitamente "proceder automáticamente" (o "solo renderiza").
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 se auto-inicializa).

---

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):

# Vía 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) usando FFmpeg incluido (engine.py --extract_frames --fps_extracted 3).
2. Escanea el 100% de los fotogramas extraídos (0 .. N-1) usando tanto diferencia global como un detector de bloques espaciales 8×6 (para que menús desplegables, clics en botones, casillas de verificación y modales nunca se pierdan).
3. Emite:
   • storyboard_01.png, storyboard_02.png, ... — hojas de contacto etiquetadas que cubren todo el video 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 + recuadros delimitadores de píxeles cambiados [x1, y1, x2, y2] + pausas inactivas trim_candidate.
   • recipe_draft.json — esquema de receta engine.py inicial.

---

Etapa 2 — Inspeccionar Visualmente Guiones Gráficos 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: anota cargas de página, rellenos de formularios, ventanas emergentes/modales, pausas muertas largas (trim_candidate: true) y cualquier clic incorrecto para recortar.
3. Abre imágenes específicas en resolución completa 0NNN_frame.png del directorio frames_dir para los pasos que planeas resaltar (y llama a inspect_frame_slice si una acción ocurre rápidamente dentro de un rango estrecho de fotogramas) para:
   • Leer el texto exacto de la interfaz (botones, campos, menús).
   • Medir coordenadas precisas [x1, y1, x2, y2] para boxes, arrows, spotlight y zoom.

---

Etapa 3 — Autoría de la recipe.json Final

Guarda una recipe.json limpia que coincida con schemas/recipe.schema.json (ver 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 una cadena — usa "preset".)
• timeline_mapping: Mapea los segmentos de salida editados limpiamente a los fotogramas fuente a 3 FPS (start_sec, end_sec, source_frame_start_3fps, source_frame_end_3fps) — ¡salta las 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, opcional spotlight / zoom).
  • Mantén boxes[].label alejado de encabezados de tabla densos donde una píldora podría cubrir etiquetas de columna adyacentes.
  • Asegúrate de que narration quepa cómodamente en la ventana [active_start, active_end] de cada paso.

---

Etapa 4 — Validar 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 dinámicas del dock):

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

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

• Si aparece alguna [ADVERTENCIA DE SUPERPOSICIÓN] o has_overlaps es verdadero, expande las ventanas de los pasos / recorta la narración y vuelve a validar hasta que haya 0 superposiciones.
• A menos que el usuario haya ordenado proceder automáticamente, comparte el breve Plan de Pre-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 instantánea de FFmpeg para confirmar que los cuadros, flechas, píldora de marca y dock HUD nunca choquen con el texto de la interfaz, luego entrega las rutas de .mp4 y .srt.