CenaForge: primeira versão pública

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>
This commit is contained in:
2026-11-17 16:35:09 -03:00
co-authored by Claude Opus 5.5
commit 84f30bbc2d
484 changed files with 74826 additions and 0 deletions
+260
View File
@@ -0,0 +1,260 @@
# 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-<versão>/` 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 <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.
```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/<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](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).