CK42BB/vox-explainer-skill

Pipeline de Vídeo Explicativo Estilo Vox

Produza um vídeo explicativo completo, narrado, legendado e com trilha sonora a partir de um único tópico. O pipeline é executado em seis estágios, cada um gerando artefatos que o próximo estágio consome. A narração é gerada ANTES da animação porque a duração da narração orienta todas as decisões de tempo.

TÓPICO → 1.Roteiro → 2.Narração → 3.Keyframes → 4.Animação → 5.Música → 6.Montagem
         (Claude)   (xAI TTS)    (Seedream)    (Omni Flash)  (MiniMax)  (ffmpeg)

Pré-requisitos

• Variável de ambiente ATLASCLOUD_API_KEY configurada (obtenha em atlascloud.ai — créditos gratuitos no cadastro)
• ffmpeg e ffprobe instalados (com libass para queima de legendas)
• Python 3.10+ com requests
• ~US$ 3–8 em créditos de API por filme de 60 segundos (veja tabela de custos em references/atlas-cloud-api.md)

Antes de fazer qualquer chamada de API, verifique os caminhos de endpoint e IDs de modelo atuais em https://www.atlascloud.ai/docs — as APIs de modelos de mídia evoluem rapidamente. Os padrões em references/atlas-cloud-api.md foram verificados em julho de 2026.

Estrutura do Projeto

Crie esta estrutura para cada filme e mantenha-a — cada estágio lê e escreve nela:

projeto/
├── brief.md            # tópico, abordagem, duração alvo, público
├── script.json         # beats com narração, descrições de cena, legendas
├── audio/
│   ├── vo/             # beat_01.mp3 ... beat_NN.mp3
│   ├── vo_durations.json
│   └── music.mp3
├── frames/             # keyframe_01.png ... style_anchor.png
├── clips/              # clip_01.mp4 ... (clipes animados silenciosos)
├── subs/               # captions.ass
└── final/              # film.mp4

Estágio 1 — Roteiro

Você escreve este estágio manualmente. Sem chamada de API. Este é o estágio que mais determina a qualidade — um grande roteiro com visuais medianos supera o oposto.

Leia references/vox-style-guide.md (seção Writing) antes de rascunhar. Regras fundamentais:

1. Estruture em beats. Um beat = um parágrafo de narração (1–3 frases, 8–14 segundos falados) + um visual. Um filme de 60 segundos tem 6–8 beats; 3 minutos tem 16–22 beats.
2. Arco narrativo Vox: gancho de abertura (um fato concreto surpreendente ou pergunta) → contexto ("para entender X, você precisa voltar a...") → explicação crescente com uma linha condutora clara → complicação ou reviravolta → resolução que reformula o gancho.
3. Voz: segunda pessoa de boas-vindas ("você provavelmente já viu..."), presente histórico, números concretos em vez de abstrações, frases declarativas curtas. Sem rodeios, sem "neste vídeo vamos".
4. Uma ideia por beat. Se uma frase introduz um segundo conceito, divida o beat.

Escreva script.json:

{
  "title": "Era de Ouro Tang",
  "topic": "Como a China da Dinastia Tang construiu a maior cidade do mundo",
  "style_seed": "colagem de papel mixed-media, montanhas chinesas em nanquim, paleta vermelho-escarlate e creme envelhecido",
  "accent_color": "#C0392B",
  "beats": [
    {
      "id": 1,
      "narration": "No século VII, a China Tang construiu Chang'an — a maior e mais rica cidade da Terra. O mundo inteiro veio aos seus portões.",
      "visual": "Imperador Taizong entronizado ao centro como recorte de papel, figuras da corte flanqueando, pagodes e montanhas em nanquim ao fundo, selo vermelho no canto superior direito lendo 盛唐",
      "caption_text": null,
      "motion": "zoom lento no imperador, nuvens se movendo para a esquerda, paralaxe sutil entre camadas de recortes"
    }
  ]
}

caption_text é para momentos de tipografia cinética na tela (uma estatística ou termo chave) — a maioria dos beats deixa como nulo; as legendas de narração são tratadas na montagem. motion se torna o prompt de animação no Estágio 4.

Estágio 2 — Narração (xAI TTS v1)

Gere um arquivo de áudio por beat e meça as durações. Essas durações são o relógio mestre para todo o filme.

Chame o endpoint de áudio do Atlas Cloud por beat (modelo: xAI TTS v1 — veja references/atlas-cloud-api.md para a forma exata da requisição e orientação sobre seleção de voz). Escolha UMA voz para todo o filme. Registro Vox: medido, caloroso, levemente irônico — evite vozes de "trailer de cinema".

Após a geração, examine cada arquivo e escreva audio/vo_durations.json:

ffprobe -v error -show_entries format=duration -of csv=p=0 audio/vo/beat_01.mp3

{"beats": [{"id": 1, "file": "audio/vo/beat_01.mp3", "duration": 9.83}], "total": 61.2}

Verifique se o comprimento total está de acordo com o brief. Se um beat estiver longo, aperte a narração e regenere apenas aquele beat.

Estágio 3 — Keyframes (Seedream 5.0 Pro)

Um keyframe por beat, todos em um estilo visual consistente. Consistência é o problema difícil; resolva-o com o padrão de âncora de estilo:

1. Gere a âncora. Use bytedance/seedream-v5.0-pro/text-to-image para o beat 1 (geralmente o quadro de título/gancho). Construa o prompt a partir do bloco de estilo em references/vox-style-guide.md (seção Visual Grammar) + o visual do beat + o style_seed e accent_color do filme. Solicite 16:9, 2K.
2. Revise a âncora antes de prosseguir. Regere até que o estilo esteja correto — todos os outros quadros o herdam.
3. Gere os quadros restantes com o modelo de edição. Use bytedance/seedream-v5.0-pro/edit com a âncora como imagem de referência (suporta até 10 referências; âncora + opcionalmente o quadro anterior). Prompt: "Mantenha exatamente o estilo de arte, paleta, tratamento de colagem de papel e moldura do quadro de referência. Nova cena: {beat.visual}"

Isso fixa paleta, textura e moldura em todo o filme, como um diretor de arte humano faria.

Todo prompt deve terminar com o sufixo de estilo (veja o guia de estilo), que codifica o visual Vox: recortes de papel com bordas brancas, pontos de meio-tom, faixas adesivas, acentos geométricos planos e ousados, margens generosas, cor de acento única.

Quadros com caption_text definido: instrua o Seedream a renderizar o texto em uma fonte condensada e em negrito, já que a renderização tipográfica do Seedream 5.0 Pro é forte. Mantenha abaixo de 5 palavras por quadro.

Estágio 4 — Animação (Gemini Omni Flash)

Anime cada keyframe em um clipe via imagem-para-vídeo. A duração alvo do clipe = duração da narração daquele beat + 0,5s de margem (arredonde para cima para os incrementos suportados pelo modelo).

Prompts de movimento para a estética de colagem devem ser SUTIS — este é o modo de falha mais comum. O visual Vox é "motion graphics", não "filmagem". Bom vocabulário de movimento:

• zoom lento / afastamento (câmera 2D, não dolly 3D)
• deslocamento de paralaxe entre camadas de recortes
• nuvens/fumaça se movendo lateralmente
• elementos de papel deslizando da borda do quadro e se fixando
• pontos de meio-tom ou textura brilhando suavemente
• um único elemento animado (bandeira ondulando, água ondulando) enquanto todo o resto permanece estático

Proíba explicitamente em todo prompt: "sem tremor de câmera, sem rotação 3D, sem morfismo de rostos ou texto, sem desvio de estilo, elementos permanecem como recortes de papel planos".

Consulte cada tarefa de geração até a conclusão e baixe para clips/clip_NN.mp4. As gerações às vezes falham ou desviam — revise cada clipe; regenere qualquer um onde o texto se deforme ou o estilo quebre. Preveja ~15% de regeneração.

Estágio 5 — Música (MiniMax Music 2.6)

Uma faixa instrumental para todo o filme. Solicite is_instrumental: true — vocais competem com a narração.

Fórmula do prompt: {humor} {textura de gênero adjacente}, {andamento}, {instrumentação}, {arco}. Exemplo para uma peça histórica: "fundo cinematográfico contemplativo, piano sentido e cordas suaves com pulsação de percussão leve, 90bpm, cresce gradualmente de esparso para completo, estilo documentário". Combine a instrumentação com o assunto (texturas de guzheng/dizi para a peça Tang; pulso de sintetizador analógico para um tópico de tecnologia).

O Music 2.6 gera músicas de comprimento fixo; se a faixa for mais curta que o filme, repita-a na montagem com um crossfade; se for mais longa, corte com fade-out. Nunca deixe o arco da música lutar contra o arco do filme — uma batida no meio da faixa caindo em um beat calmo é perturbadora, então avalie o resultado em relação à forma do filme.

Estágio 6 — Montagem (ffmpeg, local)

Leia references/ffmpeg-assembly.md para receitas completas. A sequência:

1. Conforme cada clipe à duração da narração de seu beat (corte ou segure o último quadro), normalize para 1920x1080 30fps.
2. Concatene os clipes em ordem.
3. Construa a trilha de narração concatenando o áudio dos beats com intervalos de 0,5s correspondentes ao tempo do vídeo.
4. Gere subs/captions.ass a partir do script — legendas queimadas estilo Vox: negrito sem serifa, branco com contorno preto pesado, centralizado na parte inferior, máximo de 2 linhas, divida a narração nos limites das cláusulas e cronometre cada bloco dentro da janela de seu beat.
5. Misture o áudio: narração em nível total, música reduzida em -12 a -15dB sob a narração (compressão sidechain ou automação de volume simples — receitas na referência).
6. Queime legendas + atribuição ("Feito com ..." pequeno no canto inferior direito, se desejado) e codifique: H.264, CRF 18, AAC 192k, -movflags +faststart.

Passo de QC final antes de entregar: verifique (a) desvio de sincronia legenda/narração, (b) música sobrepondo a narração, (c) um clipe cujo movimento aparece visivelmente em loop, (d) desvio de estilo entre quadros. Corrija no estágio onde o problema se originou, não com gambiarras de montagem.

Notas de Orquestração

• Execute os estágios estritamente em ordem na primeira vez; depois disso, qualquer estágio pode ser executado isoladamente porque todo o estado reside nos arquivos do projeto.
• A geração de API é lenta (clipes de vídeo: 1–4 min cada). Envie todas as tarefas de animação simultaneamente e depois consulte — não serialize.
• Mantenha todos os prompts enviados em um arquivo prompts.log — a reprodutibilidade é importante e os usuários vão querer ajustar e regenerar beats individuais.
• O custo escala linearmente com o número de beats. Informe ao usuário um custo aproximado antes do Estágio 3 (o primeiro estágio pesado em pagamento): beats × ($0.10 imagem + ~$1.20 por clipe de 10s) + ~$0.50 áudio.

Referências

• references/vox-style-guide.md — leia antes do Estágio 1 e do Estágio 3. A gramática visual, voz de escrita e modelos de prompt.
• references/atlas-cloud-api.md — leia antes do Estágio 2. Endpoints, IDs de modelo, padrão de tarefa assíncrona, código de consulta, custos.
• references/ffmpeg-assembly.md — leia antes do Estágio 6. Receitas de conformação, concatenação, legendas, redução e codificação.