Gerador de vídeos narrativos (Godot + FFmpeg), painel Next.js, serviço de voz, Clipador de lives e Publicador para YouTube, TikTok e Instagram. Inclui a leitura das visualizações dos posts para o Dashboard e o botão "Publicar no <rede>" nos cartões das publicações. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
CenaForge — prova de conceito de vídeo com Godot
Uma cena narrativa descrita por JSON é montada, animada pelo tempo de cena e renderizada offline pela Godot (Movie Maker → PNG), depois convertida em MP4 pelo FFmpeg e verificada pelo FFprobe. Nada de painel, API, banco ou publicação nesta fase.
"CenaForge" é nome de trabalho, sem aprovação nem verificação de marca/domínio.
A cena de teste tem 12 s a 30 FPS, em formato vertical. Um entregador de moto anda por uma rua de bairro fictício de aparência brasileira, com câmera em terceira pessoa. A moto freia e para, a câmera desce para um ângulo baixo e aparece a chamada "Uma entrega inesperada." com as opções A — Aceitar / B — Continuar a rota. É só visual: não há votação.
Evidências do teste (versões, tempos, verificações, inspeção visual): doc/TEST_RESULT.md. Especificação original: doc/PROMPT_TESTE_VIDEO_GODOT.md.
Painel (várias histórias, assets, votação e agentes)
pnpm panel abre o painel local em http://127.0.0.1:4500. Nele ficam várias histórias, cada
uma com episódios, assets próprios ou da biblioteca compartilhada, render com player, votação
A/B pelos comentários e envio de pedidos ao Claude Code ou ao Codex pela CLI. Detalhes em
panel/README.md.
Clipador (cortes de live)
Serviço clipper/ (127.0.0.1:4520) que assiste lives da Twitch, YouTube e Kick, lê o chat em tempo real, transcreve
com o Whisper do serviço de voz, pede a uma IA pela CLI (Codex/GPT por padrão, modelo escolhível) que confirme o
momento e gera cortes verticais 1080×1920 com legenda. Fila de aprovação na página Clipador do painel; contas
ligadas aos canais na página Contas. Publicação nas redes é a próxima etapa. Detalhes em
clipper/README.md.
Versões testadas
| Ferramenta | Versão | Observação |
|---|---|---|
| Godot | 4.7.2.stable.official (ed1daf0bf) | edição padrão (GDScript), sem .NET |
| Renderizador | Mobile (Vulkan) | ver "Decisões" |
| FFmpeg / FFprobe | 7.1.1 (build essentials gyan.dev) | encoder libx264 |
| Node.js | 24.19 | lançador; requer ≥ 20.10 |
| pnpm | 11.22 | dependências fixas em pnpm-lock.yaml |
| Sistema | Windows 11 Pro (10.0.26200) | caminhos e comandos também pensados para Linux, mas não testados em Linux |
Instalação
Atalho no Windows: setup.bat instala tudo (Node/pnpm, Python 3.12 isolado, serviço de voz, Whisper,
Applio com GPU NVIDIA se houver, Clipador com Streamlink) e roda o doctor. Depois, start.bat (ou pnpm dev)
sobe o painel (4500), o serviço de voz (4510), o Clipador (4520) e o Publicador (4530) juntos. Detalhes da voz em voice/README.md. A Godot e o FFmpeg
continuam como abaixo.
-
Godot 4.x (oficial). O lançador procura, nesta ordem:
- a variável
GODOT_BIN(caminho completo do executável); godotougodot4noPATH;- o executável oficial extraído em
.tools/godot-<versão>/dentro do projeto (ex.:.tools/godot-4.7.2/Godot_v4.7.2-stable_win64.exe). Essa pasta é ignorada pelo Git.
- a variável
-
FFmpeg e FFprobe no
PATH, ou emFFMPEG_BIN/FFPROBE_BIN. O build precisa de um encoder H.264:libx264(preferido),h264_nvencoulibopenh264. -
Dependências do lançador:
pnpm install pnpm run doctorO
pnpm-workspace.yamlrecusa o script de instalação doesbuild(allowBuilds: esbuild: false). Ele não é necessário: o binário vem do pacote opcional da plataforma.
Comandos
| Comando | O que faz |
|---|---|
pnpm dev |
Sobe o painel (127.0.0.1:4500), o serviço de voz (127.0.0.1:4510), o Clipador (127.0.0.1:4520) e o Publicador (127.0.0.1:4530) juntos; Ctrl+C encerra todos. pnpm voice sobe só a voz. |
pnpm test:clipper |
Testes do Clipador (pytest; sem rede, juiz falso). |
pnpm test:publisher |
Testes do Publicador (pytest; redes simuladas). pnpm --filter cenaforge-panel test:panel testa a fila de publicação do painel. |
pnpm test:voice |
Testes do serviço de voz (pytest). |
pnpm run doctor |
Checa Godot, FFmpeg, FFprobe, encoders, pasta de saída e espaço livre. Use pnpm run doctor: no pnpm 11, pnpm doctor executa o diagnóstico do próprio pnpm. |
pnpm preview |
Abre a cena padrão na Godot, em tempo real. Espaço pausa, R reinicia, ←/→ avança/recua um quadro (pausado), L liga/desliga a repetição, Esc fecha. Aceita -- --config <json>. |
pnpm render -- --config config/demo-street.json --profile preview |
Renderiza a prévia em 540×960. |
pnpm render -- --config config/demo-street.json --profile final |
Renderiza o perfil final em 1080×1920. |
pnpm verify -- --file <arquivo.mp4> |
Verifica codec, dimensões, FPS, quadros e duração. Lê as expectativas do scene.json da mesma pasta, ou de --width --height --fps --duration --frames. |
pnpm prepare-assets |
Regera as fachadas distantes em godot/assets/backgrounds/ (headless). |
pnpm test |
Testes do lançador (Node) e da lógica da cena (Godot headless). |
pnpm typecheck |
Checagem de tipos do lançador. |
Opções extras do render: --keep-frames (mantém os PNGs após o sucesso),
--debug-frame-index (desenha quadro/tempo na imagem), --warmup-frames N (padrão 3).
O que um render produz
Cada execução cria uma pasta nova em output/runs/<data-hora>-<id>-<perfil>/, nunca sobrescreve
as anteriores e é ignorada pelo Git:
scene.json configuração efetivamente usada (com a resolução do perfil)
render.log saída completa da Godot e do FFmpeg, com os comandos
godot-manifest.json resumo escrito pela cena (quadros, renderizador, GPU, digest)
report.json status, versões, tempos, verificações, avisos
<id>-<perfil>.mp4 o vídeo
inspect/t00.50s.png … quadros extraídos DO MP4 em 0,5 s, 4 s, 8 s e 11 s
inspect/contact-sheet.png os quatro lado a lado
output/last-success.json aponta para o último render que passou em todas as verificações.
Em falha ou cancelamento (Ctrl+C), a pasta recebe status: "failed" ou "cancelled", os PNGs são
preservados para diagnóstico e o último sucesso continua intacto. Só um render roda por
vez (output/.render.lock).
Reproduzir sem o lançador
Use caminho absoluto em --write-movie. Um caminho relativo é resolvido a partir de godot/,
não do diretório atual. Se a pasta não existir, a Godot 4.7.2 não grava nada e ainda sai
com código 0. A cena detecta esse caso e aborta com o código 3.
mkdir -p output/manual/frames
godot --path godot --write-movie "$PWD/output/manual/frames/frame.png" --fixed-fps 30 --disable-vsync \
-- --config config/demo-street.json
ffmpeg -framerate 30 -start_number 3 -i output/manual/frames/frame%08d.png -frames:v 360 \
-c:v libx264 -preset medium -crf 18 -pix_fmt yuv420p -r 30 -an -movflags +faststart \
output/manual/demo-street.mp4
(No Git Bash do Windows, use $(pwd -W) no lugar de $PWD.) Esse caminho manual só gera
540×960, a resolução base do projeto. Para 1080×1920, use o lançador (ver "Resolução do
filme").
Configuração de cena (schemaVersion: 1)
Exemplos: config/demo-street.json e config/demo-street-variant.json. A variante muda cor, caixa, distância, tempos, câmera, luz, largura da rua, casas e textos apenas no JSON.
| Campo | Regra |
|---|---|
schemaVersion |
precisa ser 1; outras versões são rejeitadas |
id |
[a-z0-9][a-z0-9_-]*, até 64 caracteres |
seed |
inteiro ≥ 0; controla cores, alturas, telhados e a distribuição do cenário |
video.width/height |
inteiros pares, 128–4096 (o perfil do lançador sobrescreve) |
video.fps, video.durationSeconds |
FPS inteiro 1–120; fps × duração precisa ser inteiro |
world.streetLengthMeters, roadWidthMeters |
40–1000 / 4–20 |
world.nearHousesPerSide |
casas 3D por lado (0–40), distribuídas ao longo da rua |
world.backgroundMode |
cards (morro com fachadas em planos) ou none |
world.lightingPreset |
warm_day ou golden_hour |
rider.assetId |
placeholder-rider (único, por enquanto) |
rider.bikeColor, rider.boxColor |
#RRGGBB (boxColor é opcional) |
rider.startPosition |
[x, y, z]; x dentro da pista |
rider.travelMeters |
distância exata até a parada; precisa terminar ≥ 15 m antes do fim da rua |
motion.startSeconds < brakeStartSeconds < stopSeconds ≤ durationSeconds |
partida, início da frenagem e parada; accelSeconds é opcional (padrão: min(1,5 s, metade do trecho livre)) |
camera.preset |
third_person_follow |
camera.offset, lookAtOffset |
posição e alvo relativos à moto, em metros, no espaço do mundo |
camera.fovDegrees |
FOV vertical, 20–100 |
camera.endOffset, endLookAtOffset |
opcionais: enquadramento para o qual a câmera migra |
camera.transitionStartSeconds/EndSeconds |
opcionais: padrão = início da frenagem → início do overlay + 0,6 s |
overlay.startSeconds, fadeSeconds |
quando o texto aparece; fade opcional (padrão 0,4 s) |
overlay.title, choiceA, choiceB |
texto puro (até 80/48/48 caracteres, sem caracteres de controle) |
audio.enabled, file, offsetSeconds |
áudio opcional fornecido pelo usuário (ver abaixo) |
Convenção desta cena: Y é altura, a moto anda em −Z e a câmera fica atrás, em +Z. Isso vale para esta cena, não para qualquer modelo importado: um GLB futuro entra por um nó adaptador que corrige escala e orientação.
Caminhos relativos (--config, audio.file) partem sempre da raiz do projeto, tanto na
Godot quanto no lançador, independentemente do diretório em que o comando foi chamado.
Campos desconhecidos são rejeitados. Nenhum valor é interpretado como código ou comando, e os subprocessos recebem os argumentos como lista, sem shell.
Áudio opcional
Com audio.enabled: true e audio.file apontando para um arquivo seu, o lançador:
confere se o arquivo existe; obtém a duração pelo FFprobe; atrasa o áudio por offsetSeconds;
preenche com silêncio; limita à duração da cena; e codifica em AAC 192 kbps / 48 kHz. Não
usa -shortest, então o vídeo nunca é truncado. Se o áudio passar do fim, o lançador avisa
que vai cortar e não altera a duração da cena. O arquivo de entrada não é modificado.
O render ainda não chama o serviço de voz: a narração por fala e a legenda automática são a próxima etapa.
Hoje o serviço gera os WAV (POST /v1/synthesize com format: "wav") e a transcrição com tempos, e o arquivo
entra aqui por audio.file. Sem áudio, o resultado é um vídeo silencioso válido.
Como funciona
config/*.json ──► lançador (scripts/) ──► scene.json da execução
│
├─ Godot --headless … --validate-only (validação, sem GPU)
├─ override.cfg temporário (resolução do perfil)
├─ Godot --write-movie frames/frame.png --fixed-fps 30 (janela + GPU)
│ └─ main.gd: monta rua/moto/câmera/overlay; quadro N = estado em t = N/30
├─ confere PNGs (contínuos, quantidade, dimensões, não vazios)
├─ FFmpeg: PNG (+ áudio) → MP4 H.264 yuv420p
├─ FFprobe: codec, dimensões, FPS, quadros decodificados, duração
└─ quadros de inspeção extraídos do MP4 + luminância (não preto)
- Tempo determinístico:
timeline_controller.gd → evaluate_at_time(t)calcula posição, rotação das rodas (ângulo = distância / raio), vibração, arfagem, câmera e overlay como função pura det. O perfil de velocidade usa rampas smoothstep (velocidade e aceleração contínuas) e chega exatamente emtravelMetersno instante de parada. Em render,t = quadro / fps. Odeltado motor não é usado: na 4.7.2 ele não sai exatamente 1/30, nem com--fixed-fps. Cada execução registra umstateDigestdos 360 estados, e a mesma configuração gera o mesmo digest (inclusive entre prévia e final). - Quadros de aquecimento: o primeiro quadro gravado pela Godot 4.7.2 sai com sombras e luz do
céu incompletas. A cena grava 3 quadros em
t = 0antes da cena, e o FFmpeg começa no índice 3 (-start_number 3). O vídeo final tem exatamente 360 quadros. - Resolução do filme: o Movie Maker fixa a resolução na inicialização, a partir do viewport do
projeto (
--resolutionnão muda isso). O projeto vem em 540×960. Para cada render, o lançador escreve umgodot/override.cfgcom o viewport do perfil e uma janela menor que cabe na tela, e o remove ao terminar. Se a resolução não bater com a configuração, a cena se recusa a renderizar (código 3).
Estrutura
| Caminho | Conteúdo |
|---|---|
godot/scripts/core/main.gd |
argumentos (--config, --validate-only, --manifest, --warmup-frames, --debug-frame-index), modos render/preview, manifesto |
godot/scripts/core/scene_config.gd |
leitura e validação do JSON |
godot/scripts/core/timeline_controller.gd |
perfil de movimento e evaluate_at_time |
godot/scripts/view/camera_controller.gd |
enquadramento por tempo |
godot/scripts/view/overlay_controller.gd |
chamada final e opções (CanvasLayer) |
godot/scripts/builders/street_builder.gd |
rua, calçadas, casas 3D, postes/fios, árvores, luz, morro com fachadas em planos |
godot/scripts/builders/rider_builder.gd |
moto e entregador com primitivas |
godot/scripts/builders/facade_painter.gd |
texturas procedurais (fachadas, asfalto, calçada) |
godot/tools/generate_backgrounds.gd |
preparação: gera assets/backgrounds/*.png |
godot/tests/ |
testes headless e configurações inválidas de exemplo |
godot/assets/models/ |
reservado para GLBs futuros (vazio) |
config/ |
cenas renderizáveis (JSON); episódios: config/<história>-epNN.json |
panel/ |
painel Next.js (histórias, episódios, assets, votação, agentes, Clipador) |
clipper/ |
Clipador: serviço Python de cortes de live (Streamlink, chat, Whisper, juiz de IA, FFmpeg) |
publisher/ |
Publicador: serviço Python que envia vídeos ao YouTube, TikTok e Instagram (API oficial ou sessão logada) — plano em doc/publicacao/ |
assets/library/ |
biblioteca de assets compartilhada entre histórias |
data/ |
banco SQLite e logs do painel (ignorado pelo Git) |
stories/ |
roteiros por história (bíblia e episódios), escritos pelo cenaforge-story-writer |
scripts/ |
lançador TypeScript (cli.ts, lib/, tests/) |
output/ |
execuções locais (ignorado pelo Git) |
Decisões e limitações
- Renderizador Mobile: é mais leve que o Forward+ e mantém sombras direcionais, MSAA 4x, névoa e tonemapping, suficientes para esta cena. O Compatibility (OpenGL) não foi testado.
- Tudo provisório: moto, entregador e casas são primitivas, sem esqueleto e sem animação facial. As fachadas distantes são texturas geradas localmente (sem assets de terceiros), em planos fixos que não giram para a câmera. Não há LOD dinâmico, tráfego, pedestres nem física.
- O tempo de render é dominado pela gravação dos PNGs, não pela GPU: no teste, 105 ms/quadro (prévia) e 404 ms/quadro (final) de codificação, contra 2–5 ms de GPU. Ver TEST_RESULT.
- Validação de pixels: imagens idênticas entre GPUs ou renderizadores diferentes não são garantidas. O que se garante é o estado idêntico (digest).
- Cancelamento: Ctrl+C encerra a árvore de subprocessos (
taskkill /Tno Windows) e marca a execução comocancelled. A lógica tem teste unitário, mas um Ctrl+C real no terminal não foi exercitado no teste automatizado. - Linux: o código evita suposições de Windows (caminhos com
path, sem shell, busca deGodot_v*_linux.x86_64em.tools/), mas não foi executado em Linux. O render 3D precisa de sessão gráfica: o modo--headlesssó é usado para validação, testes e preparação.
Fora do escopo desta fase
Painel Next.js, API Fastify, banco, Redis, autenticação, multiempresa, Electron, Meshy, Instagram, agentes e integração com Applio. A visão futura está na seção 15 da especificação.