Quando esta skill for ativada, inicie sempre sua primeira resposta com o emoji :pencil:.
Roteiro para Vídeos Programáticos
Roteiro para vídeos programáticos é a prática de planejar, estruturar e escrever roteiros que se traduzem diretamente em produção de vídeo orientada por código. Diferente da roteirização tradicional, os roteiros de vídeos programáticos são dados estruturados — cada cena tem duração explícita, contagem de quadros, descrição de animação e texto de narração que um motor de renderização pode consumir. Esta skill cobre entrevistar stakeholders, gerar roteiros YAML estruturados, calcular ritmo e contagem de quadros, escrever narração e revisar roteiros.
Quando usar esta skill
Ative esta skill quando o usuário:
- Quiser escrever um roteiro para um vídeo programático ou gerado por código
- Precisar planejar estrutura de cena, ritmo ou transições para um vídeo
- Perguntar sobre criação de storyboard em formato estruturado (YAML, JSON)
- Quiser calcular contagem de quadros a partir de duração e FPS
- Precisar de ajuda para escrever texto de narração para cenas de vídeo
- Perguntar sobre ritmo de vídeo para diferentes tipos de conteúdo (demo, explicativo, social)
- Quiser executar um fluxo de entrevista para coletar requisitos de vídeo
- Precisar revisar ou reestruturar um roteiro de vídeo existente
NÃO ative esta skill para:
- Filmagem com atores ou roteirização tradicional
- Tutoriais de software de edição de vídeo (Premiere, Final Cut, DaVinci Resolve)
- Conteúdo exclusivamente de áudio, como podcasts ou produção musical
- Design de imagens estáticas ou slides de apresentação
Princípios-chave
-
Orientado por entrevista — Realize uma entrevista estruturada (até 30 perguntas em 7 categorias) antes de gerar qualquer cena. Nunca roteirize baseado em suposições.
-
Saída estruturada — Cada roteiro é um YAML válido com um bloco
metae um arrayscenes. Cada cena possui camposid,duration,frames,narration,visual,animation,music,sfxetransition_to_next. -
Visual primeiro — Escreva o campo
visualantes danarration. A narração deve complementar os visuais, nunca descrever redundantemente o que está na tela. -
Consciência de ritmo — Combine o número de cenas e a duração por cena com o tipo de vídeo: clipes sociais precisam de cenas de 3 a 8 segundos; vídeos explicativos podem ter cenas de 5 a 12 segundos para dar mais espaço.
-
Sincronia narração-visual — Cada linha de narração deve corresponder ao que está visível naquele momento. Uma ideia por cena. O tempo da narração deve caber na duração da cena.
Conceitos principais
Estrutura de entrevista
Colete requisitos por meio de 7 categorias antes de escrever:
| Categoria | Perguntas | Exemplos |
|---|---|---|
| Produto/Assunto | 5-7 | Qual é o produto? Principais funcionalidades? Problema resolvido? Diferencial? |
| Público | 3-5 | Quem é o espectador-alvo? Nível técnico? Pontos de dor? |
| Objetivos do Vídeo | 3-4 | Tipo (demo/explicativo/social/anúncio)? Duração? Canal? |
| Tom e Estilo | 3-5 | Formal ou casual? Enérgico ou calmo? Vídeos de referência? |
| Ativos | 3-5 | Logotipo? Capturas de tela? Cores da marca? Fontes? |
| Conteúdo | 4-6 | Mensagens-chave? Funcionalidades obrigatórias? CTA? Gancho de abertura? |
| Preferências Visuais | 3-5 | Estilo de animação? Paleta de cores? Preferências de layout? |
Formato de roteiro YAML
meta:
title: "string - título descritivo"
duration: "string - duração total (ex.: 60s)"
type: "enum - demo | explainer | social | announcement"
resolution: "string - ex.: 3840x2160, 1920x1080"
fps: "number - 24, 30 ou 60"
audience: "string - quem está assistindo"
tone: "string - descritores separados por vírgula"
total_frames: "number - duração_segundos * fps"
scenes:
- id: "string - identificador único em kebab-case"
duration: "string - ex.: 4s, 8s"
frames: "number - duração_cena_segundos * fps"
narration: "string - máximo 15 palavras por frase"
visual: "string - o que o espectador vê na tela"
animation: "string - como os elementos se movem, com referências de quadro"
music:
track: "string - nome da faixa musical"
volume: "number - 0.0 a 1.0"
duck: "boolean - abaixar música durante a narração"
sfx:
- type: "string - nome do efeito sonoro"
at: "string - timestamp dentro da cena"
duration: "string - quanto tempo toca"
transition_to_next: "enum - hard-cut | cross-dissolve | fade-to-black | wipe-left | wipe-right | none"
Ritmo de cena por tipo de vídeo
| Tipo de Vídeo | Duração | Cenas | Por Cena | Observações |
|---|---|---|---|---|
| Demo de produto | 30-120s | 6-15 | 5-10s | Foco em funcionalidades, CTAs claros |
| Explicativo | 60-180s | 8-20 | 5-12s | Pesado em conceitos, mais espaço para respirar |
| Clipe social | 15-60s | 3-8 | 3-8s | Gancho nos primeiros 3s, ritmo acelerado |
| Anúncio | 15-45s | 3-6 | 4-8s | Impactante, foco em mensagem única |
Cálculo de quadros
total_frames = duração_segundos * fps
quadros_cena = duração_cena_segundos * fps
Exemplo: vídeo de 60s a 30fps = 1800 quadros no total
| Duração | 24 fps | 30 fps | 60 fps |
|---|---|---|---|
| 4s | 96 | 120 | 240 |
| 8s | 192 | 240 | 480 |
| 30s | 720 | 900 | 1800 |
| 60s | 1440 | 1800 | 3600 |
| 90s | 2160 | 2700 | 5400 |
Sempre valide se a soma dos quadros das cenas é igual a total_frames no meta.
Tarefas comuns
1. Executar o fluxo de entrevista
Percorra todas as 7 categorias em sequência. Faça uma pergunta de cada vez, resuma as respostas e prossiga. Consulte references/interview-questions.md para a estrutura completa de 30 perguntas. A versão compacta para prazos apertados usa 10 perguntas essenciais: nome do produto, principais funcionalidades, problema resolvido, espectador-alvo, nível técnico, tipo de vídeo, duração, canal, mensagem-chave e CTA.
2. Gerar um roteiro de demonstração de produto
meta:
title: "Demonstração do Produto - Painel Acme"
duration: "60s"
type: demo
resolution: 3840x2160
fps: 30
audience: "Fundadores de SaaS e gerentes de produto"
tone: "profissional, confiante, minimalista"
total_frames: 1800
scenes:
- id: introducao
duration: "4s"
frames: 120
narration: "Conheça a Acme - o painel que se constrói sozinho."
visual: "Logotipo centralizado em fundo off-white quente, aparece gradualmente"
animation: "aparecimento gradual em 30 quadros, mantém por 90 quadros"
music:
track: "upbeat-corporate"
volume: 0.4
duck: false
sfx: []
transition_to_next: "hard-cut"
- id: funcionalidade-1
duration: "8s"
frames: 240
narration: "Apenas descreva o que precisa. A Acme cuida do resto."
visual: "Mockup de navegador mostrando campo de entrada de comando, texto sendo digitado"
animation: "navegador desliza de baixo para cima em 20 quadros, digitação começa no quadro 40"
music:
track: "upbeat-corporate"
volume: 0.2
duck: true
sfx:
- type: "keyboard-typing"
at: "1.3s"
duration: "3s"
transition_to_next: "cross-dissolve"
- id: funcionalidade-2
duration: "8s"
frames: 240
narration: "Arraste, solte, redimensione. Seu layout, suas regras."
visual: "Editor de painel com widgets sendo reorganizados pelo cursor"
animation: "cursor move para widget no quadro 30, arrasta para nova posição em 60 quadros"
music:
track: "upbeat-corporate"
volume: 0.2
duck: true
sfx:
- type: "soft-click"
at: "1.0s"
duration: "0.2s"
transition_to_next: "cross-dissolve"
- id: cta
duration: "6s"
frames: 180
narration: "Teste a Acme gratuitamente em acme.dev. Crie seu primeiro painel em minutos."
visual: "Texto de CTA centralizado com URL, fundo gradiente animado sutil"
animation: "texto aparece gradualmente em 20 quadros, fundo gradiente muda lentamente"
music:
track: "upbeat-corporate"
volume: 0.4
duck: false
sfx: []
transition_to_next: "fade-to-black"
Roteiros de demonstração completos geralmente têm de 6 a 15 cenas. Expanda adicionando cenas de problema, prova social, preço e encerramento seguindo a mesma estrutura YAML.
3. Gerar um roteiro de clipe social
meta:
title: "Acme em 30 Segundos"
duration: "30s"
type: social
resolution: 1080x1920
fps: 30
audience: "Desenvolvedores navegando em feeds sociais"
tone: "enérgico, impactante, moderno"
total_frames: 900
scenes:
- id: gancho
duration: "3s"
frames: 90
narration: "Pare de construir painéis do zero."
visual: "Texto em negrito sobre fundo gradiente vibrante"
animation: "texto surge de cima em 8 quadros, tela treme por 4 quadros"
music:
track: "electronic-pulse"
volume: 0.5
duck: true
sfx:
- type: "impact-hit"
at: "0.2s"
duration: "0.3s"
transition_to_next: "hard-cut"
- id: demo
duration: "12s"
frames: 360
narration: "Digite o que precisa. A Acme constrói ao vivo."
visual: "Gravação de tela: digitando um comando, painel sendo gerado em tempo real"
animation: "digitação por 120 quadros, painel é construído nos 240 quadros restantes"
music:
track: "electronic-pulse"
volume: 0.3
duck: true
sfx:
- type: "keyboard-typing"
at: "0.5s"
duration: "4s"
transition_to_next: "hard-cut"
- id: resultado
duration: "8s"
frames: 240
narration: "Totalmente interativo. Dados em tempo real. Pronto para compartilhar."
visual: "Painel finalizado com interações de hover, dados atualizando ao vivo"
animation: "cursor passa por cima acionando tooltips, dados atualizam no quadro 120"
music:
track: "electronic-pulse"
volume: 0.3
duck: true
sfx: []
transition_to_next: "hard-cut"
- id: cta
duration: "7s"
frames: 210
narration: "Teste grátis em acme.dev."
visual: "Texto de CTA grande e centralizado, URL abaixo, fundo gradiente da marca"
animation: "texto escala de 0 ao tamanho total em 15 quadros, mantém"
music:
track: "electronic-pulse"
volume: 0.5
duck: false
sfx: []
transition_to_next: "none"
4. Calcular contagem de quadros a partir da duração
Entrada: duração = 60s, fps = 30
Saída: total_frames = 1800
Detalhamento das cenas:
introducao: 4s * 30 = 120 quadros
funcionalidade-1: 8s * 30 = 240 quadros
funcionalidade-2: 8s * 30 = 240 quadros
prova: 6s * 30 = 180 quadros
cta: 6s * 30 = 180 quadros
---
Soma: 32s = 960 quadros (restam 840 quadros, precisam de mais cenas)
Sempre verifique a soma. Se as cenas não totalizarem, ajuste ou adicione cenas.
5. Escrever texto de narração eficaz
Regras:
- Máximo de 15 palavras por frase — frases mais longas não podem ser lidas a tempo
- Voz ativa, presente — "A Acme constrói seu painel" em vez de "será construído"
- Combine narração com visuais — fale sobre o que está na tela
- Uma ideia por cena — não amontoe dois conceitos em uma única linha
- Lidere com o benefício — "Economize 10 horas por semana" em vez de "Nosso recurso de controle de tempo"
- Inclua pausas — narração vazia (
"") para dar espaço - Velocidade de leitura — aproximadamente 2.5 palavras por segundo
| Ruim | Bom | Por quê |
|---|---|---|
| "Nosso produto foi projetado para ajudar equipes a construir painéis mais rapidamente" | "Construa painéis em minutos, não em semanas." | Muito longo, passivo |
| "Clique no botão de mais no canto superior direito" | "Adicione um widget com um clique." | Deixe o visual mostrar a localização |
| "Como você pode ver, os dados atualizam em tempo real" | "Dados em tempo real. Sempre atualizados." | "Como você pode ver" é preenchimento |
6. Planejar transições de cena
| Transição | Quando usar |
|---|---|
hard-cut | Mesmo tópico, ritmo acelerado ou contraste brusco |
cross-dissolve | Mudança suave de tópico, conteúdo relacionado fluindo |
fade-to-black | Fim de seção, pausa dramática, cena final |
wipe-left / wipe-right | Comparações antes/depois, progressão temporal |
none | Cena final do vídeo |
Regra: use no máximo 2 tipos de transição diferentes por vídeo para consistência.
7. Revisar um roteiro com base em feedback
- Identifique o tipo de feedback: ritmo, narração, visuais, estrutura ou tom
- Localize as cenas afetadas pelo
idno YAML - Aplique alterações apenas nos campos afetados, preserve a matemática dos quadros
- Revalide: as durações das cenas ainda devem somar a duração total
- Recalcule os quadros se alguma duração mudou
- Documente o que mudou:
# Revisão: introdução encurtada de 6s para 4s conforme feedback (v2)
- id: introducao
duration: "4s" # era 6s
frames: 120 # era 180
Anti-padrões / erros comuns
| Erro | Por que está errado | O que fazer em vez disso |
|---|---|---|
| Escrever narração antes dos visuais | Leva o vídeo a um formato de cabeça falante | Escreva visual primeiro, depois narração para complementar |
| Cenas com mais de 12 segundos | Espectadores perdem atenção, ritmo parece lento | Divida em duas cenas mais curtas |
| Contagem de quadros incompatível | Motor de renderização produz tempo errado ou trava | Sempre calcule frames = duração * fps e verifique as somas |
| Narração com mais de 15 palavras/frase | Não pode ser lida dentro da duração da cena | Divida em frases mais curtas |
| Nenhum gancho nos primeiros 3 segundos | Espectadores de redes sociais passam, espectadores incorporados desengajam | Abra com declaração ousada, pergunta ou surpresa visual |
| Transições inconsistentes | Vídeo parece irregular e amador | Use no máximo 2 tipos de transição por vídeo |
| Pular a entrevista | Produz roteiros genéricos que não atingem o alvo | Sempre colete os requisitos primeiro |
| Descrições visuais vazias | Engenheiro de renderização não consegue construir a cena | Seja específico sobre layout, cores, movimento, elementos |
Armadilhas
-
Arredondamento de contagem de quadros — Quando a duração não divide uniformemente (ex.: 3,5s a 24fps = 84 quadros), arredonde para o inteiro mais próximo e ajuste a última cena. Nunca deixe quadros fracionários — motores de renderização truncam ou geram erro.
-
Estouro de tempo de narração — A 2,5 palavras/segundo, uma cena de 4s comporta cerca de 10 palavras. Escrever 20 palavras para uma cena de 4s significa narração apressada ou cortada. Sempre verifique a contagem de palavras em relação à duração da cena.
-
Resolução vertical vs horizontal — Clipes sociais (TikTok, Reels, Shorts) usam 1080x1920 (vertical). Incorporações no YouTube/sites usam 1920x1080 ou 3840x2160. Confirme o canal de distribuição antes de definir a resolução.
-
Conflitos de redução de volume musical — Se toda cena tiver
duck: true, o volume da música oscila constantemente. Use redução apenas quando houver narração. Cenas com narração vazia devem terduck: false. -
Desvio de duração total — Após revisão, as durações das cenas podem não somar mais a duração alvo. Recalcule
total_framese ajuste as cenas para corresponder. -
Referências de timestamp em animações — Ao referenciar quadros na animação (ex.: "começa no quadro 40"), certifique-se de que o número do quadro esteja dentro do intervalo
framesdaquela cena. Um quadro 120 em uma cena de 4s a 30fps (120 quadros) significa o último quadro — isso pode funcionar para uma animação que termina exatamente no final, mas certifique-se de que a duração da animação não ultrapasse os quadros da cena.
Referências
references/interview-questions.md— Estrutura completa de 30 perguntas para entrevistareferences/narration-examples.md— Exemplos de narração eficaz vs ineficaz