synctake

Habilidade SyncTake para Agentes de Codificação

Esta habilidade instrui agentes de codificação (Claude Code, Cursor, Antigravity, OpenCode, Codex) sobre como produzir de forma autônoma vídeos narrados e polidos de walkthroughs de aplicações web.

---

🎯 Quando Ativar Esta Habilidade

Ative este fluxo de trabalho sempre que o usuário solicitar:

• "Crie um vídeo de demonstração / walkthrough deste projeto / funcionalidade"
• "Grave um vídeo mostrando como o aplicativo funciona"
• "Faça um vídeo de walkthrough de 30s/60s desta nova interface"
• "Apresente esta funcionalidade em vídeo com narração"

---

🛠️ Passo 0: Verificação de Ambiente e Dependências

Antes de executar o fluxo de trabalho, verifique se as ferramentas necessárias estão instaladas:

1. Verificar CLI do SyncTake:

   synctake --help || pip install -e /path/to/synctake
   

2. Verificar Playwright (para captura headless autônoma):

   python -c "import playwright" 2>/dev/null || (pip install playwright && playwright install chromium)
   

---

📋 O Manual de 5 Etapas do Agente Autônomo

[1. Inspecionar UI] ──> [2. Criar synctake.json] ──> [3. Iniciar Servidor Dev] ──> [4. Executar Pipeline Autônomo] ──> [5. Entregar Vídeo]

Etapa 1: Inspecionar Código-Base e Marcos da Interface

1. Pesquise no espaço de trabalho por rotas, componentes e visualizações HTML (ex.: src/, pages/, app/, public/index.html).
2. Identifique os principais marcos visuais para o vídeo:
   • Cabeçalho, navegação, hero (#hero, header, .brand)
   • Componentes interativos, formulários, botões (#deploy-btn, button[type='submit'], select)
   • Cartões, métricas, gráficos ([data-testid='metrics'], .card, .recommendation-grid)
3. Como alternativa, execute o inspetor de interface integrado:

   synctake plan ./public/index.html --prompt "<orientação do usuário>" --duration <segundos>
   

---

Etapa 2: Criar a Especificação do Walkthrough (synctake.json)

Crie synctake.json na raiz do projeto.

Regras de Ritmo e Roteirização:

• Palavras por Minuto: Aponte para 140–150 PPM (~2,4 palavras por segundo). Uma cena de 10 segundos deve conter aproximadamente 20–24 palavras.
• Carimbos de Tempo da Cena (at): Devem ser estritamente crescentes.
• Callout na Tela: Mantenha title e callout curtos e impactantes (eles aparecem como cartões flutuantes nativos).
• Foco: Use seletores CSS reais e válidos (#id, .class, [data-testid='...']).
• Narração: Escreva uma conversa natural. Nunca leia símbolos de código, seletores ou carimbos de tempo em voz alta.

{
  "title": "Walkthrough de Funcionalidade",
  "duration_seconds": 30.0,
  "voice": {
    "provider": "system"
  },
  "scenes": [
    {
      "id": "01-visao-geral",
      "at": 0.0,
      "title": "Visão Geral do Cluster ao Vivo",
      "callout": "Métricas de saúde e telemetria em tempo real entre regiões",
      "focus": "#metrics-card",
      "text": "Bem-vindo! Neste walkthrough, exploraremos a saúde do cluster em tempo real e a correção automatizada."
    },
    {
      "id": "02-acoes",
      "at": 12.0,
      "title": "Implantações com Um Clique",
      "callout": "Validação automatizada com aprovação humana",
      "focus": "#deploy-btn",
      "text": "Com um único clique, nosso pipeline valida alterações de configuração e aplica atualizações contínuas."
    }
  ]
}

---

Etapa 3: Garantir que o Servidor de Desenvolvimento Esteja em Execução

Verifique se o servidor de desenvolvimento da aplicação web já está ouvindo em uma porta local:

lsof -i :3000 -i :5173 -i :8000 || true

Se não estiver em execução, inicie-o em segundo plano:

• Para HTML estático: python3 -m http.server 5173 --bind 127.0.0.1
• Para Vite: npm run dev
• Para Next.js: npm run dev

---

Etapa 4: Executar o Pipeline Autônomo

Execute o comando de execução autônoma tudo-em-um:

synctake run \
  --url http://127.0.0.1:5173 \
  --config ./synctake.json \
  --out ./demo.mp4

Se o usuário forneceu um clipe de referência de voz (ex.: voice.wav), passe --ref-audio ./voice.wav para clonar sua voz.

O que synctake run faz automaticamente:

1. Captura de Tela Headless: Inicia o Chromium via Playwright, percorre as dicas de cena, destaca elementos com anéis de foco adaptativos ao host, mostra badges de callout nativos e salva WebM calibrado.
2. Síntese de Fala: Sintetiza fala clara em português (ou clona a voz do usuário).
3. Validação de Ritmo e Slot: Verifica se nenhum clipe de áudio excede a duração alocada da cena.
4. Montagem da Tela Mestra: Coloca clipes nos momentos exatos, preenche pausas com silêncio digital e gera áudio estéreo calibrado de 48 kHz.
5. Multiplexação sem Perdas: Normaliza o áudio para o padrão de transmissão (-16 LUFS) e multiplexa em MP4 H.264 1080p com zero perda generacional de vídeo.

---

Etapa 5: Entregar o Vídeo Finalizado

Assim que synctake run for concluído:

1. Verifique se o vídeo de saída existe e não está vazio (ls -lh ./demo.mp4).
2. Apresente o vídeo finalizado ao usuário com o link do caminho absoluto do arquivo:

   "Aqui está o seu vídeo de walkthrough concluído: demo.mp4!"