Bikash-Meher/antigravity

Skill de Criação de Guias em Vídeo

Transforme qualquer gravação de tela bruta em um guia de usuário polido, narrado e dinamicamente anotado (.mp4 + .srt).

Regras Principais (Sempre Seguir)

1. Zero JSON / Zero Preparação Manual do Usuário: O usuário fornece apenas o caminho da gravação (ex.: C:\recordings\demo.mp4 ou uma pasta de quadros) e notas opcionais de guia/fluxo. Você extrai quadros, analisa o vídeo inteiro, escreve o JSON da receita, valida o tempo e renderiza.
2. Analise TODOS os Quadros de 3 FPS Antes de Editar: Por exemplo, uma gravação de 210 segundos gera ~630 quadros a 3 fps. Extraia cada quadro de 3 fps via FFmpeg, escaneie todos os 630 quadros, inspecione cada Storyboard Contact Sheet gerada (storyboard_*.png) e inspecione os quadros de resolução total 0NNN_frame.png (ou use inspect_frame_slice) antes de escrever qualquer passo da receita.
3. Portão de Voz, Tom e Plano de Pré-Edição: Antes da renderização final, execute validate_recipe (--plan_only), apresente seu plano de edição (número de passos, duração, zonas de encaixe, narrações) e peça ao usuário para confirmar ou escolher Voz e Tom — a menos que o usuário tenha explicitamente ordenado "auto proceed" (ou "just render").
4. Configuração Automática na Primeira Execução: Se .venv estiver faltando após o clone, execute python bootstrap.py uma vez (ou execute tool_executor.py diretamente, que faz a configuração automática).

---

Fluxo de Trabalho do Agente Passo a Passo

Estágio 1 — Extrair Quadros de 3 FPS e Analisar Todos os Quadros

Execute create_guide (via MCP ou 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

Isso automaticamente:

1. Extrai quadros a 3 fps (0001_frame.png ... 0NNN_frame.png, ex.: 630 quadros para 210s) via FFmpeg incluso (engine.py --extract_frames --fps_extracted 3).
2. Escaneia 100% dos quadros extraídos (0 .. N-1) usando tanto difusão global quanto um detector de blocos espaciais 8×6 (para que dropdowns, cliques em botões, checkboxes e modais nunca sejam perdidos).
3. Emite:
   • storyboard_01.png, storyboard_02.png, ... — folhas de contato rotuladas cobrindo o vídeo inteiro com #frame, timestamp, tag de evento (PAGE_TRANSITION / UI_ACTION / IDLE_HOLD) e caixas ciano das regiões alteradas.
   • analysis_3fps.json — segmentos completos da linha do tempo + bounding boxes de pixels alterados [x1, y1, x2, y2] + trim_candidate para pausas ociosas.
   • recipe_draft.json — esquema de receita inicial do engine.py.

---

Estágio 2 — Inspecionar Visualmente Storyboards e Quadros Chave (Obrigatório)

1. Abra e leia cada imagem storyboard_*.png listada em storyboard_paths.
2. Trace a jornada completa do usuário do início ao fim: anote carregamentos de página, preenchimentos de formulários, popups/modais, longas pausas mortas (trim_candidate: true) e quaisquer cliques errados a serem cortados.
3. Abra imagens específicas de resolução total 0NNN_frame.png de frames_dir para os passos que você planeja destacar (e chame inspect_frame_slice se uma ação acontecer rapidamente dentro de um intervalo estreito de quadros) para que você possa:
   • Ler o texto exato de botões/campos/menus da interface.
   • Medir coordenadas precisas [x1, y1, x2, y2] para boxes, arrows, spotlight e zoom.

---

Estágio 3 — Escrever o recipe.json Final

Salve um recipe.json limpo de acordo com schemas/recipe.schema.json (veja exemplos reais em examples/recipe_create_exam.json):

• Campos obrigatórios de nível 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 defina "theme" como string — use "preset".)
• timeline_mapping: Mapeie segmentos de saída editados de forma limpa para os quadros-fonte de 3 FPS (start_sec, end_sec, source_frame_start_3fps, source_frame_end_3fps) — pule pausas chatas e acelere digitações repetitivas!
• steps: Entradas sincronizadas (id, start_time, active_start, active_end, step_num, step_title, narration, sub, boxes, arrows, opcionais spotlight / zoom).
  • Mantenha boxes[].label longe de cabeçalhos densos de tabela onde um pill poderia cobrir rótulos de colunas adjacentes.
  • Garanta que narration caiba confortavelmente na janela [active_start, active_end] de cada passo.

---

Estágio 4 — Validar Plano e Confirmar Voz/Tom

Execute a validação de pré-voo (sintetiza clipes Edge-TTS, verifica placeholders [AGENT:] e sobreposições, imprime zonas dinâmicas de encaixe):

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

Vozes: en-IN-NeerjaNeural (IN Feminina), en-IN-PrabhatNeural (IN Masculina), en-US-JennyNeural (US Feminina), en-US-GuyNeural (US Masculina), en-GB-SoniaNeural (UK Feminina), en-GB-RyanNeural (UK Masculina).
Tons: friendly, professional, energetic, calm, corporate.

• Se algum [AVISO DE SOBREPOSIÇÃO] aparecer ou has_overlaps for verdadeiro, expanda janelas de passos / corte a narração e revalide até que haja 0 sobreposições.
• A menos que o usuário tenha ordenado auto-prosseguir, compartilhe o breve Plano de Pré-Edição e confirme Voz e Tom antes de renderizar.

---

Estágio 5 — Renderizar e Verificar Visualmente a Saída

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

Inspecione 2 a 3 quadros renderizados via verificação de snapshot FFmpeg para confirmar que caixas, setas, pill de branding e dock HUD nunca colidem com o texto da interface, depois entregue os caminhos do .mp4 e .srt.