Files
MateuusandClaude Opus 5.5 84f30bbc2d 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>
2026-11-17 16:35:09 -03:00

261 lines
16 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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).