atharhive/vox-explainer

Pipeline de Vídeo Explicativo Estilo Vox

Produza um vídeo explicativo completo, narrado, legendado e musicado a partir de um único tópico. O pipeline é executado em seis estágios, cada um produzindo artefatos consumidos pelo próximo estágio. 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 definida (obtenha uma 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 (consulte a tabela de custos em references/atlas-cloud-api.md)

Antes de fazer qualquer chamada de API, verifique os caminhos atuais dos endpoints e os IDs dos modelos 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, ângulo, 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 sem áudio)
├── subs/               # captions.ass
└── final/              # film.mp4

Estágio 1 — Roteiro

Você mesmo escreve. Nenhuma chamada de API. Este é o estágio que mais determina a qualidade — um roteiro excelente com visuais medianos supera o contrário.

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

1. Estruture como 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 têm 16–22 beats.
2. Arco narrativo Vox: gancho de abertura fria (um fato surpreendente ou pergunta concreta) → contexto ("para entender X, é preciso voltar a...") → explicação crescente com uma linha clara → complicação ou reviravolta → resolução que recontextualiza o gancho.
3. Voz: segunda pessoa acolhedora ("você provavelmente já viu..."), tempo presente para narrativa histórica, 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 Dourada Tang",
  "topic": "Como a China da Dinastia Tang construiu a maior cidade do mundo",
  "style_seed": "colagem de papel mídia mista, montanhas chinesas em nanquim, paleta vermelha 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 vinha aos seus portões.",
      "visual": "Imperador Taizong entronizado no 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": "aproximação lenta no imperador, nuvens derivam para a esquerda, paralaxe sutil entre as camadas de recorte"
    }
  ]
}

caption_text é para momentos de tipografia cinética na tela (uma estatística ou termo-chave) — a maioria dos beats deixa 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 da Atlas Cloud por beat (modelo: xAI TTS v1 — veja references/atlas-cloud-api.md para a forma exata da requisição e orientação de seleção de voz). Escolha UMA voz para todo o filme. Registro Vox: medida, calorosa, levemente irônica — 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 a duração total em relação ao brief. Se um beat ficar 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. A 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 Gramática Visual) + 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 (até 10 refs suportadas; âncora + opcionalmente o quadro anterior). Prompt: "Mantenha exatamente o estilo artístico, paleta, tratamento de colagem de papel e moldura da referência. Nova cena: {beat.visual}"

Isso trava a 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 guia de estilo), que codifica o visual Vox: recortes de papel com bordas brancas, pontos de meio-tom, tiras de fita, acentos geométricos planos e ousados, margens generosas, cor de destaque única.

Quadros com caption_text definido: instrua o Seedream a renderizar o texto em um sans condensado e ousado, 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 através de imagem-para-vídeo. Duração alvo do clipe = duração da narração daquele beat + 0,5s de margem (arredonde para os incrementos suportados pelo modelo).

Os 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:

• aproximação / afastamento lento (câmera 2D, não travelling 3D)
• deriva de paralaxe entre camadas de recorte
• nuvens / fumaça derivando lateralmente
• elementos de papel deslizando da borda do quadro e se acomodando
• pontos de meio-tom ou textura brilhando suavemente
• um único elemento animando (bandeira ondulando, água ondulando) enquanto tudo o mais permanece estático

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

Acompanhe 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; regere qualquer um em que o texto se deforme ou o estilo quebre. Reserve ~15% para regeneração.

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

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

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

Music 2.6 gera músicas de duração fixa; se a faixa for mais curta que o filme, faça um loop na montagem com crossfade; se mais longa, corte com fade-out. Nunca deixe o arco da música competir com o arco do filme — uma queda no meio da faixa caindo em um beat tranquilo é chocante, então audite o resultado contra a 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 do seu beat (corte ou mantenha 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 roteiro — legendas estilo Vox: sans ousado, branco com contorno preto pesado, centralizado na parte inferior, máximo 2 linhas, divida a narração nos limites das cláusulas e temporize cada bloco dentro da janela do seu beat.
5. Mix de áudio: narração no nível máximo, música abaixada -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.

Controle de qualidade final antes de entregar: verifique (a) desvio de sincronia legenda/narração, (b) música sobrepujando a narração, (c) um clipe cujo movimento loops visivelmente, (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 reexecutado isoladamente porque todo estado reside nos arquivos do projeto.
• A geração por 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 × (US$ 0,10 imagem + ~US$ 1,20 por clipe de 10s) + ~US$ 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, legenda, ducking e codificação.