# 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](doc/TEST_RESULT.md). Especificação original: [doc/PROMPT_TESTE_VIDEO_GODOT.md](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](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](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](voice/README.md). A Godot e o FFmpeg continuam como abaixo. 1. **Godot 4.x (oficial)**. O lançador procura, nesta ordem: 1. a variável `GODOT_BIN` (caminho completo do executável); 2. `godot` ou `godot4` no `PATH`; 3. o executável oficial extraído em `.tools/godot-/` dentro do projeto (ex.: `.tools/godot-4.7.2/Godot_v4.7.2-stable_win64.exe`). Essa pasta é ignorada pelo Git. 2. **FFmpeg e FFprobe** no `PATH`, ou em `FFMPEG_BIN` / `FFPROBE_BIN`. O build precisa de um encoder H.264: `libx264` (preferido), `h264_nvenc` ou `libopenh264`. 3. Dependências do lançador: ```sh pnpm install pnpm run doctor ``` O `pnpm-workspace.yaml` recusa o script de instalação do `esbuild` (`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 `. | | `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 ` | 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/--/`, 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 -.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. ```sh 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](config/demo-street.json) e [config/demo-street-variant.json](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 de `t`. O perfil de velocidade usa rampas *smoothstep* (velocidade e aceleração contínuas) e chega **exatamente** em `travelMeters` no instante de parada. Em render, `t = quadro / fps`. O `delta` do motor não é usado: na 4.7.2 ele não sai exatamente 1/30, nem com `--fixed-fps`. Cada execução registra um `stateDigest` dos 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 = 0` antes 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 (`--resolution` não muda isso). O projeto vem em 540×960. Para cada render, o lançador escreve um `godot/override.cfg` com 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/-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](doc/TEST_RESULT.md). - **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 /T` no Windows) e marca a execução como `cancelled`. 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 de `Godot_v*_linux.x86_64` em `.tools/`), mas não foi executado em Linux. O render 3D precisa de sessão gráfica: o modo `--headless` só é 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](doc/PROMPT_TESTE_VIDEO_GODOT.md).