MikeFishbeinAtherial/infinite-headcount

Auto-Loom

Transforme qualquer aplicação web em um MP4 narrado e autodirigido. A página rola, destaca elementos e navega entre rotas enquanto uma voz de IA narra — sincronizada ao milissegundo. Sem gravação manual de tela, sem takes perdidos no Loom. Edite uma linha de narração e regrave em minutos.

Como funciona: A ElevenLabs gera um clipe de áudio para cada cena do storyboard. O ffprobe mede a duração exata de cada clipe. O Playwright controla o navegador exatamente por esse tempo por cena enquanto grava a janela. O ffmpeg gera o MP4 final com uma faixa de legendas. A duração do áudio é a verdade âncora — os visuais são escravizados a ela, então a sincronia é exata.

Esta pasta é o mecanismo completo. As habilidades irmãs são pontos de entrada simplificados sobre esses mesmos scripts:

• auto-loom-proof — Vídeo de prova da Software Factory: executa os critérios de aceitação de uma build em câmera, um critério por cena

Este SKILL.md cobre o mecanismo mais o modo desenvolvedor: você tem o código-fonte, o app roda em localhost, e você pode adicionar seletores estáveis no JSX.

---

Configuração (única, ~3 minutos)

cd <pasta-desta-skill>
bash scripts/setup.sh        # instala Playwright + Chromium, cria .env.local
# edite .env.local → adicione sua chave de API da ElevenLabs
node scripts/doctor.mjs      # verifica node, ffmpeg, playwright, chave, voz

Ainda não tem conta na ElevenLabs? Cadastre-se com o link de indicação do mantenedor: https://try.elevenlabs.io/atherial.

O doctor.mjs imprime a correção exata para qualquer item faltante. Requisitos: Node 18+, ffmpeg (brew install ffmpeg), uma chave de API da ElevenLabs. Opções de voz: references/voices.md.

Teste rápido (30 segundos, grava example.com):

node scripts/run.mjs --beats examples/smoke-beats.json

---

Passo 0 — Entreviste o usuário primeiro

Não comece a construir. Pergunte:

1. Qual URL ou aplicativo vamos gravar? Está rodando localmente?
2. Quem é o destinatário — nome e contexto?
3. Qual é a história? O que mudou, ou o que estamos mostrando pela primeira vez?
4. Quais funcionalidades, métricas ou seções específicas devemos destacar?
5. Qual é o tom? (atualização para cliente, demonstração interna, apresentação para prospect)
6. O aplicativo exige login? (veja references/auth.md — nunca peça senhas no chat)
7. Duração alvo — 30s, 60s ou 75s?

Com pressa: pergunte 1–3 e deduza o resto a partir do aplicativo.

Passo 1 — Escreva o storyboard (beats.json)

Escreva a narração antes de tocar em qualquer código e obtenha aprovação textual. Regras de roteiro e a estrutura de cena que funciona: references/tts-rules.md.

{
  "meta": {
    "title": "Walkthrough do painel Acme",
    "slug": "acme-walkthrough",
    "cta": "Envie seu feedback e seguimos para a próxima fase.",
    "targetLengthSec": 70
  },
  "baseUrl": "http://localhost:3000",
  "viewport": { "width": 1920, "height": 1080 },
  "beats": [
    {
      "id": 1,
      "page": "/dashboard/insights",
      "text": "Olá Jim. Enviamos algumas atualizações para seu rastreador de visibilidade de I-A.",
      "actions": [
        { "fn": "waitFor",    "sel": "[data-vn=kpi-row]" },
        { "fn": "scrollToEl", "sel": "[data-vn=kpi-row]", "opts": { "instant": true } },
        { "fn": "hl",         "sel": "[data-vn=kpi-row]" }
      ]
    }
  ]
}

Esquema completo: schema/beats.schema.json. Tabela de ações e orientações sobre seletores: references/actions.md. Opções de login (passos roteirizados ou sessão salva): references/auth.md.

Verifique antes de gastar qualquer crédito:

node scripts/validate.mjs --beats <arquivo>       # estrutura + TTS + lint de ritmo
node scripts/run.mjs --beats <arquivo> --script-only   # imprime a narração e para

O validador detecta ações desconhecidas, seletores ausentes, problemas de TTS (travessões, siglas soltas, frases longas) e ritmo que não cabe na duração alvo.

--script-only é o portão de revisão que economiza dinheiro: imprime a narração de cada cena com estimativas de tempo por cena e sai antes de qualquer chamada à ElevenLabs ou gravação. Obtenha a aprovação do roteiro aqui, depois execute novamente sem a flag para gastar créditos.

Passo 2 — Instrumente a página (modo desenvolvedor)

O Playwright precisa de seletores estáveis. Com acesso ao código-fonte, adicione atributos data-vn ao JSX do componente:

<div data-vn="kpi-row" className="grid grid-cols-4 gap-4">
<Card data-vn="competitor-chart" ...>

Depois referencie-os: { "fn": "hl", "sel": "[data-vn=kpi-row]" }.

Suprimir detalhamentos interativos durante a gravação. Cards clicáveis com role="button" / tabIndex={0} podem receber foco automático durante os destaques e abrir uma gaveta no meio do vídeo. Condicione-os à sua flag de modo de demonstração: {!isDemoMode() && <MetricBreakdownSheet ... />}.

Se o aplicativo exigir autenticação localmente, configure um modo de demonstração (pule a autenticação, dados de fixture que correspondam exatamente aos números da narração) ou use um caminho de autenticação de references/auth.md.

Nota sobre CSP: o gravador inicia o Chromium com bypassCSP: true para poder injetar presenter.js em páginas com CSP restrito. Se você apontá-lo para um app de produção com uma sessão ativa, saiba que a Política de Segurança de Conteúdo está desabilitada dentro daquele contexto do navegador automatizado.

Passo 3 — Um comando

node scripts/run.mjs --beats <arquivo>

Isso executa: validar → áudio (em cache pelo hash do texto) → pré-voo (passagem headless resolvendo cada seletor antes de qualquer gravação) → gravar → legendas → multiplexar → verificar. A saída vai para demo-video-out/<slug>/:

• <slug>-demo.mp4 — vídeo final (H.264/AAC, faixa de legenda suave)
• <slug>-demo-contact-sheet.png — quadros amostrados para inspeção visual
• qa/beat-NN.png — captura de tela exata no ponto de pausa de cada cena
• captions.srt, audio/, video/recording.webm

Todas as flags: --script-only (imprime o roteiro de narração e sai antes de qualquer chamada à ElevenLabs ou gravação — o portão de revisão do Passo 1), --preflight-only (verifica seletores, não gasta nada), --skip-audio (mudanças apenas visuais — o áudio é reutilizado), --skip-preflight (pula a verificação headless de seletores — somente quando o pré-voo acabou de passar e nada mudou), --burn-captions (grava legendas diretamente nos pixels para plataformas que removem faixas), --no-captions, --out <dir>, --env <arquivo-env>.

Passo 4 — Verifique antes de enviar

O run.mjs verifica a duração (MP4 = soma do áudio com margem de 0,5s), nível de áudio (detecção de faixa silenciosa) e gera capturas de tela de QA. Você ainda inspeciona:

• Folha de contato + qa/beat-NN.png: cada quadro mostra o que sua cena narra — sem páginas de login, estados de erro ou modais surpresa.
• Primeira cena nomeia o destinatário; última cena entrega o CTA textualmente.

Iterando

• Edição de narração → execute novamente; apenas o áudio da cena alterada é regenerado.
• Edição visual/ritmo → --skip-audio.
• Seletor quebrado → --preflight-only mostra exatamente qual cena e seletor.

---

Problemas conhecidos

• Hot reload elimina o apresentador injetado. Já tratado — o apresentador é reinjetado antes de cada cena. Mas evite editar o aplicativo enquanto grava.
• Deriva de porta. yarn dev pega 3001 se 3000 estiver ocupada — atualize baseUrl.
• Vozes gratuitas vs. pagas. Vozes clonadas/da biblioteca geram payment_required no plano gratuito. O doctor.mjs detecta isso antes do tempo de renderização.
• Redirecionamentos de i18n. Redirecionamentos /en/dashboard → /dashboard são seguidos corretamente; cenas na mesma página não re-navegam.
• Entrega. O MP4 é autossuficiente — e-mail, Slack, LinkedIn DM, incorporação no Notion ou importação para o Descript para uma introdução pessoal no início.