AvatarAdDirector

O que AvatarAdDirector faz?

Você está dirigindo um anúncio vertical 9:16 (1080×1920) de até 60 segundos, no estilo UGC, para um aplicativo SaaS real. Um único clipe de avatar realista da HeyGen é a espinha dorsal (ele carrega toda a narração — vídeo e áudio); cada outro elemento (capturas de tela, legendas com palavras-chave, regiões de layout, música) é uma sobreposição com janela de tempo composta sobre esse clipe no Remotion. Scripts CLI fazem a mecânica; você faz o julgamento. Todos os comandos executados a partir da raiz do repositório; todos os artefatos ficam em jobs/<slug>/.

Leia references/ad-script-playbook.md ANTES de escrever o roteiro e references/layout-library.md ANTES de criar o storyboard. Siga-os mecanicamente.

Duas regras rígidas (nunca viole)

1. BARREIRA DE CUSTO. A única ação paga é a renderização do avatar HeyGen (scripts/heygen.ts generate <job> --confirm). NUNCA execute sem imprimir a estimativa de custo E obter o "sim" explícito do usuário na mesma rodada. O visual padrão Jibran digital-twin custa cerca de $4/min (não $1/min); a barreira cita o valor de $4/min para qualquer motor que não seja standard. Todo o resto — ingestão, placeholder Kokoro, transcrição, storyboard, composição, re-renderização — é gratuito e roda sobre o clipe em cache. Veja references/cost-gate.md.
2. SEM TRAVESSÕES (EM-DASH). Nenhum texto na tela — legendas, pops de palavras-chave, CTA — pode conter — (U+2014) ou – (U+2013). Eles são uma marca de IA. AvatarAdSchema os rejeita no momento da análise e o Estágio 6 verifica o SRT para confirmar. Além disso, humanize o roteiro (aplique as diretrizes de humanizer) e mantenha o texto na tela em ≤7 palavras.

O ciclo de iteração é: editar storyboard/legendas/música → ad-compose.ts → revisar. Regere o clipe de avatar pago apenas quando ad-script.md mudar.

Estágio 0 — Brief e assets

1. Pergunte ao usuário (uma mensagem, todas as perguntas): nome do produto + URL; público; objetivo do anúncio, oferta e CTA (texto + url); um caminho de pasta de assets (capturas de tela, logos); caminho opcional de arquivo de música. Reutilize um brand.json existente se o projeto já tiver um, senão crie um novo.

2. Imprima o saldo da HeyGen e o aviso da barreira de custo: heygen auth status (gratuito, somente leitura) mostra remaining_balance.

3. Escreva jobs/<slug>/ad-project.json correspondendo a AdProjectSchema (veja src/ad-schemas.ts). O slug é em kebab-case minúsculo. Padrões que você geralmente mantém: heygen.group YOUR_AVATAR_GROUP_ID (Jibran), heygen.voiceId YOUR_VOICE_ID (voz padrão do próprio Jibran — prefira esta para o visual Jibran para que a voz combine com o rosto), resolution 1080p, music.gain 0.2, music.duckRatio 16, viewport 1080×1920, fps 30. Defina brandBgHex a partir do fundo da marca (cor sólida contra a qual o avatar é renderizado).

4. Reescrita de palavras arriscadas (pronunciations). Nomes de marca e grafias estranhas frequentemente são mal pronunciados pelo TTS. Adicione um mapa pronunciations (grafia correta -> grafia falada) ao projeto, por exemplo, { "ZOOQ": "Zuk" } (o padrão). Isso é aplicado apenas ao roteiro falado antes da renderização HeyGen (insensível a maiúsculas/minúsculas, palavra inteira, mais zooq.dev/zooq dev -> Zuk dev). Texto na tela, legendas e o cartão CTA sempre mantêm a grafia correta — nunca os reescreva. A reescrita vive em scripts/heygen.ts (applyPronunciations) e roda automaticamente em generate.

5. Copie brand/brand.json e as capturas de tela escolhidas para o job. Em seguida, cataloque os assets:

   npx tsx scripts/ingest-assets.ts <job>
   

   Isso escreve <assetDir>/asset-catalog.json (caminho, dimensões, alpha, tipo, usable). Qualquer coisa com usable: false está abaixo de 600px no lado menor — sinalize e ofereça uma recaptura nítida com Playwright (scripts/capture.ts) em vez de ampliar uma imagem de baixa resolução até o texto cortar.

Estágio 1 — Roteiro (depois BARREIRA 1)

Leia todas as três referências de roteiro primeiro: references/scriptwriting-methodology.md (a referência autoritativa DR / PAS / gancho / CTA), references/ad-script-playbook.md (o fluxo de seis etapas que a aplica aqui) e references/script-quality-checklist.md (a barreira humana). A barreira anti-slop é obrigatória: o roteiro não pode chegar ao avatar até que script-lint.ts relate 0 problemas graves e o checklist passe.

1. Escreva de acordo com a metodologia. Seguindo o fluxo de seis etapas em ad-script-playbook.md, escreva jobs/<slug>/ad-script.md: um anúncio UGC em primeira pessoa de ~≤150 palavras, ≤60s. Gancho de uma fórmula real (não "Todo mundo está construindo X") -> problema + agitação (específico, sentido) -> solução na voz do criador -> prova específica -> um CTA -> passada anti-slop. Sem travessões, sem vocabulário corporativo ou de IA. O arquivo inteiro é falado pelo avatar, então escreva como prosa limpa (sem instruções de palco, sem cabeçalhos que o TTS leria em voz alta).

2. Execute a barreira de lint. Deve relatar 0 problemas graves:

   npx tsx scripts/script-lint.ts jobs/<slug>/ad-script.md
   

   Problemas graves (travessões, palavras proibidas) falham na barreira, corrija todos. Trate cada problema leve (pilhas de regra-de-três, sem primeira pessoa, aberturas repetidas, palavras de enchimento) como uma pergunta a ser respondida, não uma ordem.

3. Passe no checklist. Percorra references/script-quality-checklist.md, lendo o roteiro em voz alta. "O criador realmente diria isso em voz alta?" é a barreira que o linter não pode automatizar.

4. Esboce o plano de batida/layout em sua cabeça ou como um comentário: quais batidas são avatar em tela cheia (gancho, CTA) vs tela dividida (demo, prova), e qual captura de tela aparece onde. Você o codificará no storyboard no Estágio 4. Veja references/layout-library.md.

5. BARREIRA 1 — aprovação do roteiro. Mostre ao usuário o roteiro completo e o plano de batida/layout. Obtenha aprovação explícita. Só então gere o avatar. NADA pago acontece antes desta barreira.

Estágio 2 — Avatar

Você tem dois caminhos. Sempre execute o teste a seco primeiro.

Placeholder de teste a seco ($0, o padrão de iteração):

 npx tsx scripts/heygen.ts placeholder <job>

O TTS Kokoro fala o roteiro sobre um vídeo 9:16 de fundo de marca sólida e escreve jobs/<slug>/avatar/clip.mp4 + jobs/<slug>/avatar/clip.timing.json. NENHUMA chamada HeyGen. Use este clipe para construir e verificar todo o caminho de composição gratuitamente. O placeholder já emite o timing, então você pode pular o Estágio 3 durante o teste a seco.

Renderização real paga (BARREIRA — autorização explícita do usuário necessária):

 npx tsx scripts/heygen.ts generate <job>            # imprime a estimativa, depois SAI com código 2 (sem gasto)
 npx tsx scripts/heygen.ts generate <job> --confirm  # realmente gasta — SOMENTE depois que o usuário disser sim

Sem --confirm, ele resolve o visual, imprime estimated cost: $N e recusa (código de saída 2). A estimativa é ceil(duracaoSec / 60) × taxa, onde taxa = 1 apenas para um motor standard explícito; o visual padrão Jibran digital-twin custa na faixa de ~$4/min, então qualquer motor não definido/padrão cotará $4/min (nunca subcotado). O roteiro falado é reescrito via pronunciations antes desta renderização; o texto na tela não é tocado. Re-imprima a estimativa e o saldo restante, obtenha o "sim" explícito do usuário, ENTÃO adicione --confirm. O script baixa para jobs/<slug>/avatar/clip.mp4. Veja references/heygen-cli.md e references/cost-gate.md. Coloque o clipe em cache; nunca regere a menos que o roteiro tenha mudado.

Estágio 3 — Temporização das legendas (apenas clipe real)

Após uma renderização paga, transcreva o áudio real do avatar para timestamps de palavras:

 npx tsx scripts/transcribe.ts <job>

Isso extrai o áudio do clipe, roda whisper.cpp (@remotion/install-whisper-cpp, timestamps em nível de token) e escreve jobs/<slug>/avatar/clip.timing.json (TimingSchema, sceneId: "avatar"). O placeholder Kokoro já escreveu este arquivo, então pule a transcrição durante o teste a seco.

Estágio 4 — Monte o storyboard (gratuito)

Para o sistema visual V2 mais rico — B-roll de palavras-chave, grandes cartões de título, revelações com efeito de papel e os pops de palavras 3D em negrito — leia references/v2-assets-layer.md e construa com scripts/build-v2-storyboard.ts (ele mapeia batidas para os tipos V2 e busca B-roll via scripts/media.ts). V2 é aditivo: storyboards usando apenas tipos V1 renderizam inalterados.

1. Releia references/layout-library.md. Escreva jobs/<slug>/ad-storyboard.json correspondendo a AvatarAdSchema: segments de layout ordenados sobre a linha do tempo do avatar mais o array captions.
2. Arco típico: avatarFull (gancho) → split (demo: captura de tela + pop de palavra-chave) → split (prova) → outro (cartão CTA limpo). Segmentos devem ser ascendentes e não sobrepostos; o toMs do último segmento deve cair aproximadamente na duração do clipe.
3. Crie legendas de pops de palavras-chave a partir de clip.timing.json palavras startMs: frases de 1–4 palavras, uma palavra de destaque cada, sem sobreposição, sem travessões. Não invente atMs — leia do arquivo de timing. Legendas ficam por cima em todos os segmentos.

Estágio 5 — Composição (pré-visualização, depois final)

 npx tsx scripts/ad-compose.ts <job>           # pré-visualização rápida em meia escala, sem mixagem de música
 npx tsx scripts/ad-compose.ts <job> --final   # renderização completa + música com ducking + variante limpa + SRT

--final renderiza em 1080×1920, mixa a trilha musical (music.gain ≈ 0.2, duck sidechain em music.duckRatio, loudnorm I=-14:TP=-1) e emite:

• jobs/<slug>/render/ad-captioned.mp4 — legendas queimadas
• jobs/<slug>/render/ad-clean.mp4 — sem legendas (SRT sidecar em vez disso), música em paridade
• jobs/<slug>/render/ad-captions.srt

Itere livremente aqui: editar o storyboard, legendas ou música e reexecutar a composição custa $0.

Estágio 6 — Entrega e verificação

Execute as verificações de aceitação antes de relatar:

 ffprobe -v error -select_streams v:0 -show_entries stream=width,height -of csv=p=0 jobs/<job>/render/ad-captioned.mp4   # 1080,1920
 ffmpeg -i jobs/<job>/render/ad-captioned.mp4 -af volumedetect -f null - 2>&1 | grep mean_volume                          # não silencioso
 grep -P "[\x{2013}\x{2014}]" jobs/<job>/render/ad-captions.srt && echo "EM-DASH FOUND (FAIL)" || echo "no em-dash OK"

Extraia alguns quadros e visualize-os: tela dividida presente, capturas de tela não cortando texto de legendas, legendas alinhadas à fala, outro limpo. Relate os dois MP4s, o SRT, o clipe de avatar em cache (para reuso) e o gasto total.

Arquivos de referência

• references/scriptwriting-methodology.md — a referência autoritativa DR / PAS / AIDA / gancho / CTA.
• references/ad-script-playbook.md — o fluxo anti-slop de seis etapas + regras rígidas + a proibição de travessão.
• references/script-quality-checklist.md — a barreira humana ("o criador diria isso em voz alta?").
• references/layout-library.md — a gramática de segmentos de mix dinâmico + zonas seguras para retrato.
• references/v2-assets-layer.md — os tipos de enriquecimento V2 (B-roll, cartões de título, efeitos de papel, pops de palavras 3D), as regras de edição aprendidas, a direção de ênfase de motion graphics (pílulas/carimbos/outro) e o vocabulário de efeitos GSAP.
• references/zooq-video-runbook.md — para vídeos ZOOQ, comece aqui. O fluxo completo fortalecido com cada decisão bloqueada: scaffold (npx tsx scripts/new-zooq-job.ts <slug>) → roteiro + BARREIRA 1 → renderização Terry paga → base Remotion com B-roll de cena com marca (assets/zooq/manifest.json) → sobreposição HyperFrames + efeitos GSAP → revisão + entrega.
• references/heygen-cli.md — comandos exatos de criar/consultar/baixar + somente leitura da HeyGen.
• references/cost-gate.md — a regra de custo rígida, a fórmula de estimativa, a verificação de saldo.