polyir/ai-video-production-skill

Produção de Vídeo com IA

Um sistema de produção que já entregou mais de 40 reels e episódios longos. Ele é opinativo: cada regra abaixo veio de uma falha real ou de uma decisão explícita do proprietário. Escolhas específicas do projeto (marca, logotipos, vozes, orçamentos) não estão aqui — cada novo projeto define as suas (consulte "Configuração por projeto").

Princípios fundamentais

1. Portão de aprovação antes de gastar. Roteiro + storyboard vão para o proprietário primeiro; nenhuma geração paga (TTS, imagens, vídeo, sincronização labial) até que ambos sejam aprovados. Pesquisa de imagens e listas de fontes são permitidas antes da aprovação. Qualquer alteração substancial de conteúdo após a aprovação é mostrada novamente. Cada upload público precisa de sua própria aprovação.
2. O proprietário decide as datas. Nunca proponha datas ou cronogramas de produção/publicação, a menos que o proprietário tenha definido uma cadência fixa. Mantenha um arquivo de calendário de conteúdo e atualize-o imediatamente após cada produção e cada publicação (status, data real, ID do post) — a tarefa não está concluída até que isso seja feito.
3. Motion design primeiro, IA depois. Antes de solicitar qualquer clipe de IA, pergunte: "isso pode ser construído em código?" Se algo pode ser mostrado (mapa, medidor, linha do tempo, lista de verificação, número, comparação, cartão de regra, alegoria), construa-o em Remotion/SVG com custo zero. IA apenas para o que deve ser visto (rostos, cenas históricas, pinturas, atmosfera). Cada vídeo — incluindo reels de 30 segundos — usa motion design construído em código. Rotule a camada de cada tomada do storyboard (código / IA / sincronização labial) e declare a participação do motion design.
4. Todo vídeo com IA começa a partir de uma imagem de referência aprovada (image-to-video, reference-to-video ou first-last-frame). Sem text-to-video.
5. Áudio sempre de uma ferramenta de áudio dedicada (ElevenLabs): narração, ganchos, música, SFX. Force o áudio dos modelos de vídeo a ser desligado (também costuma dobrar o preço).
6. Os limites de orçamento são aplicados por ferramentas, não pela memória. Use scripts/fal_jobs.py com um limite; ele se recusa a enviar se a estimativa exceder o limite ou se qualquer imagem custar ≥ $1.
7. Não consigo ouvir áudio nem julgar rostos com confiabilidade. Meça em vez disso: F0 para gênero da voz, LUFS para volume, STT para redação, stills/folhas de contato para visuais. Peça ao proprietário para ouvir nomes e palavras ambíguas.
8. Registre as decisões. Mantenha um DECISIONS.md (regras do proprietário + lições, datadas) e um PRODUCTION_WORKFLOW.md (regras atuais). Conhecimento/pesquisa vai em um arquivo separado com níveis de confiança; torna-se uma regra somente quando o proprietário aprova.

Ordem de produção

1. Revisar texto fonte e objetivo → 2. rascunhar roteiro + storyboard (marcar os shorts e seus ganchos agora; limitar reutilização de imagens a ~25%) → 3. extrair lista exata de ativos → 4. verificar ativos existentes, baixar apenas lacunas de fontes licenciadas → 5. verificar downloads (tópico, duração, resolução) → 6. finalizar roteiro/storyboard com base nos arquivos reais → 7. mostrar ao proprietário, parar até aprovação → 8. gerar (TTS → imagens de referência → I2V → sincronização labial) → 9. montar no Remotion + controle de qualidade técnico → 10. revisar corte para aprovação de publicação → 11. fazer upload após aprovação → 12. atualizar calendário + registro de análise.

Pipeline com script (detalhes em references/pipeline.md): turns.py → tts.py → stt_check.py → build_audio.py (→ timing.ts + legendas) → Remotion → scripts/master.sh (two-pass −14 LUFS + QC).

Divisão de ferramentas padrão (substituir por projeto)

Tarefa	Ferramenta	Notas
Imagens	Agentes gratuitos primeiro (Codex image_gen / Antigravity via MCP entre agentes) se disponíveis; senão fal (nano-banana-2 novo, nano-banana-pro/edit para consistência de estilo e i2i; Flux 2 Pro como fallback quando Nano Banana recusa)	alvo ≤ $0.30/imagem, nunca ≥ $1
Vídeo (I2V)	fal: Veo 3.1 (incl. lite/fast, first-last-frame para transições), Gemini Omni Flash 1.1, Wan 3.0, Kling 2.6 Pro	sempre definir resolução explicitamente — o preço depende dela
Sincronização labial	Hedra hedra-character-3 apenas	geralmente mais barato por segundo que I2V → contar a história através de um personagem quando possível
Voz, música, SFX	ElevenLabs, modelo TTS principal mais recente (list_models; nunca copiar um model_id antigo)	apenas vozes da biblioteca, nunca vozes projetadas
Limpeza de voz gravada	fal veed/clean-audio → fal-ai/lava-sr (denoise desligado) → polimento leve	aprimoramento, não geração
Edição / renderização	Remotion (+ @remotion/three para no máximo uma cena herói 3D)
Masterização / QC	ffmpeg	scripts/master.sh, scripts/qc.sh

Detalhes de modelos/preços e armadilhas: references/ai-generation.md.

Regras duramente conquistadas (aquelas que custaram dinheiro)

• Nunca crie uma nova voz TTS (text_to_voice). Vozes projetadas pronunciam mal o que não é inglês e o STT não consegue capturar erros de vogais. Selecione da biblioteca existente; se nada servir, pergunte.
• Combine personagem com voz antes de gerar um rosto para sincronização labial. Meça a F0 mediana (~85–155 Hz masculino, ~165–255 Hz feminino) e leia o texto. Um avatar masculino em uma voz feminina desperdiçou uma renderização inteira.
• Nunca presuma o gênero ou a identidade de uma pessoa na câmera nas imagens do proprietário — geralmente é o próprio proprietário.
• TTS em escrita persa/árabe precisa de diacríticos (especialmente ezafe kasra e palavras curtas ambíguas) apenas no texto do TTS; as legendas permanecem sem eles. Um diacrítico mal colocado é pior do que nenhum. Consulte references/audio.md.
• A música deve ser claramente audível: ~10–13 dB abaixo da fala com ducking, mais alta em pausas/capa/cartão final. Beds fixos com ganho 0.06 eram inaudíveis.
• fal_pricing retorna apenas o nível mais baixo (ex.: 360p). Orce a partir da tabela por resolução.
• Rostos fotorrealistas de pessoas reais não são reconstruídos. Use silhuetas/vistas traseiras/mãos, rotuladas como "reconstrução simbólica". Caricaturas cartoon óbvias de figuras públicas podem falar apenas citações documentadas, datadas e com fonte, rotuladas como tal.
• Nunca coloque texto legível em um prompt de modelo de imagem/vídeo — produz algo sem sentido; adicione texto no Remotion. Não coloque nomes de personagens nos prompts (o modelo os escreve na imagem); diga "simples, sem símbolos" para bandeiras/adereços.
• Observe o final de cada clipe de IA — o conteúdo geralmente quebra nos últimos segundos; encurte clipLen.

Regras para conteúdo curto (resumo — versão completa em references/short-form.md)

• O gancho funciona em 3 camadas simultaneamente em 0–3 s: quadro 0 visual, primeira linha falada (começa em 0,05 s, sem preâmbulo, promessa principal até o segundo 4), texto na tela legível sem som. ≤ 8 palavras. Escreva 2–3 ganchos de tipos diferentes por reel.
• Quadro 0 = a capa (fade de entrada reduzido a um quadro).
• Limite rígido do reel: 160 s, ponto ideal ~80–90 s; o Instagram só recomenda ≤ 3 min para não seguidores.
• Final: voz = peça para seguir com um motivo (melhor: um teaser nomeado da próxima parte); na tela = pergunta sobre o conteúdo; legenda = pergunta nos comentários + seguir. Convite para compartilhar ("envie para alguém que…") apenas em posts práticos.
• Nunca faça perguntas que revelem o grupo, identidade, localização ou atividades do espectador quando o público pode estar em risco.
• ≤ 5 hashtags; palavra-chave principal explicitamente na linha 1–2 da legenda (as legendas são indexadas na pesquisa).
• Alterne famílias visuais, tipos de gancho, narradores e templates de capa — reels consecutivos semelhantes são ignorados como "o post anterior".

Regras de análise (resumo — versão completa em references/analytics.md)

• Compare posts apenas na mesma idade (24 h / 48 h / 7 d) e dentro do mesmo status de colaboração; posts com < 24 h são "provisórios".
• Outliers (impulsionados por compartilhamento externo de uma conta grande, evento de notícias, etc.) são excluídos das linhas de base até que seu padrão seja reproduzido alterando parâmetros que você controla. Pergunte ao proprietário sobre compartilhamentos externos antes de creditar o conteúdo — a API não pode vê-los.
• Não alegue shadowban/restrição sem evidências do Status da Conta do aplicativo.
• O tempo de aceitação de colaboração é imprevisível; não atribua saltos de alcance a colaborações sem evidências.
• Julgue o sucesso pelo engajamento (compartilhamentos, salvamentos, comentários por alcance, seguidores por 1k de alcance), não apenas pelo alcance.
• Duas velocidades: registre dados sempre; proponha mudanças de regras apenas em uma revisão semanal e apenas se ≥ 3 posts da mesma idade mostrarem o padrão.

Configuração por projeto (perguntar ou ler no início de um novo projeto)

Paleta da marca, fontes e conjunto de logotipos · voz do narrador + vozes laterais rotativas · texto de divulgação de IA · limites de orçamento por reel/vídeo · modelos permitidos/proibidos · onde as chaves de API estão (nomes de serviço do Keychain / vars de ambiente) · contas de publicação e mapa de colaboradores · locais do calendário de conteúdo e arquivo de análise · restrições de segurança do público · se o proprietário pode aparecer na câmera.

Arquivos de referência

Arquivo	Leia quando
references/pipeline.md	construindo o pipeline com script TTS → timing → Remotion; layout de pastas; entregáveis
references/remotion.md	escrevendo ou depurando composições Remotion, fontes, texto RTL, 3D, QC de renderização
references/audio.md	configurações de TTS, diacríticos, cadeia de voz, ducking de música, volume, SFX
references/ai-generation.md	escolhendo/precificando modelos fal, regras I2V, Hedra Character-3, edição de vídeo Omni, matting, LUTs, agentes de imagem gratuitos
references/short-form.md	catálogo de ganchos, CTAs, loop shorts, sinais de classificação do Instagram, lacuna de curiosidade, princípios de explicador, enquadramento
references/analytics.md	executando uma análise do Instagram/YouTube, esquemas CSV, regras de comparação
scripts/fal_jobs.py	executor de jobs de imagem/vídeo fal com limite de orçamento (estimar / enviar / consultar / baixar)
scripts/stt_check.py	verificar turns de TTS contra o roteiro com ElevenLabs STT
scripts/master.sh	masterização de volume two-pass + QC de volume/preto/congelamento
scripts/qc.sh	grade de quadros + folha de contato + verificações técnicas antes da entrega