Bikash-Meher/video-guide-skill

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

Transforme qualquer gravação de tela bruta em um vídeo de 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 os quadros, analisa o vídeo inteiro, escreve o JSON da receita, valida o tempo e renderiza.
2. Analisar TODOS os Quadros a 3 FPS Antes de Editar: Por exemplo, uma gravação de 210s gera ~630 quadros @ 3 fps. Extraia cada quadro a 3 fps via FFmpeg, escaneie todos os 630 quadros, inspecione cada Storyboard Contact Sheet gerada (storyboard_*.png) e inspecione os quadros em resolução total 0NNN_frame.png (ou use inspect_frame_slice) antes de escrever qualquer etapa da receita.
3. Portão de Voz, Tom e Plano Pré-edição: Antes da renderização final, execute validate_recipe (--plan_only), apresente seu plano de edição (contagem de etapas, duração, zonas do dock, narrações) e peça ao usuário para confirmar ou escolher Voz & Tom — a menos que o usuário tenha explicitamente ordenado "prosseguir automaticamente" (ou "apenas renderizar").
4. Configuração Automática na Primeira Execução: Se .venv estiver ausente após clonagem, execute python bootstrap.py uma vez (ou execute tool_executor.py diretamente, que faz o bootstrap automático).

---

Fluxo de Trabalho Passo a Passo do Agente

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

Execute create_guide (via MCP ou CLI tool_executor.py):

# Via CLI / Codex / Cursor / shell Antigravity:
echo '{"tool":"create_guide","video_path":"<VIDEO_PATH>","user_flow_notes":"<NOTAS_OPCIONAIS>"}' | 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 integrado (engine.py --extract_frames --fps_extracted 3).
2. Escaneia 100% dos quadros extraídos (0 .. N-1) usando tanto diff 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 + caixas delimitadoras de pixels alterados [x1, y1, x2, y2] + pausas ociosas candidatas a corte (trim_candidate).
   • recipe_draft.json — esquema inicial de receita 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: observe 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 em resolução total 0NNN_frame.png de frames_dir para as etapas que planeja destacar (e chame inspect_frame_slice se uma ação acontecer rapidamente dentro de um intervalo estreito de quadros) para:
   • 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 — Criar recipe.json Final

Salve um recipe.json limpo correspondente a 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 quadros fonte a 3 FPS (start_sec, end_sec, source_frame_start_3fps, source_frame_end_3fps) — pule pausas entediantes e acelere digitação repetitiva!
• steps: Entradas sincronizadas (id, start_time, active_start, active_end, step_num, step_title, narration, sub, boxes, arrows, opcional spotlight / zoom).
  • Mantenha boxes[].label longe de cabeçalhos densos de tabela onde uma pill poderia cobrir rótulos de colunas adjacentes.
  • Certifique-se de que narration se encaixa confortavelmente na janela [active_start, active_end] de cada etapa.

---

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

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

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

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

• Se algum [AVISO DE SOBREPOSIÇÃO] aparecer ou has_overlaps for true, expanda janelas de etapas / corte narração e revalide até 0 sobreposições.
• A menos que o usuário tenha ordenado prosseguimento automático, compartilhe o breve Plano 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":"<CAMINHO_DO_RECIPE_JSON>","output_path":"<ARQUIVO_MP4_DE_SAÍDA>","export_srt":true}'

Inspecione 2–3 quadros renderizados via verificação instantânea do FFmpeg para confirmar que caixas, setas, pill de marca e dock HUD nunca colidem com o texto da interface, então entregue os caminhos do .mp4 e .srt.