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:
@@ -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).
|
||||
Reference in New Issue
Block a user