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,371 @@
|
||||
# Bancada de rastreio de rosto (Fase 0) — MediaPipe × OpenSeeFace, YuNet para a câmera
|
||||
|
||||
Data: 16/11/2026. Plano: [PLANO_RASTREIO_REACAO.md](PLANO_RASTREIO_REACAO.md). Script:
|
||||
`clipper/tools/face_bench.py`; saídas em `output/face-bench/` (`results.json`, `cam_sheet.png`, `track_*.png`).
|
||||
|
||||
```
|
||||
clipper\.venv\Scripts\python.exe clipper\tools\face_bench.py --session 3
|
||||
```
|
||||
|
||||
Máquina: Windows 11, 32 threads de CPU, RTX 2060 Super (sem uso: MediaPipe Python no Windows é só CPU).
|
||||
Dados: sessão 3 (skipnho, Warzone/ROB RUN, 99 blocos `.ts` 1280×720 a 60 qps, 2954 s). Banco aberto só
|
||||
leitura (`mode=ro`); o serviço do usuário estava gravando e criou cortes novos durante a bancada.
|
||||
|
||||
## Decisão
|
||||
|
||||
**MediaPipe Face Landmarker confirmado.** Critério do plano: rosto em ≥ 85 % dos quadros com o streamer
|
||||
presente e ≤ 15 ms/quadro na CPU.
|
||||
|
||||
| | MediaPipe 1.2.3 | OpenSeeFace (modelo 3, onnxruntime 1.32) |
|
||||
|---|---|---|
|
||||
| Rosto presente (6 trechos × 180 quadros) | **97,8–100 %** (1 trecho 97,8 %, demais 100 %) | 100 % |
|
||||
| ms/quadro, média (p95), recorte 256×384 | **5,1–7,1 (5,6–11,6)** | 9,5–11,5 (10,1–17,4), 1 thread |
|
||||
| Expressões | 52 blendshapes prontos | só 66 pontos; "boca aberta" calculada à mão, sinal fraco |
|
||||
|
||||
OpenSeeFace fica como plano B (pesos baixados, código mínimo funcionando na bancada), mas não ganhou em
|
||||
nada aqui: a câmera desta live é boa (rosto ~110 px na fonte). Não foi testado em câmera escura/minúscula.
|
||||
|
||||
## 1. Achar a câmera (YuNet, quadro inteiro)
|
||||
|
||||
12 quadros espalhados (30 s … 2924 s), 1280×720, limiar 0,6. Folha: `output/face-bench/cam_sheet.png`
|
||||
(verde = YuNet, azul = câmera da IA, amarelo = câmera estimada pelo rosto).
|
||||
|
||||
| Métrica | Valor |
|
||||
|---|---|
|
||||
| Quadros com rosto do streamer | **12/12** (presença do grupo = 1,0) |
|
||||
| Rosto (mediana, 0–1) | x 0,084 y 0,504 w 0,066 h 0,152 → **~110 px de altura** |
|
||||
| Oscilação do centro (desvio / tamanho do rosto) | x 0,24, y 0,06 (o x sobe por 1 quadro com ele inclinado, t=30 s) |
|
||||
| Câmera estimada (rosto × 3,2 larg., × 3,6 alt.) | x 0,011 y 0,371 w 0,211 h 0,548 |
|
||||
| **IoU com a câmera da IA** (x 0,014 y 0,532 w 0,183 h 0,395) | **0,61** |
|
||||
| Fração do rosto dentro do retângulo da IA | **0,81** — a IA corta a testa (topo em y 0,532, o rosto começa em 0,504) |
|
||||
| Tempo YuNet 1280×720 | 15–17 ms/quadro |
|
||||
| Rostos falsos | tela de carregamento do ROB RUN (t=819 e 1872): **6 rostos do jogo** em cada, posições fixas |
|
||||
|
||||
Observações para o `locate_cam` (agente B) e para o `face.py`:
|
||||
|
||||
- A câmera desta live **não tem moldura**: é o streamer recortado (fundo removido) sobre o jogo, com um
|
||||
banner de patrocinador logo abaixo do rosto. "Bordas persistentes" não vão existir aqui; o retângulo tem de vir
|
||||
do rosto expandido. O retângulo da IA cortou a cabeça; o local ficou mais correto (ver folha).
|
||||
- Os rostos do jogo aparecem em **2 de 12 quadros** (mesma tela repetida) → o corte de 50 % de presença resolve.
|
||||
Note que eles se repetem na *mesma posição*; presença é o que separa, não estabilidade.
|
||||
- Agrupar comparando com o **1º membro** do grupo partiu o streamer em dois (inclinado em t=30 s, centro
|
||||
0,064 × 0,116 = 0,8 largura de rosto). Comparar com o **centroide** do grupo e tolerância de **1 largura /
|
||||
1 altura de rosto** juntou os 12. Use essa regra.
|
||||
- Rosto ≈ 15 % da altura do quadro → bem abaixo do limite de 40 % de "tela cheia".
|
||||
|
||||
### Variante do YuNet
|
||||
|
||||
Com `opencv-contrib-python 5.0.0.93` (`cv2 5.0.0`), **as duas variantes funcionaram** — `2023mar` (entrada
|
||||
fixa) e `2026may` (entrada dinâmica) deram as mesmas caixas em 768×432, 640×360 e 1280×720, e o mesmo resultado
|
||||
nos 12 quadros. Mesmo assim, o lock fixa a **`face_detection_yunet_2026may.onnx`**: é a indicada pelo
|
||||
opencv_zoo para o motor ONNX Runtime do OpenCV 5.x (a 2023mar pode falhar quando o OpenCV usar esse motor).
|
||||
O OpenCV imprime `[ WARN ] ... Targets are not supported by the new graph engine for now` ao criar o detector:
|
||||
inofensivo.
|
||||
|
||||
## 2. Rastreio no recorte da câmera (6 qps, 30 s por trecho)
|
||||
|
||||
Recorte: câmera local + 10 % de margem = px (0, 226, 316, 472) → escalado para **256×384** (maior lado 384),
|
||||
`rgb24` por pipe. Comparação extra só com MediaPipe no recorte da IA (274×340 → 308×384).
|
||||
|
||||
| Trecho (início) | Corte | MP % rosto | MP ms média/p95 | OSF % | OSF ms média/p95 |
|
||||
|---|---|---|---|---|---|
|
||||
| calmo (1980 s, menor volume a ≥ 120 s de cortes) | — | 100 | 5,6 / 6,6 | 100 | 11,5 / 17,4 |
|
||||
| 1064 s | 9 — lag, "três jogos ao mesmo tempo" (pico 1084) | 100 | 7,1 / 11,6 | 100 | 9,5 / 10,1 |
|
||||
| 1608 s | 10 — "sai fora!" (pico 1628) | 97,8 | 5,5 / 7,2 | 100 | 9,5 / 10,1 |
|
||||
| 2180 s | 11 — internet cai (pico 2200, descartado) | 100 | 5,6 / 7,1 | 100 | 9,9 / 11,7 |
|
||||
| 2381 s | 12 — heliponto (pico 2401) | 100 | 5,4 / 6,4 | 100 | 9,7 / 10,5 |
|
||||
| 2897 s | 13 — "Helicóptero!" (pico 2917, descartado) | 100 | 5,1 / 5,6 | 100 | 9,9 / 12,1 |
|
||||
|
||||
Recorte da IA (rosto maior no recorte, ~105 px): MediaPipe 98,3–100 %, 5,4–7,3 ms. Recorte apertado no rosto
|
||||
(284×284 → 256 ou 384, teste à parte): blendshapes praticamente iguais (diferença ≤ 0,01 na média), então
|
||||
**o tamanho do recorte não muda o sinal**; 256–384 px no maior lado basta.
|
||||
|
||||
Tempo por bloco de 30 s: decodificar+recortar+escalar+6 qps com FFmpeg ≈ **0,45–0,6 s**, MediaPipe 180 ×
|
||||
~6 ms ≈ **1,1 s** → **≈ 1,6–1,8 s por bloco** (meta do plano: ≤ 5 s). Medido num processo com 32 threads livres;
|
||||
a carga real de CPU com a gravação rodando junto não foi medida.
|
||||
|
||||
Folhas de contato (`track_*.png`, 10 quadros por trecho; verde = MediaPipe, vermelho = OpenSeeFace): conferidas
|
||||
a olho — os dois acertam o rosto em todos os quadros mostrados, inclusive com o banner trocando atrás.
|
||||
|
||||
## 3. As expressões sobem nos cortes?
|
||||
|
||||
Média (e p90) por trecho, MediaPipe, recorte local. `smile` = maior entre `mouthSmileLeft/Right`.
|
||||
|
||||
| Trecho | smile média (p90) | jawOpen máx | browInnerUp média (p90) | browDownLeft máx | eyeWide máx | OSF boca aberta média |
|
||||
|---|---|---|---|---|---|---|
|
||||
| calmo | **0,06** (0,15) | 0,01 | 0,02 (0,03) | 0,07 | 0,002 | 0,012 |
|
||||
| corte 9 (lag) | 0,06 (0,14) | 0,05 | **0,27 (0,77)** | 0,03 | 0,004 | 0,018 |
|
||||
| corte 10 ("sai fora") | **0,48 (0,88)** | **0,42** | 0,02 (0,05) | **0,61** | 0,007 | 0,029 |
|
||||
| corte 11 (internet) | 0,12 (0,48) | 0,10 | 0,07 (0,21) | 0,12 | 0,037 | 0,020 |
|
||||
| corte 12 (heliponto) | **0,55 (0,82)** | 0,11 | 0,01 (0,01) | 0,16 | 0,002 | 0,020 |
|
||||
| corte 13 ("Helicóptero!") | 0,30 (0,52) | 0,01 | 0,02 (0,04) | 0,08 | 0,015 | 0,012 |
|
||||
|
||||
Leitura:
|
||||
|
||||
- **Sorriso é o sinal forte**: 0,06 no calmo × 0,48–0,55 nos cortes de risada (10 e 12), com longas
|
||||
sequências de segundos em 0,75–0,95 (corte 10: 1613–1629 s; corte 12: 2391–2410 s). Bate com os títulos e com o chat
|
||||
(`tags.risada`). No corte 12 o sorriso perto do pico (±4 s) foi 0,68.
|
||||
- **`browInnerUp` marcou o lag** (corte 9): 0,27 de média e p90 0,77 contra 0,02 no calmo — cara de
|
||||
"ué?"/confusão sem sorriso. Bom candidato a "choque/confusão" no `reaction.py`.
|
||||
- **`browDown*` sobe com o grito** do corte 10 (0,61) junto com `jawOpen` 0,42 num segundo isolado (1628 s,
|
||||
exatamente o pico do chat).
|
||||
- **`jawOpen` quase nunca passa de 0,1** e **`eyeWide*` fica em ~0** em todos os trechos, inclusive com recorte
|
||||
maior. Este streamer ri de boca pouco aberta; não dá para concluir se é ele ou o modelo. Na fórmula, usar
|
||||
z relativo ao próprio streamer (como o plano já prevê) e **não** exigir jawOpen alto para "risada".
|
||||
- Os cortes descartados pelo usuário (11 e 13) têm reação facial bem menor que os aprovados 10 e 12 — indício
|
||||
(6 trechos só) de que o rosto ajuda a separar corte bom de ruim.
|
||||
- OpenSeeFace: a "boca aberta" calculada dos pontos quase não se mexe (0,012 → 0,029); sem blendshapes ele
|
||||
não serve para o sinal de expressão desta live.
|
||||
|
||||
## Notas para o agente de integração (Fase 2)
|
||||
|
||||
**Instalação** (`clipper/requirements.txt`): `mediapipe==1.2.3`, `opencv-contrib-python==5.0.0.93`,
|
||||
`numpy==2.5.5`, `onnxruntime==1.32.0`. Nunca `opencv-python-headless` junto. Pesos em `data/clipper/models/`
|
||||
conforme `clipper/models.lock.json` (o `setup.ps1` passo 6b baixa e confere o sha256; teste do bloco isolado num
|
||||
diretório vazio baixou os 4 e conferiu).
|
||||
|
||||
**API do MediaPipe 1.2.3 que funcionou** (atenção: `from mediapipe.tasks import python` **não existe** nesta
|
||||
versão; importe os submódulos):
|
||||
|
||||
```python
|
||||
import mediapipe as mp
|
||||
from mediapipe.tasks.python.core.base_options import BaseOptions
|
||||
from mediapipe.tasks.python import vision
|
||||
|
||||
options = vision.FaceLandmarkerOptions(
|
||||
base_options=BaseOptions(model_asset_path=str(models / "face_landmarker.task")),
|
||||
running_mode=vision.RunningMode.VIDEO,
|
||||
num_faces=1,
|
||||
min_face_detection_confidence=0.5,
|
||||
min_face_presence_confidence=0.5,
|
||||
min_tracking_confidence=0.5,
|
||||
output_face_blendshapes=True,
|
||||
)
|
||||
with vision.FaceLandmarker.create_from_options(options) as landmarker:
|
||||
image = mp.Image(image_format=mp.ImageFormat.SRGB, data=np.ascontiguousarray(rgb)) # uint8 H×W×3 RGB
|
||||
result = landmarker.detect_for_video(image, timestamp_ms) # int, estritamente crescente
|
||||
result.face_landmarks[0] # 478 NormalizedLandmark (x, y em 0..1 do recorte)
|
||||
result.face_blendshapes[0] # 52 Category: .category_name, .score
|
||||
```
|
||||
|
||||
- `timestamp_ms` tem de crescer sempre dentro do mesmo landmarker; usei o tempo da sessão em ms. Ao recomeçar
|
||||
(bloco fora de ordem, reset), crie outro landmarker.
|
||||
- O array vindo de `np.frombuffer` é só-leitura: passei uma cópia contígua (`.copy()`); sem cópia não testei.
|
||||
- Ao criar, o MediaPipe escreve avisos do glog no stderr (`inference_feedback_manager ... Disabling support for
|
||||
feedback tensors`, `Logging before InitGoogle()`): inofensivos.
|
||||
|
||||
**YuNet:** `cv2.FaceDetectorYN.create(path, "", (w, h), 0.6, 0.3, 50)`; `_, faces = det.detect(bgr)`;
|
||||
`faces` é `None` ou N×15 (`x, y, w, h` em px, 10 valores de pontos, `score` na coluna 14). Entrada BGR uint8.
|
||||
Com a `2026may`, `setInputSize((w, h))` troca a resolução sem recriar.
|
||||
|
||||
**FFmpeg do recorte** (por bloco, sem shell):
|
||||
`ffmpeg -v error -ss <off> -t <len> -i seg_XXXXX.ts -vf fps=6,crop=W:H:X:Y,scale=OW:OH -f rawvideo -pix_fmt rgb24 -`
|
||||
(crop/escala com valores pares). `fps` antes do `crop` reduz o trabalho do filtro.
|
||||
|
||||
**OpenSeeFace (plano B):** `OsfTracker` em `face_bench.py` reimplementa o mínimo do `tracker.py` do commit
|
||||
`50c0974`: detector `mnv3_detection_opt.onnx` (entrada `input` 1×3×224×224, normalização ImageNet; saída 56×56 com
|
||||
NMS por maxpool e raio × 112) e landmarks `lm_model3_opt.onnx` (224×224, saída 198×28×28: 66 mapas de
|
||||
confiança + 66 offsets de linha + 66 de coluna, `logit/16`). Cuidado: no original a 1ª coluna dos pontos é **y**.
|
||||
Limiar de confiança 0,6. Esforço ~20 min; ficou funcionando, mas não é recomendado aqui.
|
||||
|
||||
## Integração (Fase 2) — pipeline de verdade na sessão 3
|
||||
|
||||
Data: 16/11/2026. Código: `clipper/app/face.py` (novo), `reaction.py` recalibrado, ganchos em `db.py` (migração
|
||||
**v5** `face_track`), `intel.py`, `worker.py`, `scoring.py`, `judge.py`, `main.py`. Rodado numa **cópia** do banco
|
||||
(`output/face-bench/clipper-copy.db`, `sqlite3.backup` do banco vivo aberto só leitura) com o `FaceService` real
|
||||
(YuNet + MediaPipe 1.2.3, CPU), bloco a bloco como o laço `face` do serviço. Saída: `output/face-bench/integration.json`
|
||||
e `track_log.txt`. A live seguia gravando: 144 blocos, 4316 s (o jogo trocou para Supermarket Together perto do fim).
|
||||
|
||||
### Câmera local × IA
|
||||
|
||||
`FaceService.locate` (12 quadros espalhados pela live inteira, YuNet 1280 px + `reaction.locate_cam` com grupo pelo
|
||||
centro e tolerância de 1 rosto): **1,34 s**, rosto em 10/12 quadros, confiança 0,585.
|
||||
|
||||
| Retângulo | x | y | w | h | IoU com o local | rosto dentro dele |
|
||||
|---|---|---|---|---|---|---|
|
||||
| **local (yunet)** | 0,005 | 0,388 | 0,213 | 0,519 | — | 1,00 |
|
||||
| IA da bancada (cam_json antigo) | 0,014 | 0,532 | 0,183 | 0,395 | 0,60 | 0,85 (corta a testa) |
|
||||
| IA nova (cam_json, Supermarket Together) | 0,036 | 0,499 | 0,167 | 0,222 | 0,34 | 1,00 |
|
||||
| layout da sessão (marcado à mão) | 0,023 | 0,425 | 0,206 | 0,241 | 0,41 | 1,00 |
|
||||
|
||||
O local deixa 0,85 altura de rosto de folga acima da testa. Ele é mais **alto** que o layout marcado à mão: vai
|
||||
até ~1,75 rosto abaixo do queixo e pega o banner do patrocinador; o manual termina logo abaixo do queixo.
|
||||
|
||||
### Rastreio (câmera local + 10 %, 6 qps, recorte ~384 px)
|
||||
|
||||
| Métrica | Valor |
|
||||
|---|---|
|
||||
| Blocos | 144/144 `done`, backend `mediapipe`, nenhum erro |
|
||||
| Tempo por bloco de 30 s (FFmpeg + MediaPipe, landmarker novo por bloco) | média **1,47 s**, mediana 1,44, p95 2,05, máx 2,44 (meta ≤ 5 s) |
|
||||
| Quadros com rosto | **85,1 %** dos 25 822 (segundos com rosto: 85,4 %) |
|
||||
| Trechos dos cortes 9–13 e calmo | rosto 95–100 %; 1,24–2,12 s por bloco |
|
||||
| Sem rosto | 630 s, quase tudo de **3767 s ao fim** (troca de jogo/câmera) e 3692–3761 s |
|
||||
|
||||
### Calibração (números da live inteira, não só dos 6 trechos da bancada)
|
||||
|
||||
Na live inteira o normal deste streamer é bem diferente dos trechos: sorriso por segundo mediana 0,24 (MAD 0,30),
|
||||
`browOuterUp` sobe junto com `browInnerUp` (canal de "surpresa" com mediana 0,24), movimento p90 0,46 e até 3,0
|
||||
quando o rastreio pisca. A 1ª rodada (surpresa = olho ou sobrancelha externa, movimento na intensidade, corte
|
||||
"face" com z ≥ 3 e apoio fraco) deu **165 picos** (41 "choque", 20 "susto" — os maiores eram o rosto piscando) e
|
||||
**32 cortes novos** de fonte `face` em 72 min, mais que os 21 do chat. Ajustes:
|
||||
|
||||
- `brow` = maior entre browInnerUp e browOuterUp; `surprise` = só olho arregalado; sobrancelha + cabeça mexendo = susto;
|
||||
- movimento fora da intensidade (só rotula) e só vale com rosto em ≥ 80 % do segundo;
|
||||
- pisos por canal: sorriso 0,10, boca 0,05, olho 0,06, franzido 0,07, sobrancelha 0,10 (peso 0,6), movimento 0,15;
|
||||
- corte novo de fonte `face`: z ≥ 6 (forte) **e** áudio suavizado ≥ 1,5 **ou** ≥ 2 mensagens de reação até 10 s depois.
|
||||
|
||||
Resultado final: **114 picos** (risada 77, grito 16, confuso 10, susto 6, raiva 5), nenhum no trecho calmo
|
||||
(1980–2010 s), **0 cortes novos** de fonte `face` (nenhum pico forte teve apoio suficiente), **14 dos 21** momentos do
|
||||
chat ganharam `reasons.face`. A nota dos momentos do chat sobe no máximo 0,6.
|
||||
|
||||
### 10 maiores reações e os cortes
|
||||
|
||||
| Pico | Rótulo | z | Corte que contém (±5 s) |
|
||||
|---|---|---|---|
|
||||
| 2884 s | risada forte | 10,8 | 13 (descartado) |
|
||||
| 3264 s | risada forte | 10,4 | — |
|
||||
| 1553 s | risada forte | 9,9 | — (75 s antes do corte 10) |
|
||||
| 403 s | risada forte | 7,9 | — |
|
||||
| 1247 s | risada forte | 7,8 | — |
|
||||
| 3687 s | risada forte | 7,7 | 21 (descartado pela IA) |
|
||||
| 3588 s | risada forte | 7,6 | — |
|
||||
| 144 s | grito forte | 7,4 | — |
|
||||
| 493 s | risada forte | 7,3 | — (perto do pico do chat em 501 s, que não virou corte) |
|
||||
| 3078 s | risada forte | 7,2 | 16 |
|
||||
|
||||
Nos cortes da bancada (rótulo/z do maior pico dentro do corte ±5 s):
|
||||
|
||||
| Corte | Usuário | Rosto |
|
||||
|---|---|---|
|
||||
| 9 (lag) | — | **confuso** 3,8 em 1076 s e 1090 s (era "choque" antes do ajuste) |
|
||||
| 10 ("sai fora!") | aprovado | risada 4,4 em 1638 s; **grito em 1626 s** (o pico do chat é 1628 s) |
|
||||
| 11 (internet cai) | descartado | risada 4,7 |
|
||||
| 12 (heliponto) | aprovado | nenhum pico ≥ 3 dentro do corte (sorriso alto, mas o normal dele já estava alto; risada forte em 2339 s) |
|
||||
| 13 ("Helicóptero!") | descartado | **risada forte 10,8** em 2884 s (a maior da live) |
|
||||
|
||||
Leitura honesta: com a live inteira, o rosto **não** separa os aprovados dos descartados como os 6 trechos da
|
||||
bancada sugeriam — o 13 descartado tem a maior risada, o 12 aprovado não tem pico (z relativo a um "normal" que
|
||||
já é sorridente). O rosto acerta bem o **tipo** de reação (lag = confuso, grito no segundo do grito) e o início
|
||||
dela; por isso entra como reforço limitado, texto para o analista e série para o editor — não como juiz.
|
||||
|
||||
Linha que vai para o analista (corte 10, janela −60/+15 s): "risada forte em 1553s; grito em 1626s; risada em
|
||||
1638s; susto em 1651s".
|
||||
|
||||
### Não verificado na integração
|
||||
|
||||
- Serviço de verdade rodando o laço `face` junto com gravação + transcrição (CPU concorrente); só a cópia, fora do serviço.
|
||||
- Câmera que muda de lugar no meio da live: a detecção roda uma vez (com nova tentativa só quando não acha rosto);
|
||||
aqui o rosto some depois de 3767 s e o rastreio marca esses segundos sem rosto.
|
||||
- Backend OpenSeeFace (plano B) dentro do `face.py`: código portado da bancada, sem teste com os pesos reais.
|
||||
- Download sob demanda real (os pesos já estavam em `data/clipper/models/`; testado só com download falso).
|
||||
- Painel no navegador (só `tsc`); `GET …/face` só pelos testes da API.
|
||||
|
||||
## Não verificado
|
||||
|
||||
- Outra sessão/canal (só existe a sessão 3 no banco e em `data/clipper/sessions/`).
|
||||
- Câmera escura, pequena (< 40 px de rosto) ou muito comprimida — o caso em que o OpenSeeFace poderia ganhar.
|
||||
- Live sem câmera (falso positivo do YuNet no jogo ao longo de uma live inteira) e câmera em tela cheia.
|
||||
- Uso de CPU com a gravação/transcrição rodando ao mesmo tempo; GPU não foi tentada.
|
||||
- `setup.ps1` inteiro não foi rodado; só o bloco novo do passo 6b (isolado, nas duas situações: arquivos já
|
||||
presentes e pasta vazia) e o parse do arquivo.
|
||||
|
||||
## Testes de 17/11 — ao vivo
|
||||
|
||||
Data: 16–17/11/2026 (23:30–00:10). Instância **isolada** do Clipador na porta **4521**, com
|
||||
`CLIPPER_DATA_DIR=output/face-live-test/data` e `CLIPPER_OUTPUT_DIR=output/face-live-test/clips` (variáveis novas do
|
||||
`config.py`; o padrão continua `data/clipper` e `output/clipper`), juiz `off`, banco novo com o `sqlite_sequence` de
|
||||
`sessions` em 90000 (a chave de idempotência da voz é `clipper-<sessão>-<bloco>`: as sessões 1–3 colidiriam com as do
|
||||
banco real). Nada foi escrito em `data/clipper/` nem no serviço do usuário (4520). Saídas em `output/face-live-test/`
|
||||
(`t1_models.json`, `t2_osf.json`, `monitor.jsonl`, `service*.log`, `panel-*.png`, cortes em `clips/`).
|
||||
|
||||
### 1. Download real dos modelos — passou
|
||||
|
||||
`face.ModelStore` com a pasta de modelos vazia (`output/face-live-test/data/models/`), rede de verdade:
|
||||
|
||||
| Modelo | Tamanho | Tempo | sha256 |
|
||||
|---|---|---|---|
|
||||
| `face_detection_yunet_2026may.onnx` | 229 738 B | 0,79 s | confere |
|
||||
| `face_landmarker.task` | 3 758 596 B | 0,33 s | confere |
|
||||
| `osf_lm_model3_opt.onnx` | 13 500 226 B | 0,91 s | confere |
|
||||
| `osf_mnv3_detection_opt.onnx` | 568 302 B | 0,28 s | confere |
|
||||
|
||||
Nenhum `.part` sobrou; nova checagem sem baixar: 4 ms. Num diretório temporário: lock adulterado (sha256 = 0…0) →
|
||||
`FaceUnavailable("sha256 … não confere")` e a pasta ficou vazia (`.part` apagado); arquivo corrompido no lugar →
|
||||
baixado de novo e aceito; URL 404 → `FaceUnavailable` e pasta vazia. O lock real não foi tocado.
|
||||
|
||||
### 2. Plano B OpenSeeFace com pesos reais (sessão 3, cópia do banco) — passou
|
||||
|
||||
Backend `openseeface` forçado pelo `tracker_factory` do `FaceService.process_block`, nos blocos 54 (grito/risada do
|
||||
corte 10), 66 (calmo) e 80 (heliponto), com a câmera local da integração; depois o MediaPipe nos mesmos blocos. Cópia
|
||||
por `sqlite3.backup` do banco aberto só leitura (`output/face-live-test/t2-copy.db`); os `.ts` foram só lidos.
|
||||
|
||||
| Bloco | OSF % rosto | OSF ms/quadro (bloco) | MP % rosto | MP ms/quadro (bloco) | cy OSF × MP | size OSF × MP |
|
||||
|---|---|---|---|---|---|---|
|
||||
| 54 | 96,7 | 12,3 (2,2 s) | 94,4 | 13,2 (2,4 s) | 0,605 × 0,593 | 0,110 × 0,132 |
|
||||
| 66 | 100 | 13,6 (2,4 s) | 100 | 10,4 (1,9 s) | 0,600 × 0,588 | 0,109 × 0,133 |
|
||||
| 80 | 100 | 13,9 (2,5 s) | 100 | 9,8 (1,8 s) | 0,601 × 0,589 | 0,105 × 0,128 |
|
||||
|
||||
ms/quadro aqui = tempo do bloco inteiro (FFmpeg + modelo) ÷ 180. A série gravada é válida nos dois (180 quadros, `cx/cy`
|
||||
dentro da câmera, `size` 0..1). O `size` do OpenSeeFace é ~18 % menor (os 66 pontos não pegam a testa). Sem
|
||||
blendshapes, os canais ficam em 0 → `reaction_signal` 0 em todo segundo, nenhum pico, `find_moments(face=…)` sem erro
|
||||
e sem corte, e o `view` responde. O MediaPipe no mesmo trecho: grito em 1626 s e risada em 1638 s (z 4,2 e 4,4), iguais
|
||||
à integração. **Bug achado e corrigido:** com o OpenSeeFace, o `FaceService.summary` mandava ao analista "sem reação
|
||||
marcante no rosto", o que é falso (ele não mede expressão). Agora a linha não vai quando a série da sessão é do plano B.
|
||||
|
||||
### 3. Serviço real gravando ao vivo (twitch.tv/skipnho, ROB RUN) — passou
|
||||
|
||||
Sessão 90001, 722 s gravados (23:48–00:01), 25 blocos. A voz (4510) ficou no ar até 23:56 (1 bloco com erro de
|
||||
transcrição depois disso). No meio do teste (23:56) o `start.bat` do usuário foi reiniciado e **todos** os serviços da
|
||||
faixa caíram, inclusive a instância de teste (sem traceback e sem evento de crash no Windows). Religada, a sessão foi
|
||||
**retomada sozinha** (`resume_interrupted`), com a numeração dos blocos seguindo.
|
||||
|
||||
| Verificação | Resultado |
|
||||
|---|---|
|
||||
| Câmera | `cam_json.source = yunet`, rosto em 12/12 quadros, confiança 0,864, cam x 0,014 y 0,372 w 0,207 h 0,545 (achada 73 s depois do início, com 2 blocos analisados) |
|
||||
| `_face_loop` durante a gravação | `face_track done` acompanhou: atraso de 0–1 bloco em regime (37 leituras do monitor), 25/25 `done`, 0 erro |
|
||||
| Tempo por bloco (FFmpeg + MediaPipe, com gravação + transcrição + chat juntos) | média **1,71 s**, mediana 1,74, p95 2,20, máx 2,91 |
|
||||
| Latência do fim do bloco ao rosto gravado | 1,4–9,4 s (o laço dorme até 10 s quando ocioso); 16,5 s no bloco pego durante a reconstrução |
|
||||
| CPU (árvore do processo, % de 1 núcleo, amostras de 15 s) | média 16,8 %, pico 90,5 % (reconstrução depois do reset); sistema (32 threads): média 21 %, máx 48 % |
|
||||
| Rosto presente | 99,8 % dos segundos |
|
||||
| `GET /v1/sessions/90001/face?from=60&to=75` | 200; `cx` 0,10–0,13, `cy` 0,58–0,59, `size` 0,12–0,13 (no quadro inteiro, dentro da câmera); `signal`, `blocks`, `camSource` |
|
||||
| `POST …/face/reset` | 200 `{deleted: 17}` com o laço ocioso; **202** `{scheduled: true}` com um bloco em andamento; série refeita: 19 blocos em ~45 s (≈ 12× o tempo real) |
|
||||
| `find_new_clips` | não travou: 2 cortes do chat criados ao vivo e renderizados em `output/face-live-test/clips/90001/`; o 1º com `reasons.face` = **grito forte, z 12,7, pico em 430 s** (corte 383–443 s); o 2º, decidido durante a reconstrução do reset, saiu sem rosto (atraso > 2 blocos → não espera, como desenhado) |
|
||||
|
||||
**Bug achado e corrigido:** com o juiz `off`, o `Intel.research_pending` tentava pesquisar o jogo e registrava o WARNING
|
||||
"pesquisa de jogo falhou: IA desligada" **a cada 30 s**. Agora ele sai cedo com a IA desligada (o jogo fica `pending`).
|
||||
|
||||
### Live sem câmera (twitch.tv/lofigirl, 3 min) — falhou, corrigido
|
||||
|
||||
Sessão 90002, 8 blocos. O YuNet achou um "rosto" de **24×34 px colado na borda esquerda** (a tela de um notebook
|
||||
desenhado) em 8 de 12 quadros, com score 0,61–0,66. O `locate_cam` aceitou (`hasWebcam: true`, confiança 0,42) e
|
||||
aplicou uma câmera de 51×122 px como layout da sessão. O MediaPipe não achou rosto nenhum no recorte (`present` 0 em
|
||||
todos). O rosto real do skipnho tem score **0,92–0,94** em todo quadro. **Correção:** `ReactionParams.min_cam_score =
|
||||
0.7` — o grupo que vira câmera precisa de confiança média ≥ 0,7 (`reaction.locate_cam`). Refeito no serviço:
|
||||
`detect-cam` → `hasWebcam: false` (8/11 quadros com o falso positivo, recusado), série refeita como **8 `no_cam`**,
|
||||
layout sem câmera e `GET …/face` respondendo; um corte de áudio saiu normalmente. O skipnho continua achado (confiança 0,87).
|
||||
|
||||
### 4. Painel no navegador (http://127.0.0.1:4500/clipper) — passou, com ressalva
|
||||
|
||||
A página carrega sem erro nem aviso no console (só logs de dev e um "issue" de acessibilidade: campos sem id/name).
|
||||
O painel fala com o serviço **antigo** da 4520: o selo da câmera aparece como "câmera achada pela IA" (o `cam_json`
|
||||
antigo não tem `source`) e o interruptor "Rastrear a reação do streamer" fica **oculto** (o serviço antigo não manda
|
||||
`faceTrack`, e o painel esconde o interruptor de propósito). Para ver o desenho com dados do serviço novo, as respostas
|
||||
GET de `/api/clipper/*` foram alteradas **só no navegador** (script injetado na aba, nada enviado ao serviço): selo
|
||||
"câmera achada (rosto, sem IA)", interruptor visível e ligado ("Nada mudou", nenhum botão de salvar clicado) e o chip
|
||||
do cartão "rosto: risada forte · intensidade 4,4 · pico em 8:21". Nenhuma configuração, aprovação ou corte foi
|
||||
alterado. Screenshots: `output/face-live-test/panel-1…5.png`. A interação real (ligar/desligar, `reasons.face` de
|
||||
verdade) depende de o serviço do usuário rodar o código novo. Ele reiniciou às 23:56, então já pega o `config.py` e o
|
||||
`intel.py` corrigidos, mas **não** a correção do `locate_cam` (feita depois): é preciso reiniciar o `start.bat` de novo.
|
||||
|
||||
### Testes automatizados
|
||||
|
||||
`clipper/.venv/Scripts/python -m pytest -q`: verde (novos: série OpenSeeFace no sinal/pontuação/resumo, objeto parado
|
||||
de score baixo no `locate_cam`, `research_pending` quieto com a IA desligada, `CLIPPER_DATA_DIR`/`CLIPPER_OUTPUT_DIR`).
|
||||
`npx tsc --noEmit -p panel`: sem erros.
|
||||
|
||||
### Ainda não verificado
|
||||
|
||||
- Câmera em tela cheia e câmera escura ou minúscula (nenhuma live assim encontrada); GPU.
|
||||
- Live longa (> 15 min) com o rastreio: a janela da pontuação ao vivo (`LIVE_WINDOW_S`, 900 s) não foi ultrapassada.
|
||||
- O juiz analista recebendo a linha "Rosto do streamer" ao vivo (juiz desligado para não gastar cota).
|
||||
- Interação real com o interruptor no painel contra o serviço novo.
|
||||
@@ -0,0 +1,137 @@
|
||||
# Plano — Rastreio de reação (câmera + rosto do streamer) no Clipador
|
||||
|
||||
Data: 16/11/2026. Dono do pedido: usuário. Escopo: **só o Clipador** (`clipper/`); o editor de cortes está com
|
||||
outro agente — não mexer em `clipper/app/editor*.py` nem nos componentes do editor no painel.
|
||||
|
||||
## Objetivo
|
||||
|
||||
1. Saber, sem gastar IA, **se a live tem câmera** e **onde ela está** no quadro.
|
||||
2. **Rastrear o rosto** do streamer dentro da câmera, ao longo da live inteira.
|
||||
3. Transformar as **expressões** (risada, grito, susto, raiva, choque, movimento da cabeça) num sinal por segundo
|
||||
que **reforça e cria cortes**, ajuda a achar o início/fim da reação e vai, em texto, para o juiz analista.
|
||||
4. Deixar a série do rosto (centro, tamanho, reação) disponível na API para o editor reenquadrar a câmera.
|
||||
|
||||
## Stack escolhida (pesquisa de 16/11/2026)
|
||||
|
||||
| Papel | Ferramenta | Licença | Por quê |
|
||||
|---|---|---|---|
|
||||
| Achar a câmera (rosto pequeno no quadro inteiro) | **YuNet** (OpenCV Zoo, `cv2.FaceDetectorYN`) | MIT | leve, CPU, qualquer resolução; OpenCV já vem com o MediaPipe |
|
||||
| Pontos + expressões | **MediaPipe Face Landmarker** (`mediapipe==1.2.3`) | Apache-2.0 | 478 pontos 3D + **52 blendshapes** prontos (jawOpen, mouthSmile*, eyeWide*, browInnerUp, browDown…); 37,7 mil estrelas, commit diário |
|
||||
| Plano B (câmera escura/pequena/comprimida) | **OpenSeeFace** — só os `.onnx` no onnxruntime atual | BSD-2 | mais estável em condição ruim, segundo o autor; sem blendshapes; repo preso em Python 3.9 |
|
||||
| Fase 2 (opcional) | EmotiEffLib (ex-HSEmotion) | Apache-2.0 | rótulo de emoção para o juiz |
|
||||
|
||||
Descartados: SCRFD/InsightFace (pesos não comerciais), YOLO-Face (GPL/AGPL), LibreFace (não comercial),
|
||||
OpenFace 3.0 (só pesquisa, parado desde jun/2025), Py-Feat (licença indefinida). Os cortes serão publicados:
|
||||
**nada de peso não comercial ou copyleft**.
|
||||
|
||||
## Fases e agentes
|
||||
|
||||
```
|
||||
Fase 0 A "bancada" ──┐ (paralelo)
|
||||
Fase 1 B "sinal" ──┤
|
||||
└─► Fase 2 C "integração" ─► Fase 3 D revisão (python-reviewer) ─► E skill-updater
|
||||
```
|
||||
|
||||
### Fase 0 — Agente A "bancada" (instalação + teste comparativo)
|
||||
|
||||
Dono de: `clipper/requirements.txt`, `clipper/models.lock.json` (novo), `scripts/setup.ps1` (passo 6b),
|
||||
`clipper/tools/face_bench.py` (novo), `doc/FACE_BAKEOFF.md` (novo).
|
||||
|
||||
1. Instalar com `uv pip install --python clipper/.venv/Scripts/python.exe` e **fixar versões** no
|
||||
`requirements.txt`: `mediapipe==1.2.3`, `onnxruntime==1.32.0` (o MediaPipe traz `opencv-contrib-python` e
|
||||
`numpy`; **não** instalar `opencv-python-headless` junto — conflito de `cv2`). Conferir `import` e a API
|
||||
(`mediapipe.tasks.python.vision.FaceLandmarker`, `cv2.FaceDetectorYN`).
|
||||
2. Baixar os modelos para `data/clipper/models/` e registrar URL imutável + sha256 em `clipper/models.lock.json`:
|
||||
YuNet (variante compatível com o OpenCV instalado — 5.x pode exigir a `2026may` de entrada dinâmica),
|
||||
`face_landmarker.task` (float16/1), e os `.onnx` do OpenSeeFace (modelo 3 + detector) do commit fixado.
|
||||
`setup.ps1` passo 6b baixa e confere o sha256.
|
||||
3. Bancada com a sessão 3 (skipnho, 2937 s, 99 blocos `.ts` em `data/clipper/sessions/3/`; câmera achada pela IA
|
||||
em `cam_json`: x 0,014 y 0,532 w 0,183 h 0,395):
|
||||
- **Achar a câmera:** 12 quadros espalhados; YuNet no quadro inteiro → taxa de rosto, posição estável?
|
||||
IoU do retângulo estimado com o da IA.
|
||||
- **Rastreio:** 3 trechos de 30 s (um calmo, um com o lag/mortes que geraram corte, um qualquer) a 6 qps no
|
||||
recorte da câmera: MediaPipe × OpenSeeFace → % de quadros com rosto, tempo por quadro (CPU), e se os
|
||||
blendshapes sobem nos momentos de reação (comparar com `clips` existentes da sessão 3).
|
||||
- Se houver outra sessão/canal disponível, repetir a câmera nela.
|
||||
4. Escrever `doc/FACE_BAKEOFF.md` com números, quadros de exemplo (salvar em `output/face-bench/`) e a
|
||||
**decisão**: MediaPipe confirmado ou plano B. Critério: rosto em ≥ 85 % dos quadros com o streamer presente e
|
||||
≤ 15 ms/quadro na CPU.
|
||||
|
||||
### Fase 1 — Agente B "sinal" (lógica pura, sem dependências)
|
||||
|
||||
Dono de: `clipper/app/reaction.py` (novo), `clipper/tests/test_reaction.py` (novo). Python puro (como
|
||||
`scoring.py`), testável sem modelo.
|
||||
|
||||
- `FaceSample` (por quadro): `t`, `present`, `cx`, `cy`, `size`, `blend` (dict nome→0..1).
|
||||
- `per_second(samples, duration)` → lista de `FaceSecond` (`present` 0..1, `cx`, `cy`, `size`, `smile`, `jaw`,
|
||||
`surprise`, `frown`, `blink`, `motion`), com médias/máximos por segundo; `motion` = deslocamento do centro
|
||||
normalizado pelo tamanho do rosto.
|
||||
- `reaction_signal(seconds, baseline_s=180)` → intensidade por segundo **relativa ao neutro do próprio
|
||||
streamer**: z robusto (mediana + MAD) de cada canal sobre a janela recente só com segundos com rosto; o sinal é o
|
||||
máximo ponderado dos canais; `None` sem rosto.
|
||||
- `label(second)` → `risada` (smile+jaw), `grito` (jaw sem smile), `susto` (surprise+motion), `raiva` (frown),
|
||||
`choque` (surprise sem motion), `neutro`.
|
||||
- `reaction_moments(...)`/`summarize(window)` → picos com rótulo, início da reação (onset) e texto curto para o
|
||||
juiz ("risada forte em 12 s, susto em 15 s").
|
||||
- `locate_cam(detections_per_frame, frame_w, frame_h)` → agrupa rostos por posição; câmera = grupo presente em
|
||||
≥ 50 % dos quadros e estável; devolve `{hasWebcam, cam, faceRect, confidence, fullFrame}`. Rosto > 40 % da
|
||||
altura = câmera em tela cheia (`fullFrame`). Retângulo: bordas persistentes da moldura quando dadas (média de
|
||||
gradiente entre quadros, passada como parâmetro opcional), senão rosto expandido (≈3,2× largura, 3,6× altura,
|
||||
deslocado para baixo), recortado em 0..1.
|
||||
- Testes: séries sintéticas (neutro com ruído → sem pico; risada → pico `risada` com onset certo; streamer com
|
||||
"neutro sorridente" não vira falso positivo; câmera estável × rosto que aparece no jogo/cutscene; tela cheia).
|
||||
|
||||
### Fase 2 — Agente C "integração" (depois de A e B)
|
||||
|
||||
Arquivos: `clipper/app/face.py` (novo: backends YuNet/MediaPipe/OpenSeeFace atrás de uma interface, download
|
||||
lazy com sha256), e **ganchos pequenos** em `db.py`, `worker.py`, `intel.py`, `scoring.py`, `judge.py`,
|
||||
`main.py`, `config.py`; painel só `panel/src/lib/clipper.ts` (`ALLOWED`) + um interruptor nas opções do juiz +
|
||||
reação no cartão do corte. **Reler cada arquivo logo antes de editar** (o agente do editor mexe neles).
|
||||
|
||||
1. **Banco:** próxima migração (ler `user_version` atual; hoje 3) — tabela `face_track(session_id, idx, status,
|
||||
data_json, error, PRIMARY KEY(session_id, idx))`. `cam_json` ganha `source` (`yunet`|`ai`|`manual`).
|
||||
2. **Câmera:** `Intel.detect_cam` tenta primeiro o local (YuNet + `reaction.locate_cam` em 8–12 quadros); a IA
|
||||
só entra se o local não achar rosto ou o usuário pedir. Opção `camDetect` continua valendo; detecção local não
|
||||
exige `vision`/juiz ligados.
|
||||
3. **Laço `_face_loop`** (thread própria, não atrasa a transcrição): blocos com câmera conhecida e sem
|
||||
`face_track` → FFmpeg recorta a câmera (+10 % de margem), escala para ~384 px, 6 qps, `rawvideo rgb24` por
|
||||
pipe → MediaPipe em modo VIDEO (timestamps crescentes) → `reaction.per_second` → grava. Sem câmera →
|
||||
`status='no_cam'`. Câmera alterada (detect/PUT de layout) → apaga o `face_track` da sessão e refaz.
|
||||
Opção nova `faceTrack` (padrão `true`) em `OPTION_DEFAULTS` e no `PUT /v1/judge`.
|
||||
4. **Pontuação:** `find_moments` recebe `face` opcional:
|
||||
- momentos de chat/áudio ganham `reasons.face` (pico, rótulo, onset) e bônus limitado na nota;
|
||||
- fonte nova `face` só com **apoio** (áudio z ≥ 1 ou chat acima do normal no mesmo trecho) e z ≥
|
||||
`face_threshold` (padrão 3,0) — rosto sozinho não vira corte;
|
||||
- `find_new_clips` espera o rosto do trecho quando há câmera e `faceTrack` ligado (no máximo 2 blocos de atraso).
|
||||
- Testes de regressão em `test_scoring.py` (sem rosto = comportamento atual idêntico).
|
||||
5. **Juiz:** o prompt do analista ganha a linha "Rosto do streamer: …" de `reaction.summarize` na janela do corte.
|
||||
6. **API:** `GET /v1/sessions/{id}/face?from=&to=` (série por segundo; o editor usa `cx/cy/size` para
|
||||
reenquadrar) e `POST /v1/sessions/{id}/face/reset`. Atualizar `ALLOWED` e timeout no `panel/src/lib/clipper.ts`.
|
||||
7. **README do Clipador** (seção nova "Rastreio de reação") e `.env.example` se houver variável nova.
|
||||
8. **Validação na sessão 3** (cópia do banco em `output/face-bench/`, nunca o banco vivo enquanto o serviço do
|
||||
usuário roda): câmera local × IA, % de rosto, tempo por bloco (meta ≤ 5 s CPU por bloco de 30 s), 10 maiores
|
||||
reações com rótulo e tempo, e quais coincidem com cortes existentes. `pnpm test:clipper` e
|
||||
`npx tsc --noEmit -p panel` verdes.
|
||||
|
||||
### Fase 3 — revisão e manutenção
|
||||
|
||||
- D: `ecc:python-reviewer` nos arquivos novos/alterados do Clipador; corrigir CRÍTICO/ALTO.
|
||||
- E: `cenaforge-skill-updater` com o que mudou, arquivos e evidência.
|
||||
- O serviço do usuário só pega o código novo após reiniciar o `start.bat` — **pedir ao usuário**, não reiniciar.
|
||||
|
||||
## Regras para todos os agentes
|
||||
|
||||
- Identificadores em inglês; comentários, mensagens e docs em português.
|
||||
- Portas só na faixa 4500–4599. Não iniciar/encerrar o painel nem o serviço do Clipador do usuário.
|
||||
- Subprocesso sem shell, argumentos em lista. Nada de rede na thread do chat.
|
||||
- Nada de peso com licença não comercial/GPL. Modelos com URL imutável + sha256.
|
||||
- Não publicar nada em rede social.
|
||||
|
||||
## Riscos
|
||||
|
||||
- OpenCV 5 × modelo YuNet antigo (fixo) → usar a variante dinâmica; a bancada confirma.
|
||||
- Webcam muito pequena (rosto < 40 px no recorte) → MediaPipe perde; plano B OpenSeeFace ou ampliar o recorte.
|
||||
- Rosto no jogo (cutscene, outro jogador com câmera) → `locate_cam` exige posição estável em ≥ 50 % dos quadros.
|
||||
- Streamer sai da câmera → `present` 0, sinal `None`, nunca vira pico.
|
||||
- Conflito com o agente do editor nos mesmos arquivos → ganchos mínimos, reler antes de editar, migração com o
|
||||
próximo número livre na hora da edição.
|
||||
@@ -0,0 +1,397 @@
|
||||
# Prompt de implementação — prova de conceito de vídeo em Godot
|
||||
|
||||
> Copie este documento para `doc/PROMPT_TESTE_VIDEO_GODOT.md` na pasta do projeto e peça ao Claude Code: **“Leia esse documento e implemente o teste de vídeo de ponta a ponta. Execute e valide o resultado quando o ambiente permitir.”**
|
||||
>
|
||||
> Este arquivo é uma especificação para implementação. Não significa que o projeto ou o vídeo já tenham sido implementados ou testados.
|
||||
|
||||
## 1. Sua missão
|
||||
|
||||
Atue como desenvolvedor responsável por implementar e executar uma prova de conceito local de produção de vídeos narrativos com Godot. Não entregue apenas arquitetura ou pseudocódigo. Crie os arquivos, execute os comandos disponíveis, corrija erros e entregue um MP4 reproduzível, se houver Godot e FFmpeg utilizáveis neste computador.
|
||||
|
||||
O objetivo imediato é provar que uma cena descrita por dados pode ser montada, animada e renderizada automaticamente. **O vídeo vem antes do painel.**
|
||||
|
||||
Não implementar agora Next.js, API Fastify, banco, Redis, autenticação, multiempresa, Electron, integração Instagram, integração Meshy, agentes ou skills. Essas ideias estão documentadas no final para evolução posterior. Não deixar esse futuro bloquear a prova de conceito.
|
||||
|
||||
Nome de trabalho opcional: CenaForge. Esse nome não foi aprovado definitivamente nem teve disponibilidade de marca/domínio verificada. Trabalhe na pasta atual fornecida pelo usuário; não crie uma pasta extra com esse nome se já estiver na raiz do projeto.
|
||||
|
||||
## 2. Contexto e decisões já tomadas
|
||||
|
||||
- O produto futuro produzirá histórias animadas, uma história por vez, divididas em episódios com decisões do público.
|
||||
- A direção visual inicial mistura personagens e objetos próximos em 3D com fachadas distantes em imagens planas.
|
||||
- Godot será o motor de cena neste teste.
|
||||
- O primeiro plano mostra um motoboy andando de moto numa rua, observado por uma câmera em terceira pessoa, atrás e acima dele.
|
||||
- A rua não deve ter nome de cidade, clube, empresa ou referências geográficas que restrinjam o público. Usar um bairro fictício de aparência brasileira.
|
||||
- O usuário já tem Applio e outros projetos de narração no PC. **Não instalar, modificar nem integrar esses projetos agora.**
|
||||
- A prova pode funcionar sem voz. Se houver um áudio que o usuário fornecer explicitamente, aceitar esse arquivo como entrada opcional.
|
||||
- Não é necessário modelo do Meshy para começar. Construir modelos provisórios com primitivas é parte da implementação, e não motivo para interromper o trabalho.
|
||||
- A aparência deve ser simples, mas legível: moto identificável, entregador com capacete e caixa de entrega, rua, calçadas, casas e horizonte.
|
||||
|
||||
## 3. Resultado esperado
|
||||
|
||||
Entregar uma cena vertical de **12 segundos a 30 FPS**:
|
||||
|
||||
1. Entre 0 e 1 segundo, câmera já enquadra a moto e o entregador, ambos visíveis.
|
||||
2. Entre 1 e 9 segundos, a moto avança pela rua; a câmera acompanha por trás, com movimento estável.
|
||||
3. Entre 9 e 10 segundos, a moto desacelera suavemente até parar.
|
||||
4. Entre 10 e 12 segundos, surge uma chamada simples: “Uma entrega inesperada.” e duas opções visuais: “A — Aceitar” e “B — Continuar a rota”.
|
||||
|
||||
Essa chamada demonstra o formato futuro; **não implementar votação real**. O movimento e a mudança de enquadramento são o núcleo do teste.
|
||||
|
||||
Saídas:
|
||||
|
||||
- Prévia em 540 × 960, 30 FPS, MP4.
|
||||
- Perfil final configurável em 1080 × 1920, 30 FPS. Renderizar primeiro a prévia e só depois tentar o perfil final.
|
||||
- Arquivo de cena JSON utilizado em cada execução.
|
||||
- Relatório do render com versões das ferramentas, tempo gasto, resolução, quadros produzidos e resultado de verificação.
|
||||
- Imagens de conferência de momentos diferentes do vídeo.
|
||||
|
||||
Não prometer qualidade fotorrealista ou desempenho específico. O teste avalia a lógica e a viabilidade do fluxo.
|
||||
|
||||
## 4. Inspeção do ambiente antes de implementar
|
||||
|
||||
Leia instruções locais e preserve arquivos existentes. Descubra:
|
||||
|
||||
1. Sistema operacional e shell disponíveis.
|
||||
2. Caminho e versão da Godot, usando `--version` e `--help`.
|
||||
3. Caminhos de FFmpeg e FFprobe, consultando as versões.
|
||||
4. Node.js e gerenciador de pacotes disponíveis, apenas para um lançador opcional.
|
||||
5. Se há sessão gráfica e acesso à GPU para renderizar.
|
||||
6. Espaço disponível no diretório de saída.
|
||||
|
||||
Alvo principal: Windows, mas manter os caminhos e comandos compatíveis com Linux quando possível. Não presumir que um executável do Windows pode ser chamado como binário Linux, nem depender de WSL para renderização.
|
||||
|
||||
Preferir uma versão estável da Godot 4 instalada, com GDScript. Não exigir a edição .NET. Consultar a documentação correspondente à versão instalada, fixar a versão testada no README e não atualizar instalações existentes sem necessidade.
|
||||
|
||||
Se um executável não estiver no PATH, aceitar variáveis `GODOT_BIN`, `FFMPEG_BIN` e `FFPROBE_BIN`. Não procurar indiscriminadamente por arquivos pessoais. Não baixar programas de fontes não oficiais.
|
||||
|
||||
Se o ambiente não permitir execução gráfica ou faltar dependência, continuar criando o projeto e executar as verificações possíveis. Informar exatamente o que não foi executado; nunca apresentar um arquivo vazio ou uma simulação como render real.
|
||||
|
||||
## 5. Estrutura mínima de arquivos
|
||||
|
||||
Criar na raiz do projeto:
|
||||
|
||||
| Caminho | Finalidade |
|
||||
|---|---|
|
||||
| `README.md` | Instalação, comandos, resultado e limitações |
|
||||
| `doc/PROMPT_TESTE_VIDEO_GODOT.md` | Esta especificação |
|
||||
| `doc/TEST_RESULT.md` | Evidências reais do teste e próximos passos |
|
||||
| `godot/project.godot` | Projeto do motor |
|
||||
| `godot/scenes/main.tscn` | Cena principal |
|
||||
| `godot/scripts/main.gd` | Inicialização e orquestração |
|
||||
| `godot/scripts/scene_config.gd` | Leitura e validação do JSON |
|
||||
| `godot/scripts/street_builder.gd` | Rua, casas e cenário |
|
||||
| `godot/scripts/rider_builder.gd` | Moto e entregador provisórios |
|
||||
| `godot/scripts/timeline_controller.gd` | Tempo, deslocamento e eventos |
|
||||
| `godot/scripts/camera_controller.gd` | Enquadramento por tempo |
|
||||
| `godot/scripts/overlay_controller.gd` | Textos finais |
|
||||
| `godot/assets/backgrounds/` | Imagens de fachadas/fundo |
|
||||
| `godot/assets/models/` | GLBs opcionais futuros |
|
||||
| `config/demo-street.json` | Cena de teste padrão |
|
||||
| `config/demo-street-variant.json` | Segunda configuração para provar reutilização |
|
||||
| `scripts/` | Comandos de importação, render e conversão |
|
||||
| `output/` | Execuções locais, ignoradas pelo Git |
|
||||
|
||||
Separar responsabilidades sem criar uma arquitetura genérica excessiva. Se juntar dois scripts tornar a prova mais simples, isso é aceitável, desde que a configuração continue independente do motor.
|
||||
|
||||
Incluir `.gitignore` para `.godot`, `node_modules`, resultados de render, arquivos temporários, segredos e arquivos locais de áudio. Não ignorar cenas, scripts ou metadados de importação que a versão utilizada exija versionar.
|
||||
|
||||
## 6. Configuração de cena
|
||||
|
||||
Criar um contrato JSON pequeno, com versão. Este é o formato proposto; implementá-lo de verdade, adaptando nomes somente se o README e os exemplos forem atualizados juntos:
|
||||
|
||||
```json
|
||||
{
|
||||
"schemaVersion": 1,
|
||||
"id": "demo-street",
|
||||
"seed": 42,
|
||||
"video": {
|
||||
"width": 540,
|
||||
"height": 960,
|
||||
"fps": 30,
|
||||
"durationSeconds": 12
|
||||
},
|
||||
"world": {
|
||||
"streetLengthMeters": 100,
|
||||
"roadWidthMeters": 8,
|
||||
"nearHousesPerSide": 6,
|
||||
"backgroundMode": "cards",
|
||||
"lightingPreset": "warm_day"
|
||||
},
|
||||
"rider": {
|
||||
"assetId": "placeholder-rider",
|
||||
"bikeColor": "#D95437",
|
||||
"startPosition": [0, 0, 0],
|
||||
"travelMeters": 32
|
||||
},
|
||||
"motion": {
|
||||
"startSeconds": 1,
|
||||
"brakeStartSeconds": 9,
|
||||
"stopSeconds": 10
|
||||
},
|
||||
"camera": {
|
||||
"preset": "third_person_follow",
|
||||
"offset": [0, 3.2, 6.5],
|
||||
"lookAtOffset": [0, 1.2, -2],
|
||||
"fovDegrees": 55
|
||||
},
|
||||
"overlay": {
|
||||
"startSeconds": 10,
|
||||
"title": "Uma entrega inesperada.",
|
||||
"choiceA": "A — Aceitar",
|
||||
"choiceB": "B — Continuar a rota"
|
||||
},
|
||||
"audio": {
|
||||
"enabled": false,
|
||||
"file": null,
|
||||
"offsetSeconds": 0
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Convenção do nosso projeto: Y é altura, a moto percorre o eixo -Z e a câmera está atrás em +Z. Isso é uma decisão desta cena, não uma suposição sobre a orientação de todo modelo importado. Conversões de GLB serão tratadas num nó adaptador.
|
||||
|
||||
Validar campos obrigatórios, tipos, números finitos, cores, intervalos de tempo e limites razoáveis antes de começar. Exigir que início < frenagem < parada ≤ duração e que FPS e resolução sejam positivos. Rejeitar versões desconhecidas e configurações inválidas com mensagem útil. Não aceitar código GDScript ou comandos shell dentro do JSON.
|
||||
|
||||
Argumentos próprios da aplicação devem ficar após `--` na linha de comando da Godot e ser lidos via `OS.get_cmdline_user_args()`. Expor no mínimo `--config` e, se necessário, um diretório de trabalho/resultado. Resolver caminhos relativos contra uma base documentada, nunca conforme um diretório de execução imprevisível.
|
||||
|
||||
## 7. Cenário e qualidade visual
|
||||
|
||||
### Rua
|
||||
|
||||
- Piso cinza com faixas discretas e calçadas em ambos os lados.
|
||||
- Rua comprida o bastante para o percurso inteiro, sem revelar o fim do cenário.
|
||||
- Casas próximas com volumes simples, telhados, portas e janelas que conservem perspectiva ao passar.
|
||||
- Variação determinística de cor e altura baseada na seed.
|
||||
- Alguns postes ou elementos repetidos para evidenciar deslocamento e profundidade.
|
||||
- Não criar cidade aberta, tráfego, pedestres, navegação ou colisão física complexa.
|
||||
|
||||
### Moto e personagem
|
||||
|
||||
- Construir moto com duas rodas, quadro, banco, guidão e caixa de entrega.
|
||||
- Entregador sentado, com tronco, braços, pernas e capacete construídos de primitivas.
|
||||
- Ajustar as mãos para perto do guidão e os pés para perto dos apoios.
|
||||
- Rodas devem girar de acordo com distância percorrida e raio; o motor não pode deslizar a moto com rodas paradas durante todo o plano.
|
||||
- Inclinação e vibração, se usadas, devem ser sutis e determinísticas.
|
||||
- É aceitável começar sem esqueleto e sem animação facial. Não exigir Mixamo, Meshy ou download pago.
|
||||
|
||||
### Casas distantes como imagens
|
||||
|
||||
- Criar ao menos uma camada distante com fachadas em textura sobre planos ou Sprite3D com billboard desabilitado.
|
||||
- Gerar texturas simples localmente ou usar imagens de licença adequada já disponíveis; não depender de busca de assets para finalizar.
|
||||
- Manter os planos orientados como fachadas fixas. Não fazer casas girarem para encarar a câmera.
|
||||
- Posicionar fora do trecho pelo qual a moto passa de perto durante os 12 segundos.
|
||||
- Evitar transparência excessiva, sobreposição e bordas recortadas chamativas.
|
||||
- Não implementar troca dinâmica de LOD neste teste. Escolher 3D ou plano previamente por localização e enquadramento.
|
||||
- Se houver comparação de desempenho, medir. Não afirmar ganho apenas porque o objeto é um sprite.
|
||||
|
||||
### Luz e câmera
|
||||
|
||||
- Usar iluminação simples, ambiente coerente e sombras nos objetos próximos, conforme suporte do renderizador.
|
||||
- Começar com um perfil de render leve; documentar se foi usado Compatibility, Mobile ou Forward+ e por quê.
|
||||
- Não exigir volumetria, iluminação global pesada ou texturas grandes.
|
||||
- A câmera acompanha o protagonista sem entrar em casas, atravessar o chão ou cortar o capacete.
|
||||
- Preservar uma área inferior para as opções e margens laterais confortáveis na composição vertical.
|
||||
- HUD/textos em CanvasLayer ou estrutura equivalente; fonte legível e contraste adequado.
|
||||
|
||||
## 8. Tempo determinístico e movimento
|
||||
|
||||
O estado visual precisa ser controlado pelo tempo da cena, não pelo relógio real do sistema.
|
||||
|
||||
Implementar uma função central equivalente a `evaluate_at_time(t)` que calcule posição da moto, rotação das rodas, câmera e visibilidade do overlay. Em render, usar o relógio de frames controlado e verificar a correspondência com FPS. Em prévia, permitir avanço normal e reinício.
|
||||
|
||||
Não basear a posição em chamadas de tempo de parede. Evitar física de veículo para esse plano: o movimento é cinematográfico e pode ser calculado diretamente.
|
||||
|
||||
Definir uma curva de distância com aceleração e frenagem contínuas. A moto começa na posição configurada, atinge exatamente `travelMeters` no instante de parada e permanece ali. Não usar uma interpolação que provoque salto entre fases. A roda gira pela distância acumulada, usando ângulo = distância / raio, com eixo e sinal adequados ao modelo.
|
||||
|
||||
O estado deve ser igual ao avaliar o mesmo instante em duas execuções na mesma configuração. Não exigir identidade binária de pixels entre GPUs/renderizadores distintos.
|
||||
|
||||
Configuração alternativa: mudar cor da moto, distância, câmera e texto final apenas no JSON. Renderizar uma segunda prévia curta ou completa para provar que a cena não está inteiramente fixada no código.
|
||||
|
||||
## 9. Renderização e exportação
|
||||
|
||||
Godot oferece Movie Maker para renderização offline. Usar sua saída de sequência PNG e WAV quando disponível na versão instalada, e converter para MP4 com FFmpeg. Confirmar flags e nomes de arquivos reais antes de automatizar. Não supor que gravar a janela ou usar OBS é necessário. A integração de captura deve seguir a documentação oficial indicada nas referências.
|
||||
|
||||
Separar preparação/importação de renderização. O modo headless pode servir para tarefas sem imagem; **não presumir que ele oferece renderização 3D válida**. O render precisa de um backend gráfico funcional. Um comando pode abrir uma janela e ainda ser totalmente automatizado.
|
||||
|
||||
Modelo conceitual de chamada, a adaptar e testar com o executável instalado:
|
||||
|
||||
```text
|
||||
godot --path godot --write-movie <saida>/frame.png --fixed-fps 30 -- --config <cena.json>
|
||||
```
|
||||
|
||||
Usar encerramento normal da cena após o número esperado de quadros; não matar o processo no sucesso. Verificar a relação entre inicialização, primeiro frame e último frame para não incluir telas vazias. Usar timeout somente como proteção contra travamento.
|
||||
|
||||
Uma sequência de 12 segundos a 30 FPS deve produzir 360 quadros úteis. Confirmar o padrão numérico efetivo, o índice inicial e a duração final. Não confiar em uma mensagem de log como única prova.
|
||||
|
||||
Exemplo de conversão, somente depois de descobrir o padrão real dos PNGs:
|
||||
|
||||
```text
|
||||
ffmpeg -framerate 30 -start_number <indice_inicial> -i <padrao_real_dos_pngs> -c:v libx264 -pix_fmt yuv420p -movflags +faststart -an <saida.mp4>
|
||||
```
|
||||
|
||||
O exemplo sem áudio é suficiente para esta fase. Se `libx264` não estiver disponível, diagnosticar os encoders instalados e documentar a alternativa; não prometer uma opção inexistente.
|
||||
|
||||
Criar pastas de execução únicas, sem sobrescrever o último sucesso. Gravar `scene.json`, `render.log`, `report.json`, o MP4 e frames de inspeção dentro da pasta. Não servir credenciais, caminhos pessoais ou logs inteiros para nenhum serviço externo.
|
||||
|
||||
## 10. Áudio opcional e Applio
|
||||
|
||||
O áudio local será integrado depois. Não instalar TTS, não baixar modelos de voz, não configurar Applio e não assumir que ele oferece uma API específica.
|
||||
|
||||
Se implementar a entrada opcional agora:
|
||||
|
||||
- Aceitar somente arquivo indicado pelo usuário e validar sua existência.
|
||||
- Obter duração via FFprobe.
|
||||
- Compor áudio no FFmpeg, fora da Godot, para reduzir complexidade.
|
||||
- Respeitar `offsetSeconds`, preencher silêncio quando necessário e limitar a saída à duração da cena.
|
||||
- Se o áudio for maior, emitir um aviso claro de corte ou pedir ajuste de duração; não mudar a duração silenciosamente.
|
||||
- Não usar `-shortest` de modo a truncar o vídeo quando o áudio acabar cedo.
|
||||
- Codificar AAC quando adequado ao MP4 e preservar o arquivo de entrada.
|
||||
|
||||
Sem arquivo fornecido, o resultado é um vídeo silencioso válido. Não gerar narração falsa nem afirmar integração com o Applio.
|
||||
|
||||
## 11. Lançador local e TypeScript
|
||||
|
||||
Primeiro faça a Godot gerar a cena e o render. Depois, se Node já estiver disponível, crie um lançador TypeScript enxuto para unificar o comando. Essa camada é conveniente, mas não deve virar backend ou painel nesta fase.
|
||||
|
||||
Comandos desejados, que só devem aparecer no README se realmente implementados:
|
||||
|
||||
- `pnpm doctor`: checa executáveis, versões e diretórios.
|
||||
- `pnpm preview`: abre a cena padrão na Godot.
|
||||
- `pnpm render -- --config config/demo-street.json --profile preview`: gera a prévia.
|
||||
- `pnpm render -- --config config/demo-street.json --profile final`: gera o perfil final.
|
||||
- `pnpm verify -- --file <arquivo.mp4>`: verifica propriedades do vídeo.
|
||||
|
||||
Pode usar npm se já for o padrão do repositório. Fixar dependências e manter lockfile. Preferir TypeScript com `tsx` para os scripts se isso reduzir configuração.
|
||||
|
||||
O lançador deve usar criação de processo com lista de argumentos, sem concatenar comandos a partir do JSON e sem `shell: true` desnecessário. Suportar espaços nos caminhos. Capturar stdout/stderr, devolver exit code correto e distinguir renderização de conversão. Um processo de FFmpeg com erro não pode resultar em status de sucesso.
|
||||
|
||||
Executar só um render por vez. Não implementar fila distribuída. Se o usuário cancelar, encerrar subprocessos e marcar a execução como incompleta, preservando o último render válido.
|
||||
|
||||
## 12. Critérios de aceite
|
||||
|
||||
### Funcionais
|
||||
|
||||
- [ ] Projeto abre na Godot sem erros de parsing.
|
||||
- [ ] A configuração externa é lida e validada.
|
||||
- [ ] A cena contém moto, entregador, rua, casas 3D e fundo em planos.
|
||||
- [ ] Câmera acompanha por trás durante o deslocamento.
|
||||
- [ ] Moto avança e desacelera sem saltos visíveis.
|
||||
- [ ] Rodas giram enquanto há deslocamento.
|
||||
- [ ] Overlay aparece no período configurado.
|
||||
- [ ] A prévia gera MP4 real, reproduzível e não vazio.
|
||||
- [ ] FFprobe confirma codec, dimensões, FPS e duração com tolerância de até um frame para a duração planejada.
|
||||
- [ ] Uma segunda configuração muda a cena sem editar scripts.
|
||||
- [ ] O projeto funciona sem API paga, Meshy, Applio e Instagram.
|
||||
|
||||
### Verificação visual
|
||||
|
||||
Extrair e examinar quadros próximos de 0,5 s, 4 s, 8 s e 11 s. Abrir também o vídeo quando houver ferramenta disponível. Conferir:
|
||||
|
||||
- Nada de vídeo preto, câmera dentro de geometria ou texturas ausentes.
|
||||
- Personagem reconhecível e devidamente apoiado na moto.
|
||||
- Mudança de perspectiva dos objetos próximos.
|
||||
- Fundo sem rotação artificial nem aparecimento de bordas dos planos.
|
||||
- Sem z-fighting importante ou recortes nos textos.
|
||||
- Overlay legível em tamanho reduzido.
|
||||
- Luz e cores consistentes durante a tomada.
|
||||
|
||||
Se não houver meio de inspecionar imagens, declarar “validação visual pendente”, mesmo que o FFprobe passe.
|
||||
|
||||
### Testes pequenos e úteis
|
||||
|
||||
Testar rejeição de JSON inválido, intervalos de tempo impossíveis e arquivo de áudio inexistente. Testar posição inicial/final e estabilidade da avaliação temporal. Verificar falhas de subprocessos no lançador, se ele existir. Não construir uma suíte enorme para funções triviais.
|
||||
|
||||
Não fazer promessas de duração de render antes de medir. Registrar resolução, renderizador, versão da Godot, hardware disponível e tempo total observado.
|
||||
|
||||
## 13. Sequência de implementação
|
||||
|
||||
1. Inspecionar ambiente e registrar versões.
|
||||
2. Criar projeto mínimo Godot com piso, luz, câmera e um objeto visível.
|
||||
3. Criar rua, moto e entregador provisórios.
|
||||
4. Implementar JSON e controle temporal.
|
||||
5. Acrescentar casas próximas e fachadas distantes.
|
||||
6. Renderizar uma amostra de 2 segundos para validar captura e conversão.
|
||||
7. Gerar a prévia completa de 12 segundos.
|
||||
8. Inspecionar quadros e corrigir enquadramento/movimento.
|
||||
9. Testar a variante JSON.
|
||||
10. Adicionar lançador TypeScript se isso for viável sem expandir o escopo.
|
||||
11. Tentar perfil final e registrar resultado, sem bloquear a entrega da prévia se faltar recurso.
|
||||
12. Atualizar README e `doc/TEST_RESULT.md` com evidências reais.
|
||||
|
||||
Quando o vídeo estiver funcionando, parar e entregar. Não iniciar o painel automaticamente.
|
||||
|
||||
## 14. Como entregar ao usuário
|
||||
|
||||
Informar de forma objetiva:
|
||||
|
||||
1. O que foi implementado.
|
||||
2. Caminho do MP4 e da configuração.
|
||||
3. Comando exato para reproduzir o render.
|
||||
4. Quais testes foram executados e resultados.
|
||||
5. Quais partes continuam provisórias.
|
||||
6. Dependências faltantes, se houver.
|
||||
|
||||
Não dizer “funciona” apenas porque o código foi escrito. Distinguir código criado, validação estática, projeto iniciado, MP4 gerado e inspeção visual.
|
||||
|
||||
## 15. Evolução futura — contexto, não tarefas desta entrega
|
||||
|
||||
### Painel e execução
|
||||
|
||||
Depois de validar o vídeo: painel Next.js + React + TypeScript + Tailwind, API Node/TypeScript (Fastify é a preferência inicial), contratos de cena compartilhados e executor local que chama Godot/FFmpeg. O navegador não deve tentar abrir executáveis arbitrários diretamente. Na primeira versão, tudo poderá rodar como projeto local, sem instalador.
|
||||
|
||||
O painel futuramente terá projetos, histórias, episódios, catálogo, planejamento de cenas, prévia, render e histórico. O estado de jobs deve persistir antes de introduzir agendamento. Banco e fila serão escolhidos conforme escala; MySQL e Redis são opções conhecidas do usuário, não requisitos desta prova.
|
||||
|
||||
Electron, instalador, distribuição comercial, tenancy e cobrança são posteriores. Não adicioná-los agora. Manter apenas limites claros entre configuração, renderizador e interface.
|
||||
|
||||
### IA e catálogo
|
||||
|
||||
O futuro planejador recebe história e catálogo de recursos e retorna dados de cena validados. Não recebe autoridade irrestrita para gerar e executar scripts arbitrários. Um adaptador de IA pode usar API ou integração oficialmente suportada por ferramentas locais; validar autenticação, limites e condições de cada fornecedor antes de prometer conexão por CLI.
|
||||
|
||||
O catálogo acumula personagens, objetos, cenários, animações e planos reutilizáveis. Cada recurso deverá ter ID, versão, caminho, tipo, escala, orientação, licença/origem e capacidades. Uma porta estática é diferente de uma porta que abre; um personagem com animação de andar não está automaticamente preparado para pilotar moto.
|
||||
|
||||
Identificar recursos disponíveis, que precisam de adaptação e ausentes. Fixar versões por episódio. Meshy poderá produzir GLBs no futuro; testar malha, materiais, esqueleto e animações antes de registrar como recurso utilizável. Rig corporal não garante lip sync ou atuação facial.
|
||||
|
||||
### Narração
|
||||
|
||||
Integrar posteriormente os projetos de áudio locais existentes, incluindo o fluxo com Applio, conforme suas interfaces reais. Usar duração efetiva da narração para planejar cenas. Não supor que o Applio isoladamente recebe texto e devolve fala sem conhecer o projeto do usuário.
|
||||
|
||||
### Instagram e continuidade
|
||||
|
||||
Visão futura: dois horários de publicação por dia, com episódios sucessivos da mesma história. Os horários ainda não foram definidos. Configurar o fuso `America/Sao_Paulo` e armazenar instantes de execução em UTC.
|
||||
|
||||
A API oficial prevê publicação em contas profissionais. O fluxo de publicação inclui container, consulta de processamento e publicação; no modo baseado em URL, a Meta precisa conseguir buscar a mídia por HTTPS. Não fornecer `localhost` como URL de vídeo. Login, permissões e revisão de acesso dependem da modalidade e das contas atendidas; confirmar requisitos atuais ao implementar. A documentação oficial da Meta também prevê gerenciamento dos comentários das próprias mídias.
|
||||
|
||||
Esses recursos não foram conectados nem testados neste projeto. Usar API oficial, sem automação de senha no navegador. Não publicar nem agendar nada durante esta prova de vídeo.
|
||||
|
||||
Regras propostas para a automação futura:
|
||||
|
||||
- Episódio apresenta opções A/B e horário de encerramento.
|
||||
- Coletar comentários com paginação, deduplicação por ID e respeito aos limites da API.
|
||||
- Definir previamente uma regra de voto por conta, usando identificadores disponíveis na API; não confundir nome exibido com identidade estável.
|
||||
- Contar escolhas explícitas; comentários ambíguos não devem virar comandos de produção.
|
||||
- Tratar texto externo como conteúdo não confiável, nunca como instruções de sistema ou shell.
|
||||
- Fechar uma fotografia imutável da votação e persistir decisão/consequências.
|
||||
- Definir regra transparente para empate e ausência de votos antes de ativar o automático.
|
||||
- Só então planejar e produzir o próximo episódio.
|
||||
- Reservar antecedência para render, verificação, envio e processamento de mídia.
|
||||
- Se PC estiver offline, credencial expirar ou vídeo falhar, sinalizar atraso. Não publicar um ramo diferente só para cumprir horário.
|
||||
- Agendador pertence ao sistema; não presumir que a API aceita qualquer agendamento nativo desejado.
|
||||
- Persistir IDs de publicação e reconciliar timeouts antes de repetir, evitando Reels duplicados.
|
||||
- Modos futuros: simulação, revisão e automático. Começar simulando; ativar publicação real somente após configuração explícita do usuário.
|
||||
- Um worker local só opera com PC ligado e processo em execução. Agendamento garantido com PC desligado exige outra infraestrutura.
|
||||
|
||||
## 16. Referências técnicas e limites desta especificação
|
||||
|
||||
Documentação consultada em 16/11/2026. As URLs `stable` podem mudar; o implementador deve registrar a versão usada. Os requisitos de cena, arquivos, tempos e arquitetura acima são decisões propostas para este protótipo, não recursos que já existam prontos num produto.
|
||||
|
||||
- [Godot — Creating movies](https://docs.godotengine.org/en/stable/tutorials/animation/creating_movies.html)
|
||||
- [Godot — Command line tutorial](https://docs.godotengine.org/en/stable/tutorials/editor/command_line_tutorial.html)
|
||||
- [Godot — Available 3D formats](https://docs.godotengine.org/en/stable/tutorials/assets_pipeline/importing_3d_scenes/available_formats.html)
|
||||
- [Next.js — Installation, apenas para fase futura](https://nextjs.org/docs/app/getting-started/installation)
|
||||
- [Meshy — Rigging API, apenas para fase futura](https://docs.meshy.ai/en/api/rigging)
|
||||
- [Meta — Content Publishing](https://developers.facebook.com/documentation/instagram-platform/content-publishing)
|
||||
- [Meta — Coleção oficial Instagram API](https://www.postman.com/meta/instagram/documentation/6yqw8pt/instagram-api)
|
||||
|
||||
## 17. Comando final para o agente implementador
|
||||
|
||||
**Agora implemente a prova de conceito descrita. Comece pelo vídeo, use modelos provisórios e não espere integrações externas. Faça escolhas simples dentro deste escopo e registre-as. Valide o resultado real antes de afirmar sucesso. Entregue o MP4, os arquivos do projeto e os comandos de reprodução. Não implemente painel, SaaS ou publicação no Instagram nesta fase.**
|
||||
@@ -0,0 +1,235 @@
|
||||
# Resultado do teste — prova de conceito de vídeo em Godot
|
||||
|
||||
Data: 16/11/2026. Máquina: Windows 11 Pro 10.0.26200, Intel i9-13900K, 64 GB de RAM,
|
||||
**NVIDIA GeForce RTX 2060 SUPER** (Vulkan 1.4.341), tela de 1920×1080.
|
||||
|
||||
O que se distingue abaixo: **código criado**, **validação estática**, **projeto aberto na Godot**,
|
||||
**MP4 gerado** e **inspeção visual**. Tudo o que está marcado como feito foi executado nesta
|
||||
máquina, e os números vêm de `report.json`, `godot-manifest.json` e `render.log` de cada execução.
|
||||
|
||||
## Ambiente encontrado
|
||||
|
||||
| Item | Resultado |
|
||||
|---|---|
|
||||
| Godot | Não estava no `PATH`. Havia o zip oficial `Godot_v4.7.2-stable_win64.exe.zip` em Downloads; a pasta já extraída tinha só o wrapper `_console.exe`. O zip foi extraído em `.tools/godot-4.7.2/`, sem alterar o original. Assinatura Authenticode **válida** (Prehensile Tales B.V.). `--version` → `4.7.2.stable.official.ed1daf0bf`. |
|
||||
| FFmpeg/FFprobe | 7.1.1 *essentials* (gyan.dev) no `PATH`; encoders `libx264`, `h264_nvenc` e `aac` disponíveis |
|
||||
| Node / pnpm | 24.19.0 / 11.22.0 |
|
||||
| Sessão gráfica / GPU | sim / RTX 2060 SUPER (a Godot usou o dispositivo #0, Vulkan) |
|
||||
| Espaço livre | ~210 GB em F: |
|
||||
|
||||
## Entregas (MP4)
|
||||
|
||||
Todas em `output/runs/` (pasta ignorada pelo Git; regenere com os comandos do README).
|
||||
|
||||
| Execução | Configuração | Perfil | MP4 | Tamanho |
|
||||
|---|---|---|---|---|
|
||||
| `20261116-174231-demo-street-preview` | `config/demo-street.json` | 540×960 | `demo-street-preview.mp4` | 4,35 MB |
|
||||
| `20261116-173734-demo-street-final` | `config/demo-street.json` | 1080×1920 | `demo-street-final.mp4` | 11,6 MB |
|
||||
| `20261116-173649-demo-street-variant-preview` | `config/demo-street-variant.json` | 540×960 | `demo-street-variant-preview.mp4` | 3,65 MB |
|
||||
| `20261116-173528-demo-street-audio-preview` | cópia da cena padrão + tom de teste (ver "Áudio") | 540×960 | `demo-street-audio-preview.mp4` | 4,41 MB |
|
||||
|
||||
Comandos exatos:
|
||||
|
||||
```sh
|
||||
pnpm render -- --config config/demo-street.json --profile preview
|
||||
pnpm render -- --config config/demo-street.json --profile final
|
||||
pnpm render -- --config config/demo-street-variant.json --profile preview
|
||||
```
|
||||
|
||||
> O render final (`173734`) foi gerado antes de uma última mudança no `main.gd`: a checagem
|
||||
> de que a pasta do Movie Maker existe. Ela roda só na inicialização e não altera a cena. O
|
||||
> `stateDigest` do render final é igual ao da prévia gerada depois (`18b41815…`).
|
||||
|
||||
## Verificação automática (FFprobe + lançador)
|
||||
|
||||
Todas as quatro execuções passaram em todas as verificações:
|
||||
|
||||
| Verificação | Prévia | Final | Variante |
|
||||
|---|---|---|---|
|
||||
| Movie Maker anunciou resolução/FPS do perfil | 540×960 @ 30 | 1080×1920 @ 30 | 540×960 @ 30 |
|
||||
| PNGs gravados (contínuos, índice inicial 0) | 363 (0..362) | 363 | 363 |
|
||||
| Quadros de cena (+ aquecimento descartado) | 360 + 3 | 360 + 3 | 360 + 3 |
|
||||
| Codec / pix_fmt | h264 / yuv420p | h264 / yuv420p | h264 / yuv420p |
|
||||
| `r_frame_rate` | 30/1 | 30/1 | 30/1 |
|
||||
| Quadros decodificados (`-count_frames`) | 360 | 360 | 360 |
|
||||
| Duração (tolerância ±1 quadro) | 12,000 s | 12,000 s | 12,000 s |
|
||||
| Distância final da moto | 32 m de 32 m | 32 m de 32 m | 44 m de 44 m |
|
||||
| Luminância média em 0,5/4/8/11 s (não preto ≥ 20) | 147 / 148 / 146 / 116 | 147 / 148 / 146 / 116 | 135 / 133 / 134 / 111 |
|
||||
|
||||
`pnpm verify -- --file …/demo-street-final.mp4` confirmou o arquivo de forma independente
|
||||
(saída 0). Com `--fps 25`, a mesma verificação falha como esperado (saída 1).
|
||||
|
||||
### Determinismo
|
||||
|
||||
`stateDigest` (MD5 dos estados dos 360 quadros: posição, rodas, câmera, overlay):
|
||||
|
||||
- cena padrão: **`18b41815028decf7ef557b1573072af1`** na prévia (540×960), no final (1080×1920) e na
|
||||
execução com áudio. São três processos diferentes, em duas resoluções. O áudio não entra no estado;
|
||||
- `demo-street-variant`: `9cd400166a1c87e73d2165004d44c88d` (diferente, como esperado).
|
||||
|
||||
## Tempo medido (não é promessa de desempenho)
|
||||
|
||||
| Etapa | Prévia 540×960 | Final 1080×1920 |
|
||||
|---|---|---|
|
||||
| Validação (Godot headless) | 0,27 s | 0,26 s |
|
||||
| Render Godot (363 quadros) | 39–42 s | 153 s |
|
||||
| └ GPU por quadro | 1,9 ms | 4,5 ms |
|
||||
| └ CPU por quadro | 0,5 ms | 0,5 ms |
|
||||
| └ **codificação PNG por quadro** | **105 ms** | **404 ms** |
|
||||
| FFmpeg libx264 (preset medium, CRF 18) | 0,8–0,9 s | 2,8 s |
|
||||
| FFprobe + inspeção | ~1,3 s | ~3,4 s |
|
||||
| **Total** | **~42–45 s** | **~160 s** |
|
||||
|
||||
A etapa de render da Godot ocupa 94–96% do tempo total, e quase tudo é a codificação PNG: cerca de 91% do total no final (404 ms × 363 quadros ≈ 147 s de 160 s) e cerca de 90% na prévia (38 s de 42 s). A GPU é irrelevante neste plano.
|
||||
Fica como ponto de otimização futura, por exemplo comparar com a saída AVI/MJPEG do Movie
|
||||
Maker. Não foi medido aqui.
|
||||
|
||||
## Testes executados
|
||||
|
||||
- **`pnpm test:godot`**: 38/38 passaram (headless). Rejeitam JSON malformado, versão
|
||||
desconhecida, intervalo impossível (`start ≥ brake`, `stop > duração`), FPS zero, largura
|
||||
negativa ou ímpar, número como texto, duração sem número inteiro de quadros, cor inválida,
|
||||
percurso além do fim da rua, câmera abaixo do chão, texto com caractere de controle, campo
|
||||
desconhecido (`world.script`), áudio habilitado sem arquivo e arquivo inexistente. Na
|
||||
lógica temporal: posição inicial, parada até `startSeconds`, distância exata na parada,
|
||||
permanência parada, monotonicidade, ausência de saltos (passo máximo 0,00206 m com dt =
|
||||
0,5 ms), velocidade contínua, continuidade em cada fronteira de fase, ângulo da roda =
|
||||
distância/raio, visibilidade do overlay, mesmo estado em duas instâncias e independência
|
||||
da ordem de avaliação.
|
||||
- **`pnpm test:launcher`**: 17/17 passaram. Saída ≠ 0 não é sucesso; executável inexistente;
|
||||
argumentos com espaço e `;` chegam intactos (sem shell); timeout; cancelamento encerra o
|
||||
subprocesso; FFmpeg com entrada inexistente falha; `--` do pnpm ignorado; perfil não muta a
|
||||
config; trava de render único e recuperação de trava abandonada; conferência de PNG
|
||||
(lacuna, quantidade, dimensões, pasta vazia); critérios do FFprobe (tolerância de 1 quadro,
|
||||
FPS/dimensões/contagem errados); áudio inexistente; aviso de corte; filtro sem `-shortest`.
|
||||
- **`pnpm typecheck`**: sem erros (TypeScript 7.0.2).
|
||||
- **Projeto aberto na Godot**: `godot --headless --path godot --import` (editor) terminou sem erros e
|
||||
gerou os `.uid`/`.import`. O `--check-only` de todos os scripts também passou sem erros.
|
||||
- **Prévia interativa**: `godot --path godot --quit-after 90 -- --config config/demo-street-variant.json`
|
||||
abriu em modo preview (`SCENE_READY … mode=preview`). Os controles de teclado não foram
|
||||
acionados manualmente.
|
||||
- **Falha pelo lançador**: render com `godot/tests/fixtures/impossible-times.json` parou na etapa
|
||||
`validate` (saída 1, `status: failed`) com a mensagem
|
||||
`motion: exige startSeconds < brakeStartSeconds < stopSeconds <= durationSeconds (recebido 5.0 < 4.0 < 13.0 <= 12.0)`.
|
||||
O `output/last-success.json` continuou apontando para o render válido anterior.
|
||||
- **Áudio (pipeline)**: um tom senoidal de 5 s, gerado só para o teste (não é narração), foi
|
||||
colocado num caminho com espaço, com `offsetSeconds: 9`. O lançador avisou o corte de 2,00 s.
|
||||
O MP4 saiu com vídeo h264 de 12,000 s e áudio AAC 48 kHz de 12,000 s. Pico do áudio: −91 dB
|
||||
antes de 9 s (silêncio) e −18 dB depois de 9,1 s (tom). O arquivo de entrada não foi alterado.
|
||||
|
||||
## Inspeção visual
|
||||
|
||||
Foram examinados os quadros extraídos **do MP4** em 0,5 s, 4 s, 8 s e 11 s (`inspect/` de cada
|
||||
execução), uma tira com 1 quadro por segundo do MP4 final, recortes ampliados do entregador e
|
||||
das rodas, e o quadro de 11 s em 1080×1920. **O vídeo não foi assistido em um player**: a
|
||||
avaliação de fluidez vem dos quadros em sequência e dos testes numéricos.
|
||||
|
||||
| Critério | Resultado |
|
||||
|---|---|
|
||||
| Sem vídeo preto, câmera dentro de geometria ou textura ausente | ok |
|
||||
| Personagem reconhecível e apoiado na moto | ok: capacete com viseira, jaqueta, mãos no guidão, pés nas pedaleiras, caixa de entrega no bagageiro |
|
||||
| Mudança de perspectiva dos objetos próximos | ok: muros, casas, árvores e postes passam e mudam de perspectiva quadro a quadro |
|
||||
| Rodas girando | ok: raios e cravos mudam de posição entre quadros consecutivos (~26°/quadro a 4,13 m/s, abaixo do limiar de efeito estroboscópico da simetria de 60°) |
|
||||
| Fundo sem rotação artificial nem bordas de planos | ok após correção (ver abaixo); as fachadas são planos fixos voltados para +Z |
|
||||
| Sem z-fighting importante ou texto cortado | ok; acentos e travessão (—) renderizam com a fonte padrão |
|
||||
| Overlay legível em tamanho reduzido | ok na tira de 180 px de largura |
|
||||
| Luz e cores consistentes | ok; do quadro 1 em diante (o quadro 0 é descartado, ver abaixo) |
|
||||
|
||||
## Problemas encontrados e corrigidos durante o teste
|
||||
|
||||
1. **Primeiro quadro inválido.** O quadro 0 gravado pela Godot 4.7.2 saía azulado, com uma sombra
|
||||
diagonal errada, porque sombras e radiância do céu ainda não estavam prontas. A partir do
|
||||
quadro 1 tudo ficava estável. Correção: 3 quadros de aquecimento em `t = 0`, descartados com
|
||||
`-start_number 3`.
|
||||
2. **`delta` não é 1/30 com `--fixed-fps`.** Os valores observados foram 0,025, 0,0333, 0,0417…
|
||||
Por isso o tempo da cena vem do contador de quadros.
|
||||
3. **Resolução do filme fixada na inicialização.** `--resolution` e mudanças em runtime não
|
||||
alteram o arquivo gravado, e uma janela de 1080×1920 não cabe numa tela de 1080 px. Correção:
|
||||
`override.cfg` temporário por render. A cena confere se o viewport corresponde à configuração.
|
||||
4. **`--write-movie` relativo e falha silenciosa.** O caminho relativo é resolvido a partir de
|
||||
`godot/`. Com a pasta inexistente, nenhum PNG foi gravado e mesmo assim a Godot saiu com
|
||||
código 0, imprimindo "Done recording". Correção: o lançador usa caminho absoluto e confere os
|
||||
PNGs, e a cena aborta (código 3) se a pasta não existir.
|
||||
5. **Composição.** O título quebrava em duas linhas sobre a opção A, e no fim o texto cobria o
|
||||
entregador. O título passou a crescer para cima, e a câmera final desce para um ângulo baixo
|
||||
(entregador na metade superior, opções embaixo, ~18% inferior livre).
|
||||
6. **Borda reta do morro** visível contra o céu. Correção: cumeeira irregular com volumes
|
||||
(determinística pela seed).
|
||||
7. **`pnpm doctor`** é comando nativo do pnpm 11; o diagnóstico do projeto é `pnpm run doctor`.
|
||||
|
||||
## Painel (16/11/2026, depois da prova de conceito)
|
||||
|
||||
Executado com o painel em `pnpm panel` (127.0.0.1:4310):
|
||||
- `next build`: sem erros de tipo nem avisos. Páginas `/`, `/assets` e `/agent` respondem 200;
|
||||
história inexistente responde 404.
|
||||
- `/api/files`: serve PNG e MP4 (com `Range` → 206) e bloqueia `../package.json` e
|
||||
`godot/project.godot` (404).
|
||||
- Lógica por script: 25/25 casos ok. Cobre a regra de voto ("A ou B?" e "Amei" não contam),
|
||||
apuração com último voto por conta, comentário repetido ignorado, linha sem autor rejeitada,
|
||||
fotografia imutável, episódio seguinte herdando a escolha, decisão manual obrigatória sem
|
||||
votos, asset da história com `asset.json`, extensão errada recusada e promoção para a biblioteca.
|
||||
- Agente pela API: Claude Haiku leu `package.json` com cwd na raiz, com streaming SSE de
|
||||
sessão, ferramenta, resultado e custo (US$ 0,0072). "Continuar conversa" retomou a sessão.
|
||||
O segundo pedido simultâneo foi recusado e o Codex aparece como não instalado.
|
||||
- Render pelo painel: episódio de teste em prévia em 44 s, `success`, MP4 registrado e player na
|
||||
página do episódio.
|
||||
- **Não testado:** interface clicada no navegador (o navegador automatizado estava ocupado por
|
||||
outra sessão); formulários foram validados pela mesma lógica que eles chamam. Codex não testado.
|
||||
- Dados de teste removidos depois.
|
||||
|
||||
## Serviço de voz e página Vozes (16/11/2026)
|
||||
|
||||
Máquina: Windows 11, RTX 2060 SUPER 8 GB (driver 610.88), com um jogo (Rust) aberto durante parte dos testes.
|
||||
- `setup.bat` completo rodou duas vezes com saída 0. A 1ª rodada deixou a GPU passar por "sem GPU" (bug no
|
||||
`nvidia-smi | Select-Object -First 1`, corrigido); a 2ª trocou `torch 2.11.0+cpu` por `+cu128`
|
||||
(`cuda True`). O `VoiceConverter` do Applio 3.7.0 importa em `cuda:0`; rmvpe, fcpe e contentvec baixados.
|
||||
- `pnpm test:voice`: 122 testes passando (motores falsos + decodificador real + detecção de GPU ocupada).
|
||||
- Fumaça (`voice/scripts/smoke.py`): Antonio (Edge) 6,5 s de áudio em 3,0 s; Francisca (Edge) 5,8 s em 2,6 s;
|
||||
Faber (Piper) 4,9 s em 2,5 s na 1ª vez e 0,02 s carregado. Whisper small na CPU: 6,5 s de fala em 2,7 s
|
||||
com 14 palavras e tempos.
|
||||
- GPU sem cuBLAS: falha só na 1ª inferência → o aquecimento na subida pega e cai para a CPU. GPU ocupada pelo
|
||||
jogo (99%, 1,6 GB livres): legenda de 6,5 s ficou mais de 8 min na GPU; depois da mudança, o `auto` escolheu
|
||||
CPU e a mesma legenda pelo painel levou 2,5 s.
|
||||
- Painel (`/voices` e `/api/voice/*`, 127.0.0.1:4500): status, ouvir (Francisca em 2,1 s), validação de
|
||||
texto vazio, legenda com `.srt`, salvar configurações com reinício automático do serviço, adicionar voz
|
||||
(recusa sem origem/licença e arquivo que não é `.pth` do torch), remover (recusa voz base), e `.pth` sem
|
||||
estrutura RVC → `422 rvc_failed` com mensagem clara. Páginas `/`, `/voices`, `/assets`, `/agent` → 200.
|
||||
- **Não testado:** conversão RVC com modelo real (nenhum modelo neutro com licença clara), Whisper
|
||||
`large-v3-turbo`, download de modelo pelo painel, estado offline visto no navegador.
|
||||
|
||||
## Clipador — cortes de live (16/11/2026)
|
||||
|
||||
Teste ponta a ponta numa live real (twitch.tv/alanzoka, Parasite Eve), serviço `clipper/` em 127.0.0.1:4520:
|
||||
|
||||
- Captura: Streamlink 8.6.3 → FFmpeg em blocos de 30 s; 10 min 18 s gravados (21 blocos), parada pelo painel/API
|
||||
fechou o último bloco sem deixar `streamlink`/`ffmpeg` órfãos.
|
||||
- Chat: IRC anônimo da Twitch conectado, 490 mensagens mapeadas para o tempo da gravação.
|
||||
- Transcrição: 21/21 blocos pelo serviço de voz (`X-Detail: words`), 0 erros; texto em pt-BR bate com a legenda do jogo.
|
||||
- Momentos: 4 cortes automáticos pelo chat; juiz `codex:gpt-6-luna` manteve os 4 (notas 7,4–8,5), ~7 s por candidato.
|
||||
"Cortar agora" (40 s): juiz deu nota 3 (sem gancho), renderizado por ser manual.
|
||||
- Render: H.264 1080×1920 + AAC, 40–52 s; quadros inspecionados mostram crédito `twitch.tv/alanzoka` no topo e
|
||||
legenda palavra a palavra sincronizada. Vídeos não assistidos inteiros em player.
|
||||
- Testes: `pnpm test:clipper` → 33 passed; `pnpm typecheck` e `npx tsc --noEmit -p panel` limpos.
|
||||
|
||||
Corrigido no teste: legenda deslocada (`-ss` depois do `-i`), tag `\c` virando `\C` com `.upper()`, e 2 falsos
|
||||
positivos com chat calmo (emote `clip5k1hmm`, começo da gravação) — ver `clipper/README.md`, "Armadilhas".
|
||||
Não testado: chat da Kick, live do YouTube, VOD, juiz `claude`, publicação nas redes (ainda não existe).
|
||||
|
||||
## O que continua provisório ou pendente
|
||||
|
||||
- Moto, entregador e casas feitos de primitivas, sem rig nem animação facial. Fachadas
|
||||
distantes geradas proceduralmente.
|
||||
- O vídeo não foi assistido em player (só quadros extraídos).
|
||||
- O cancelamento por Ctrl+C real no terminal não foi exercitado; há teste unitário da lógica.
|
||||
- Não foi testado em Linux, nem com os renderizadores Compatibility ou Forward+.
|
||||
- A codificação PNG domina o tempo de render; não houve otimização.
|
||||
- Um único preset de câmera (`third_person_follow`) e um único asset (`placeholder-rider`).
|
||||
|
||||
## Próximos passos sugeridos
|
||||
|
||||
1. Assistir aos MP4 e ajustar o ritmo: velocidade de 4,1 m/s (~15 km/h) e duração da transição da câmera.
|
||||
2. Medir a saída AVI/MJPEG do Movie Maker contra PNG para reduzir o tempo de render.
|
||||
3. Nó adaptador para GLB (escala/orientação) e primeiro teste com um modelo real.
|
||||
4. Ligar o render ao serviço de voz: narração gerada por fala (`/v1/synthesize`, `wav`) e legenda
|
||||
automática a partir dos tempos (`/v1/transcribe`, `X-Detail: words`).
|
||||
5. Só então: contrato de cena compartilhado com o futuro painel/API.
|
||||
@@ -0,0 +1,67 @@
|
||||
# Editor de cortes — pesquisa (16/11/2026)
|
||||
|
||||
Base do editor do Clipador (`/clipper/edit/<id>`). Estudamos padrões; **nenhum código de terceiros foi copiado**.
|
||||
|
||||
## OpenCut — https://github.com/OpenCut-app/OpenCut (MIT)
|
||||
|
||||
O repositório principal está sendo reescrito em Rust. O editor web maduro está em
|
||||
https://github.com/OpenCut-app/opencut-classic (MIT).
|
||||
|
||||
O que pegamos:
|
||||
|
||||
- **Trilhas por papel e elementos com início/fim.** No OpenCut, `apps/web/src/timeline/types.ts` define trilhas
|
||||
`video | text | audio | graphic | effect` e elementos com `startTime`, `duration`, `trimStart` e `trimEnd`.
|
||||
Aqui viraram as trilhas Vídeo/Legenda/Texto-zoom/Áudio/Chat e os trechos `cuts` com início e fim em tempo da
|
||||
sessão.
|
||||
- **Desfazer por comandos** (`core/managers/commands.ts`). Simplificamos para instantâneos do projeto, que é
|
||||
pequeno, e juntamos arrastes seguidos num passo só.
|
||||
- **Atalhos de mercado** (`actions/definitions.ts`):
|
||||
|
||||
| Tecla | Ação |
|
||||
|---|---|
|
||||
| Espaço / K | tocar ou pausar |
|
||||
| J / L | ±2 s |
|
||||
| ← / → | um quadro |
|
||||
| S | dividir |
|
||||
| Q / W | cortar até ou desde o playhead |
|
||||
| Del | remover |
|
||||
| Ctrl+Z / Ctrl+Shift+Z | desfazer / refazer |
|
||||
|
||||
- **Ímã** (`timeline/snapping/`, limiar de ~10 px). Aqui são 8 px, nas bordas das palavras e no playhead.
|
||||
- **Forma de onda em cache, desenhada em canvas.** Aqui os picos vêm do FFmpeg no servidor.
|
||||
- **O que não seguimos:** o export no navegador (WebCodecs/mediabunny). O render final fica no FFmpeg do
|
||||
servidor, a mesma pipeline do Clipador, e o navegador só mostra uma prévia aproximada.
|
||||
|
||||
## effectcraft — https://github.com/storytold/effectcraft (MIT OR Apache-2.0; nome/logo "ArtCraft" são marcas)
|
||||
|
||||
É um app de motion graphics no estilo After Effects, em Rust, com GPU via wgpu e 308 efeitos. Está em alfa, não
|
||||
usa FFmpeg e não traz legendas. Não serve como biblioteca para nós. Ficaram duas ideias:
|
||||
|
||||
- **efeito como dado** (projeto `.ecproj` em JSON);
|
||||
- **animadores de texto por faixa.** Aqui viraram presets de legenda descritos por dados e tags ASS (`\t`,
|
||||
`\fscx`, `\kf`, `\fad`).
|
||||
|
||||
## Editores online de vídeo curto
|
||||
|
||||
| Editor | O que adotamos |
|
||||
|---|---|
|
||||
| **Descript** ([ajuda](https://help.descript.com/hc/en-us/articles/21908864772493)) | Edição pela transcrição (apagar palavra corta o vídeo) e "encurtar pausas" com limiar. Aqui: "Remover silêncios > X s", com 0,15 s de respiro de cada lado. |
|
||||
| **Opus Clip** ([editor](https://opus.pro/ai-video-editor)) | Texto + timeline juntos; reenquadramento 9:16 (aqui: layout por trecho); a IA propõe o corte. |
|
||||
| **Submagic** ([Hormozi](https://www.submagic.co/blog/how-to-make-alex-hormozi-captions), [temas](https://care.submagic.co/en/article/what-are-themes-and-themes-categories-1pv8wvz/)) | Presets de legenda: palavra falada com pop de escala, cor de ênfase por palavra e "Magic Zoom". Aqui: presets **pop**, **uma palavra por vez**, **karaokê**, **clássica** e **mínima**, ênfase verde por palavra e punch-in com rampa (0 = crash zoom). |
|
||||
| **Vizard** ([legendas animadas](https://vizard.ai/tools/animated-subtitles)) | Destaque de palavra-chave. Nota de gancho ficou para depois. |
|
||||
| **Kapwing / VEED** ([Smart Cut](https://www.kapwing.com/help/how-to-use-smart-cut/)) | Remover silêncios com sensibilidade ajustável. |
|
||||
| **CapCut** ([karaokê](https://www.capcut.com/features/how-to-make-karaoke-subtitles-capcut-workflow-alternate)) | Legenda karaokê (preenche palavra a palavra). |
|
||||
|
||||
Padrões adotados no editor: edição pela transcrição, timeline com forma de onda, legendas animadas, layout 9:16
|
||||
por trecho, zoom, gancho nos primeiros segundos, barra de progresso, narração TTS, música com ducking,
|
||||
exportação no servidor e capa (etapa 7 da metodologia).
|
||||
|
||||
**Não verificado na pesquisa:** se esses editores fazem ducking automático de música; barra de progresso nativa
|
||||
(só confirmada no Vizard Agent).
|
||||
|
||||
**Fora por enquanto:**
|
||||
|
||||
- emoji colorido (o libass do FFmpeg desenha monocromático);
|
||||
- B-roll;
|
||||
- legenda com caixa por palavra;
|
||||
- reenquadramento que segue o rosto quadro a quadro.
|
||||
@@ -0,0 +1,129 @@
|
||||
# API das peças e cenas do Godot (gerado)
|
||||
|
||||
Gerado por `python .claude/skills/cenaforge/scripts/godot_api.py`. Não edite à mão: rode de novo
|
||||
quando uma peça ou cena mudar. Use estas funções sem abrir os .gd inteiros.
|
||||
|
||||
## Peças (`godot/kits/`, use com `preload("res://kits/<arquivo>.gd")`)
|
||||
|
||||
### `godot/kits/boat.gd`
|
||||
> Peça reaproveitável: lancha de pesca (~8 m) low-poly, com balanço e afundamento.
|
||||
> const Boat := preload("res://kits/boat.gd")
|
||||
> var b := Boat.new()
|
||||
> b.build({"hull": "#f2f0ea", "stripe": "#1f5fa8", "cabin": "#e9e6df", "lights": true})
|
||||
> add_child(b)
|
||||
> # em apply(t):
|
||||
> b.float_on(t, 1.0) # balanço no mar (intensidade 0 = calmo, 1 = normal, 2 = agitado)
|
||||
> b.sink(0.6) # 0 = flutuando; 1 = quase submerso (popa afunda primeiro, adernado)
|
||||
> Origem no centro do casco na linha d'água (y = 0 é o nível do mar), proa em -Z.
|
||||
|
||||
- `build(opts: Dictionary = {}) -> void`
|
||||
- `deck() -> Node3D`: Corpo do barco (balança e afunda): pessoas e objetos a bordo entram como filhos dele, com o pé em y = DECK_Y; popa em +Z (z de 0,8 a 3,4 livre atrás da cabine).
|
||||
- `float_on(t: float, intensity := 1.0) -> void`: Balanço determinístico no mar (sobe/desce, arfagem e jogo).
|
||||
- `sink(amount: float) -> void`: 0 = flutuando; 1 = quase submerso. Chame antes de float_on no mesmo quadro.
|
||||
|
||||
### `godot/kits/person.gd`
|
||||
> Peça reaproveitável: pessoa estilizada (low-poly) com juntas e animações por tempo.
|
||||
> const Person := preload("res://kits/person.gd")
|
||||
> var p := Person.new()
|
||||
> p.build({"shirt": "#2f6fb3", "pants": "#3a3a3a", "skin": "#c68e6a", "hair": "#2b1d14", "height": 1.75})
|
||||
> # opções: "sleeveless": true (regata, braço de fora), "shorts": true (bermuda), "vest", "shoes"
|
||||
> add_child(p)
|
||||
> # em apply(t):
|
||||
> p.pose("walk", t) # parado | andar | correr | nadar | sentar | acenar | ajoelhar | deitar
|
||||
> p.blend("walk", "run", t, 0.3) # mistura duas poses (0 = a primeira, 1 = a segunda)
|
||||
> Origem nos pés (y = 0 é o chão), frente em -Z. Tudo depende só de t: determinístico.
|
||||
> Poses: "idle", "walk", "run", "swim", "sit", "wave", "kneel", "lie", "exhausted".
|
||||
|
||||
- `build(opts: Dictionary = {}) -> void`
|
||||
- `pose(action: String, t: float, amount := 1.0) -> void`: Aplica uma pose no instante t (segundos). Ver lista no topo.
|
||||
- `blend(a: String, b: String, t: float, k: float) -> void`: Mistura duas poses (k de 0 a 1), por exemplo "walk" → "kneel" quando o personagem chega.
|
||||
|
||||
## Cenas da biblioteca (`godot/library/<id>/`)
|
||||
|
||||
### `castaways`
|
||||
**Náufragos no costão** (doc3d): Reconstituição estilizada: quatro pescadores, pesqueiro e lancha civil na ilha. Chegada, naufrágio, nado, espera, resgate, embarque e partida. Elenilson mantém regata cinza e bermuda escura; roupas e gestos são ilustrativos.
|
||||
- param `moment` (select: arrival, sinking, swimming, waiting, rescue, boarding, departure; padrão 'arrival')
|
||||
- param `camera` (select: medium, close, wide; padrão 'medium')
|
||||
- param `variant` (number; padrão 0)
|
||||
|
||||
`godot/library/castaways/actor.gd`
|
||||
> Mantém o kit e suas roupas; flexão das poses voltada para a frente local (-Z).
|
||||
|
||||
`godot/library/castaways/cast.gd`
|
||||
> Elenco e barcos da reconstituição dos náufragos (opções de res://kits/person.gd e boat.gd).
|
||||
> Elenilson: regata cinza e bermuda escura (convenção visual do roteiro, igual em todo o vídeo).
|
||||
> Os companheiros usam cores discretas e diferentes entre si, nenhuma cinza.
|
||||
|
||||
`godot/library/castaways/shore.gd`
|
||||
> Ilha reutilizada com uma pequena laje de costão para encenação, sem precisão topográfica.
|
||||
> A malha e ground_at compartilham as mesmas alturas; a ilha original não é modificada.
|
||||
|
||||
- `prepare_coast(center: Vector3, sea: Vector3) -> void`
|
||||
- `height_at(x: float, z: float) -> float`
|
||||
|
||||
`godot/library/castaways/sky.gd`
|
||||
> Céu, sol (ou lua), névoa e cor do mar por hora do dia, com mistura entre duas horas
|
||||
> (a espera no costão passa da noite para o dia). Usa o ShaderMaterial do mar da ilha.
|
||||
> const SkyRig := preload("res://library/castaways/sky.gd")
|
||||
> var sky := SkyRig.new(); add_child(sky)
|
||||
> sky.build(island.ocean_material(), direção_horizontal_do_sol)
|
||||
> sky.set_preset("dawn") # "dawn" | "day" | "dusk" | "night"
|
||||
> sky.blend_presets("night", "dawn", k)
|
||||
|
||||
- `build(ocean: ShaderMaterial, sun_dir: Vector3) -> void`
|
||||
- `set_preset(preset: String) -> void`
|
||||
- `blend_presets(a_name: String, b_name: String, k: float) -> void`
|
||||
|
||||
`godot/library/castaways/template.gd`
|
||||
> Cena 3D do documentário: os náufragos da Ilha das Cobras (reconstituição do caso de 2019).
|
||||
> Elenilson (regata cinza, bermuda escura) e três companheiros, do naufrágio do pesqueiro ao
|
||||
> resgate pela lancha de mergulho, no costão da ilha da biblioteca (res://library/island).
|
||||
> Tudo depende só de (params, t): poses e barcos animados por tempo, sem física nem relógio.
|
||||
> Modelo "castaways": params
|
||||
> moment: "arrival" | "sinking" | "swimming" | "waiting" | "rescue" | "boarding" | "departure"
|
||||
> camera: "medium" (padrão) | "close" (mais perto do Elenilson) | "wide" (mais aberto)
|
||||
> variant: inteiro; muda o ângulo da câmera (lado, altura e ponto de vista)
|
||||
> Tom sóbrio: sem cobra, sem helicóptero, sem navio militar; a lancha do resgate é civil.
|
||||
|
||||
- `setup(cfg: Dictionary, viewport_size: Vector2) -> void`
|
||||
- `apply(t: float) -> void`
|
||||
- `state_signature() -> String`
|
||||
|
||||
`godot/library/castaways/verify.gd`
|
||||
> Verificação local: Godot --headless --path godot --script res://library/castaways/verify.gd
|
||||
> Compara todos os nós articulados ao buscar tempos em ordens diferentes.
|
||||
|
||||
### `island`
|
||||
**Ilha costeira** (doc3d): Ilha alongada com mata densa, costão de pedra e farol listrado num mar animado. Sobrevoo, chegada pelo mar, perto do farol ou rasante; de dia, entardecer ou noite. Outras cenas podem usá-la como cenário (params embedded: true, environment: false, sea_detail: true; métodos ground_at(x, z), sea_height(x, z, t), set_sea_state, set_sea_focus, rock_list e lighthouse_position()).
|
||||
- param `shot` (select: orbit, approach, lighthouse, lowpass; padrão 'orbit')
|
||||
- param `time` (select: day, sunset, night; padrão 'day')
|
||||
- param `lighthouse` (bool; padrão True)
|
||||
|
||||
`godot/library/island/template.gd`
|
||||
> Cena 3D do documentário: uma ilha costeira estilizada (terreno por ruído, mata densa,
|
||||
> costão de pedra, farol) num mar animado por shader. Tudo depende só de (configuração, t):
|
||||
> sementes fixas, o mar recebe o tempo de cena por uniform (não usa TIME), então o render
|
||||
> é determinístico.
|
||||
> Modelo "island": params
|
||||
> shot: "orbit" (sobrevoo em volta) | "approach" (chega do mar) | "lighthouse" (perto do
|
||||
> farol) | "lowpass" (rasante sobre a água) — padrão "orbit"
|
||||
> time: "day" | "sunset" — padrão "day"
|
||||
> lighthouse: true/false — padrão true
|
||||
> variant: inteiro; muda ângulo inicial, sentido da câmera e (ímpar) a hora do dia
|
||||
> Como cenário de outra cena (params embedded: true; environment: false se a outra cena faz
|
||||
> céu e luz; sea_detail: true para tomadas rente à água): height_at / ground_at / ground_normal
|
||||
> (terreno), sea_height(x, z, t) e set_sea_state(escala) (mar), set_sea_focus(x, z) (centro da
|
||||
> malha fina do mar), rock_list() (pedras do costão) e lighthouse_position().
|
||||
|
||||
- `lighthouse_position() -> Vector3`: Para outras cenas da biblioteca: posição do farol (pé da torre) e altura do terreno.
|
||||
- `ground_at(x: float, z: float) -> float`: Altura da superfície do terreno COMO DESENHADA (interpola os triângulos da malha, não o ruído): use para apoiar pés, joelhos e pedras sem flutuar nem afundar na rocha.
|
||||
- `ground_normal(x: float, z: float) -> Vector3`: Normal do terreno desenhado em (x, z).
|
||||
- `rock_list() -> Array`: Pedras do costão: lista de [centro (Vector3), raio horizontal].
|
||||
- `sea_height(x: float, z: float, t: float) -> float`: Altura da água em (x, z) no instante t (as mesmas ondas do shader).
|
||||
- `set_sea_state(scale: float) -> void`: Mar mais calmo (< 1) ou agitado (> 1). Padrão 1.
|
||||
- `set_sea_focus(x: float, z: float) -> void`: Com params.sea_detail = true, o mar é uma malha radial fina no centro; mova o centro para perto da câmera a cada quadro (as ondas usam coordenada do mundo, então não "andam").
|
||||
- `ocean_material() -> ShaderMaterial`
|
||||
- `setup(cfg: Dictionary, viewport_size: Vector2) -> void`
|
||||
- `apply(t: float) -> void`
|
||||
- `state_signature() -> String`
|
||||
- `height_at(x: float, z: float) -> float`: Altura do terreno (y = 0 é o nível do mar). A ilha é alongada, com uma crista central alta, encostas íngremes e costão de pedra que cai direto no mar.
|
||||
@@ -0,0 +1,160 @@
|
||||
# Guia: construir cenas no Godot para os vídeos (biblioteca de cenas)
|
||||
|
||||
Para **qualquer agente** (Codex ou Claude pela CLI do painel) que precise de uma cena que ainda
|
||||
não existe: um campo de futebol, um estádio, o Pelé batendo um pênalti, uma cidade, um planeta.
|
||||
A cena construída fica guardada na **biblioteca** e serve para todos os vídeos depois.
|
||||
|
||||
## Onde fica
|
||||
|
||||
```
|
||||
godot/library/<id>/
|
||||
template.gd a cena (obrigatório)
|
||||
manifest.json nome, descrição, parâmetros e palavras-chave (obrigatório)
|
||||
*.gd peças reaproveitáveis (ex.: field.gd com a função que monta o campo)
|
||||
assets/ modelos .glb, texturas, sons que a cena usa (opcional)
|
||||
```
|
||||
|
||||
- `<id>`: minúsculas, números e `-` (ex.: `soccer-field`, `penalty-kick`). É o nome usado no JSON.
|
||||
- **Leia `doc/godot/api.md`** (gerado: assinaturas das peças e cenas) em vez de abrir os .gd
|
||||
inteiros de outras cenas. Depois de criar ou mudar peça ou cena, rode
|
||||
`python .claude/skills/cenaforge/scripts/godot_api.py` para atualizar o resumo.
|
||||
- Antes de criar, **liste `godot/library/`** e leia os manifestos: se já existe algo parecido,
|
||||
reaproveite ou estenda. Uma cena pode usar peças de outra:
|
||||
`const Field := preload("res://library/soccer-field/field.gd")`.
|
||||
- Não mexa em `godot/scripts/`, `scripts/` nem `panel/`: a cena nova não precisa disso.
|
||||
|
||||
## Contrato do `template.gd`
|
||||
|
||||
```gdscript
|
||||
extends Node3D # (ou Node2D para cena 2D)
|
||||
|
||||
## Monta a cena uma vez. cfg.params = parâmetros do manifest; cfg.video.duration = segundos.
|
||||
func setup(cfg: Dictionary, viewport_size: Vector2) -> void: ...
|
||||
|
||||
## Estado no instante t (segundos). Chamada a cada quadro, em qualquer ordem de t.
|
||||
func apply(t: float) -> void: ...
|
||||
|
||||
## Texto curto do estado atual (posição da câmera etc.), para conferir determinismo.
|
||||
func state_signature() -> String: ...
|
||||
```
|
||||
|
||||
Regras que não se negociam:
|
||||
|
||||
1. **Determinismo:** a imagem depende só de `(params, t)`. Nada de `TIME`, `randf()` sem semente,
|
||||
`_process(delta)` nem física em tempo real. Use `RandomNumberGenerator` com `seed` fixo e
|
||||
passe `t` para shaders por `uniform` (veja o mar da ilha).
|
||||
2. **A cena dura o que a narração dura** (`cfg.video.duration`, de 2 a ~20 s). Anime em
|
||||
proporção da duração (`p = t / duração`) para funcionar com qualquer tamanho.
|
||||
3. **Vertical 9:16** (1080x1920; a prévia é 540x960). Componha para tela em pé. O terço de
|
||||
baixo (y > 70%) recebe a legenda, e o alto (y < 18%), o texto na tela. Deixe o assunto
|
||||
principal no meio.
|
||||
4. **Câmera própria:** crie a `Camera3D`, marque `current = true` e posicione em `apply(t)`.
|
||||
Movimento suave (ease in/out), nada de corte seco dentro da cena.
|
||||
5. **Luz e céu próprios** (WorldEnvironment + DirectionalLight3D). O render é `mobile`, com MSAA 2x.
|
||||
Tonemap ACES e névoa leve deixam tudo mais bonito.
|
||||
6. **Parâmetro `variant`** (inteiro): o botão "Gerar de novo" do painel soma 1. Use para mudar
|
||||
ângulo, sentido da câmera, hora do dia ou paleta, mantendo a cena reconhecível.
|
||||
7. **Sem texto dentro da cena 3D** (o painel põe o texto na tela e a legenda por cima).
|
||||
|
||||
## `manifest.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "soccer-field",
|
||||
"kind": "doc3d",
|
||||
"label": "Campo de futebol",
|
||||
"description": "Estádio com gramado listrado, traves, arquibancada e torcida; câmera de transmissão.",
|
||||
"keywords": ["campo", "futebol", "gol", "estádio", "gramado", "pênalti"],
|
||||
"params": [
|
||||
{ "name": "shot", "label": "Tomada", "type": "select", "default": "broadcast", "options": [
|
||||
{ "value": "broadcast", "label": "Câmera de TV", "keywords": ["jogo", "partida"] },
|
||||
{ "value": "goal", "label": "Atrás do gol", "keywords": ["gol", "pênalti", "goleiro"] }
|
||||
] },
|
||||
{ "name": "night", "label": "Jogo à noite", "type": "bool", "default": false },
|
||||
{ "name": "team_color", "label": "Cor do time", "type": "text", "default": "#ffffff" }
|
||||
],
|
||||
"createdBy": "<agente>",
|
||||
"createdAt": "AAAA-MM-DD"
|
||||
}
|
||||
```
|
||||
|
||||
- `keywords`: palavras que, na coluna "Imagem" do roteiro, fazem o modo automático escolher
|
||||
esta cena. Seja específico (para uma cena de futebol, não use "verde").
|
||||
- `params[].type`: `select` (com `options`), `bool`, `number` ou `text`. Cada opção de `select`
|
||||
pode ter `keywords` próprias: o automático escolhe a opção pelo texto do roteiro.
|
||||
- O painel monta o formulário da cena a partir daqui.
|
||||
|
||||
## Testar: renderize e OLHE os quadros
|
||||
|
||||
1. Crie um JSON de teste em `data/tmp/<id>-teste.json`:
|
||||
```json
|
||||
{ "id": "teste-<id>", "kind": "doc3d", "template": "<id>",
|
||||
"video": { "width": 1080, "height": 1920, "fps": 30, "durationSeconds": 5 },
|
||||
"params": { "shot": "broadcast", "variant": 0 } }
|
||||
```
|
||||
2. Rode `python .claude/skills/cenaforge/scripts/frame_check.py --config data/tmp/<id>-teste.json`.
|
||||
Ele chama `pnpm render ... --profile preview`, mostra só o fim do log se falhar e devolve ~10
|
||||
linhas: status, tempo e, por quadro, luz, contraste, movimento e enquadramento, marcando
|
||||
ESCURO, ESTOURADO, CHAPADO, PARADO ou FORA. Para conferir um render que já existe:
|
||||
`frame_check.py output/runs/<run>` (ou `--last`).
|
||||
- `CONFIG_INVALID`: o erro diz o campo.
|
||||
- `SCENE_SCRIPT_INVALID`: o `template.gd` (ou algo que ele carrega) não compila. A validação
|
||||
reprova antes de renderizar e os `Parse Error` com a linha ficam no `render.log` da pasta do run.
|
||||
Os dois erros mais comuns:
|
||||
- `var x := dict.get("k")`, `var p := nodes[i]` ou uma variável de tipo `Node3D` com método do
|
||||
kit: o tipo não pode ser inferido. Declare o tipo (`var x: Vector3 = ...`) ou use `=`.
|
||||
- Constante com nome de classe do Godot (`const Sky := preload(...)`, `Camera3D`, `Environment`):
|
||||
"shadows a native class". Use outro nome (`SkyRig`).
|
||||
3. **Abra UMA imagem por render**, a que o `frame_check.py` indicar: `inspect/contact-sheet.png`
|
||||
(480 px de altura) ou o quadro marcado. Não abra quadros soltos em resolução cheia, não abra
|
||||
imagens em lote e não gere imagens próprias de QA: cada imagem fica no histórico e é reenviada
|
||||
a cada turno (na cena dos náufragos, ~100 imagens = 6,8 milhões de tokens de entrada). Confira
|
||||
com olho crítico:
|
||||
- [ ] o assunto está claro e no meio da tela vertical;
|
||||
- [ ] nada cortado nas bordas e nada sem sentido (objeto flutuando, buraco, emenda no horizonte);
|
||||
- [ ] cores com contraste (nada lavado ou estourado) e luz coerente;
|
||||
- [ ] movimento suave entre o primeiro e o último quadro;
|
||||
- [ ] cada `select` e `variant` 0, 1 e 2 dão resultados diferentes e bons.
|
||||
4. Corrija e renderize de novo **até ficar bom**. Uma cena só vai para a biblioteca quando
|
||||
passar nessa lista. Depois apague os JSONs de teste.
|
||||
|
||||
## Personagens e animação (ex.: o Pelé batendo o pênalti)
|
||||
|
||||
- Sem modelo pronto, monte o personagem com formas simples (cápsulas e cilindros: tronco,
|
||||
cabeça, braços, coxas, canelas) em `Node3D` articulados. Anime as juntas por tempo, com
|
||||
curvas suaves: corrida, apoio, chute, comemoração.
|
||||
- Movimento crível: o pé de apoio planta antes do chute, o corpo inclina e o braço contrário
|
||||
balança. A bola sai no instante do contato, com trajetória (parábola) e giro.
|
||||
- Com modelo `.glb` (feito por você ou obtido na internet), coloque em `library/<id>/assets/` e
|
||||
carregue em tempo de execução, porque o render não passa pelo importador do editor:
|
||||
`var doc := GLTFDocument.new(); var st := GLTFState.new(); doc.append_from_file(ProjectSettings.globalize_path("res://library/<id>/assets/x.glb"), st); add_child(doc.generate_scene(st))`.
|
||||
- **Peças prontas em `godot/kits/`** (use antes de modelar do zero):
|
||||
`person.gd` é uma pessoa articulada com poses idle, walk, run, swim, sit, wave, kneel, lie e exhausted;
|
||||
roupa, pele, cabelo, altura e colete são opções; `blend` faz a transição entre poses.
|
||||
`boat.gd` é uma lancha de pesca com balanço e afundamento.
|
||||
- Pessoa real: estilizada e respeitosa (sem caricatura ofensiva). Use a roupa e as cores da época.
|
||||
|
||||
## Reaproveitar uma cena dentro de outra (ex.: náufrago NA ilha)
|
||||
|
||||
Para pôr um personagem, barco ou ação dentro de um cenário que já existe, use a cena existente
|
||||
como cenário em vez de refazer:
|
||||
|
||||
```gdscript
|
||||
const Island := preload("res://library/island/template.gd")
|
||||
var island := Island.new()
|
||||
add_child(island)
|
||||
# embedded: a ilha não cria câmera (a sua cena cria); céu, mar e luz continuam vindo dela.
|
||||
island.setup({"params": {"time": "night", "embedded": true}, "video": cfg.video}, viewport_size)
|
||||
# em apply(t): island.apply(t) (anima o mar e o farol)
|
||||
var y := island.ground_at(x, z) # altura da malha desenhada: o personagem pisa aqui
|
||||
var farol := island.lighthouse_position()
|
||||
```
|
||||
|
||||
O nível do mar é y = 0. A ilha tem cerca de 160 × 84 m, com o centro em (0, 0, 0), e o costão
|
||||
fica onde `height_at` passa de 0. A hora vai em `time`: "day", "sunset" ou "night".
|
||||
|
||||
## Exemplo completo
|
||||
|
||||
`godot/library/island/` é a referência. Ela mostra terreno por ruído com semente, mata em
|
||||
`MultiMesh`, mar por shader com `uniform scene_time`, céu e névoa, quatro tomadas de câmera e
|
||||
`variant`. Copie a estrutura, não o conteúdo.
|
||||
@@ -0,0 +1,71 @@
|
||||
# Publicação nas redes — pesquisa de 17/11/2026
|
||||
|
||||
[C] = confirmado em página oficial · [S] = fonte secundária / a testar. Reverificar a cada 3 meses.
|
||||
|
||||
## YouTube (Data API v3)
|
||||
|
||||
- **Projeto não verificado já publica público** desde 02/11/2026 (revision history) [C]. Sem `privacyStatus` ⇒ `public`.
|
||||
- Cota: desde 01/06/2026 `videos.insert` tem balde próprio de **100/dia** (custo 1); demais chamadas 10.000 unidades; zera meia-noite PT [C].
|
||||
- OAuth: cliente **"Desktop app"**, redirect loopback `http://127.0.0.1:<porta>` (qualquer porta), **PKCE sempre** [C]. Escopo mínimo `youtube.upload`.
|
||||
- Upload resumable (`uploadType=resumable`), `video/*` [C].
|
||||
- Metadados: `snippet.title/description/tags`; `status.privacyStatus`, `publishAt` (exige `private` e nunca publicado), `selfDeclaredMadeForKids`, **`containsSyntheticMedia`** [C].
|
||||
- `thumbnails.set` aceita capa personalizada em Shorts desde 03/11/2026, depois do processamento [C].
|
||||
- Vira Short: ≤ 3 min e vertical/quadrado; não existe campo "isShort" [C].
|
||||
- Tokens: app em **"Testing" expira autorização em 7 dias** (inclui refresh). Colocar o app em **"In production"** (mesmo sem verificação) resolve; aparece tela "app não verificado"; teto 100 usuários — irrelevante [C].
|
||||
- Libs: `google-api-python-client` 2.202.0, `google-auth-oauthlib` 1.5.0 (PyPI); `googleapis` 190.0.0 (npm) [C].
|
||||
|
||||
## TikTok (Content Posting API)
|
||||
|
||||
- OAuth desktop: host `localhost`/`127.0.0.1` com porta (curinga `*` aceito); **PKCE obrigatório, S256 com desafio em hex** do SHA-256 [C].
|
||||
- Access token 2 h; refresh 180 d **rotativo** — gravar sempre o novo [C].
|
||||
- Direct Post (`video.publish`): chamar antes `POST /v2/post/publish/creator_info/query/`. Campos: `title` (≤2200), `privacy_level` (obrigatório, vindo do creator_info), `disable_comment/duet/stitch`, `video_cover_timestamp_ms`, `brand_content_toggle`, `brand_organic_toggle`, **`is_aigc`** [C].
|
||||
- Rascunho (`video.upload`): `/v2/post/publish/inbox/video/init/`; vai para a caixa de entrada do app; máx. **5 pendentes/24 h** [C]. Funciona sem auditoria [S].
|
||||
- FILE_UPLOAD: PUT em blocos 5–64 MB (último até 128 MB), ≤ 4 GB, ≤ 10 min, 23–60 fps, `upload_url` vale 1 h. PULL_FROM_URL exige domínio verificado ⇒ **usar FILE_UPLOAD** [C].
|
||||
- 6 req/min por token; erro `spam_risk_too_many_posts` [C].
|
||||
- **Sem auditoria: só `SELF_ONLY`, a conta precisa estar privada, máx. 5 usuários/24 h** [C].
|
||||
- UI exigida pelo TikTok: mostrar apelido do criador; privacidade escolhida à mão **sem padrão**; interações desmarcadas; divulgação comercial; prévia; declaração de uso de música; sem marca d'água [C].
|
||||
- **Auditoria provavelmente negada**: a TikTok lista como inaceitável "utility tool to help upload contents to the account(s) you or your team manages" e apps de uso interno/privado [C].
|
||||
|
||||
## Instagram (Reels)
|
||||
|
||||
- Conta **Profissional** (Business/Creator) [C].
|
||||
- **Instagram API with Instagram Login**: sem Página do Facebook; host `graph.instagram.com`; escopos `instagram_business_basic`, `instagram_business_content_publish` [C].
|
||||
- Facebook Login for Business: exige Página; `graph.facebook.com` + `rupload.facebook.com` [C].
|
||||
- Upload resumable com **arquivo local** (rupload) é documentado "só para Facebook Login for Business"; com Instagram Login precisaria de `video_url` pública. Blogs mostram rupload funcionando com `graph.instagram.com` [C/S — **testar**].
|
||||
- Fluxo: container `media_type=REELS` → (rupload) → consultar `status_code` 1×/min até 5 min → `media_publish`; container expira em 24 h [C].
|
||||
- Campos: `caption`, `cover_url`, `thumb_offset`, `share_to_feed`, `audio_name`, `collaborators` (≤3), `trial_params`, **`is_ai_generated`** [C].
|
||||
- Vídeo: MP4/MOV com moov no início, H.264/HEVC, 23–60 fps, 3 s–15 min, ≤ 300 MB, 9:16 recomendado [C].
|
||||
- Limite: 100 posts/24 h (a página também cita 50); consultar `/content_publishing_limit` [C].
|
||||
- Conta própria ("I own or manage"): Standard Access, **sem App Review** [C].
|
||||
- Token longo 60 d, renovável por `refresh_access_token` (> 24 h de idade) [C].
|
||||
- Redirect precisa bater exatamente; a Meta **não aceita localhost** e pede HTTPS [S] ⇒ usar token gerado no painel de desenvolvedor.
|
||||
|
||||
## Modo sessão logada (sem API)
|
||||
|
||||
- **Viola os termos das três redes** (YouTube: "qualquer meio automatizado"; TikTok: "automated scripts"; Instagram: automação sem permissão) — risco de bloqueio/checkpoint é do usuário.
|
||||
- Bibliotecas: `tiktok-uploader` v1.2.0 (fev/2026, parada); `instagrapi` 3.2.15 (API privada do app móvel — **maior risco, não usar**); `youtube_uploader_selenium` (abandonada); `social-auto-upload` (depende de burla de detecção — **descartar**).
|
||||
- Abordagem honesta: Playwright com perfil **próprio e vazio** (automatizar o perfil padrão do Chrome não é suportado), navegador visível, **usuário loga à mão**, nunca automatizar senha/captcha.
|
||||
- O Google costuma bloquear login em navegador controlado por automação ("This browser or app may not be secure") [S] ⇒ abrir Chrome/Edge **normal** com `--user-data-dir` dedicado, o usuário loga, e só depois conectar via `connectOverCDP`.
|
||||
- Sessão expirada: redirecionamento para login, botão "Entrar/Log in" por role, ou ausência do campo de arquivo/botão "Criar".
|
||||
- Seletores: `getByRole`/`getByLabel`/`getByText` em PT e EN; screenshot e trace na falha; teste de fumaça que só abre a tela de upload. As telas mudam com frequência [S].
|
||||
|
||||
## Comparativo
|
||||
|
||||
| | Publica | Limitações | Risco |
|
||||
|---|---|---|---|
|
||||
| YouTube API | público, privado, agendado, Short automático | 100/dia; tela "não verificado" | baixo |
|
||||
| YouTube sessão | o mesmo pelo Studio | login Google pode ser bloqueado; UI muda | alto (termos) |
|
||||
| TikTok API | rascunho no app; Direct Post só SELF_ONLY sem auditoria | 5 rascunhos/24 h | baixo |
|
||||
| TikTok sessão | post público | captcha; UI instável | alto (termos) |
|
||||
| Instagram API | Reel público, capa, rótulo IA | token 60 d; rupload a testar | baixo |
|
||||
| Instagram sessão | Reel pelo site | checkpoints frequentes | alto (termos) |
|
||||
|
||||
## Fontes
|
||||
|
||||
developers.google.com/youtube/v3/revision_history · /docs/videos/insert · /docs/videos · /determine_quota_cost ·
|
||||
developers.google.com/identity/protocols/oauth2/native-app · support.google.com/cloud/answer/15549945 ·
|
||||
support.google.com/youtube/answer/15424877 · developers.tiktok.com/doc/content-posting-api-reference-direct-post ·
|
||||
/content-posting-api-reference-upload-video · /content-posting-api-media-transfer-guide · /content-sharing-guidelines ·
|
||||
/login-kit-desktop · /oauth-user-access-token-management · developers.facebook.com/docs/instagram-platform/content-publishing ·
|
||||
/content-publishing/resumable-uploads · /instagram-api-with-instagram-login · /app-review ·
|
||||
playwright.dev/docs/api/class-browsertype#browser-type-launch-persistent-context
|
||||
@@ -0,0 +1,246 @@
|
||||
# Publicação automática — plano e contratos (17/11/2026)
|
||||
|
||||
Documento-fonte para quem implementa. Pesquisa das plataformas: [PESQUISA.md](PESQUISA.md).
|
||||
Identificadores de código em inglês; textos de UI, comentários e mensagens em português.
|
||||
|
||||
## 1. O que o usuário pediu
|
||||
|
||||
- **Canal de publicação**: agrupa perfis de **YouTube, TikTok e Instagram**. É a entidade que hoje se chama
|
||||
"Conta" no painel (tabela `accounts`). Na UI passa a se chamar **"Canal de publicação"**. No Clipador, os
|
||||
streamers de onde saem os cortes passam a se chamar **"Fontes"** na UI (o código e as rotas continuam `channels`).
|
||||
- Um canal de publicação é ligado a **histórias** e a **fontes do Clipador** (vínculos já existem:
|
||||
`account_stories`, `account_channels`).
|
||||
- Quando um vídeo é **aprovado** ele é publicado nas redes do canal. Cada canal tem **aprovação automática**
|
||||
(liga/desliga) e **quando publicar**: "na hora" ou "próximo horário bom", com **limite de vídeos por dia por rede**.
|
||||
- **Dois modos de conexão em cada rede, escolhidos pelo usuário perfil a perfil** (sem padrão imposto):
|
||||
- **API oficial** (OAuth / token).
|
||||
- **Sessão logada** (sem API): o usuário faz login à mão num Chrome/Edge normal; a sessão fica salva e o sistema
|
||||
publica pelo site usando essa sessão.
|
||||
- Nova aba **Configurações** no painel.
|
||||
- **Design acessível e fácil de entender** (requisito explícito).
|
||||
|
||||
## 2. Arquitetura
|
||||
|
||||
```
|
||||
navegador ──► Painel Next (4500) ──────────────► Publicador Python (4530) ──► YouTube / TikTok / Instagram
|
||||
cérebro: canais, regras, executor: cofre de tokens, (API oficial OU
|
||||
fila de publicação, despachante OAuth, perfis de navegador, navegador via CDP 4540–4549)
|
||||
(laço em instrumentation.ts) jobs de envio com progresso
|
||||
│
|
||||
└──► Clipador (4520): lê cortes ready/approved, aprova (PATCH) e marca published
|
||||
```
|
||||
|
||||
- **Painel = cérebro.** Dono da verdade: canais, configurações, fila (`publish_jobs`). Um laço único
|
||||
(`panel/src/instrumentation.ts`, protegido por `globalThis` contra duplicação no HMR) roda a cada 20 s.
|
||||
**O painel precisa estar aberto para publicar/agendar** — a UI diz isso.
|
||||
- **Publicador = executor** (`publisher/`, Python FastAPI, porta **4530**, chave `X-Service-Key` como o Clipador).
|
||||
Não sabe o que é canal/história/corte: recebe um job com arquivo + metadados + perfil e devolve progresso/resultado.
|
||||
Guarda os segredos (cofre DPAPI) e os perfis de navegador. Jobs persistem no SQLite dele; um worker por vez.
|
||||
- **Perfil** = (canal, rede). `profileId = "<accountId>--<platform>"` (ex.: `historias-do-litoral--youtube`).
|
||||
|
||||
### Regras de segurança e honestidade (valem para todos)
|
||||
|
||||
- Modo sessão: **navegador visível**, o **usuário loga à mão** (2FA normal). Proibido: automatizar senha,
|
||||
resolver captcha, "stealth"/burla de detecção, patchright, stealth.js. Um envio por vez, ritmo humano.
|
||||
Login pedido / captcha / checkpoint ⇒ job para em `needs_login` e o usuário é avisado. Não tentar contornar.
|
||||
- O modo sessão viola os termos das três redes (risco de bloqueio da conta): a UI mostra esse aviso **antes** de
|
||||
conectar e pede confirmação explícita.
|
||||
- Segredos nunca voltam para o navegador (a API diz só `configured: true/false`). Tokens no cofre DPAPI
|
||||
(`CryptProtectData`, escopo do usuário Windows) em `data/publisher/`.
|
||||
- Nunca dizer "publicado" sem URL/ID remoto confirmado. Com aprovação automática desligada nada sai sem aprovação humana.
|
||||
|
||||
## 3. Publicador (`publisher/`, porta 4530) — contrato HTTP
|
||||
|
||||
Todas as rotas exigem `X-Service-Key`, exceto `GET /health` e `GET /oauth/callback/{platform}` (validada por `state`).
|
||||
Erros: `{ "detail": "<mensagem em pt-BR>" }` com 4xx/5xx. Campos JSON em camelCase.
|
||||
|
||||
| Método e rota | Corpo → Resposta |
|
||||
|---|---|
|
||||
| `GET /health` | `{ ok: true }` |
|
||||
| `GET /v1/status` | `{ browser: { found: bool, kind: "chrome"\|"msedge"\|null, path }, worker: "idle"\|"busy", queue: int }` |
|
||||
| `GET /v1/apps` | `{ youtube: AppState, tiktok: AppState, instagram: AppState }` — `AppState = { configured: bool, clientId: string\|null, redirectUri: string, notes: string }` (sem segredo) |
|
||||
| `PUT /v1/apps/{platform}` | `{ clientId, clientSecret }` → `AppState` |
|
||||
| `DELETE /v1/apps/{platform}` | → `AppState` |
|
||||
| `GET /v1/profiles/{profileId}` | → `Profile` |
|
||||
| `POST /v1/profiles/{profileId}/connect` | `{ platform, mode: "official"\|"session" }` → `{ profile: Profile, next: Next }` |
|
||||
| `POST /v1/profiles/{profileId}/token` | `{ accessToken }` (Instagram oficial: token colado) → `Profile` |
|
||||
| `POST /v1/profiles/{profileId}/session/check` | confere a sessão (abre a página de upload e verifica login) → `Profile` |
|
||||
| `POST /v1/profiles/{profileId}/session/open` | reabre a janela para o usuário relogar → `{ profile, next }` |
|
||||
| `DELETE /v1/profiles/{profileId}` | desconecta: apaga tokens e o diretório do perfil de navegador → `Profile` |
|
||||
| `GET /v1/profiles/{profileId}/tiktok/creator-info` | (TikTok oficial) → `{ nickname, privacyOptions: string[], maxDurationS, commentDisabled, duetDisabled, stitchDisabled }` |
|
||||
| `POST /v1/jobs` | `JobInput` → `Job` (201) |
|
||||
| `GET /v1/jobs/{jobId}` | → `Job` |
|
||||
| `POST /v1/jobs/{jobId}/cancel` | → `Job` (só se ainda `queued`) |
|
||||
| `GET /oauth/callback/{platform}` | troca `code` por token; devolve HTML simples "Conectado, pode fechar esta aba" |
|
||||
|
||||
```ts
|
||||
type Profile = {
|
||||
profileId: string; platform: "youtube" | "tiktok" | "instagram";
|
||||
mode: "official" | "session" | null;
|
||||
status: "disconnected" | "connecting" | "connected" | "needs_login" | "expired" | "error";
|
||||
displayName: string | null; handle: string | null; // lidos da rede quando possível
|
||||
connectedAt: string | null; expiresAt: string | null; // ISO; expiresAt = validade do refresh/token longo
|
||||
lastCheckAt: string | null; lastError: string | null;
|
||||
};
|
||||
type Next =
|
||||
| { kind: "open_url"; url: string } // painel abre em nova aba (OAuth YouTube/TikTok)
|
||||
| { kind: "paste_token"; help: string } // Instagram oficial
|
||||
| { kind: "browser_opened"; help: string } // modo sessão: janela aberta, usuário loga e clica "Já entrei"
|
||||
| { kind: "none" };
|
||||
type JobInput = {
|
||||
profileId: string; platform: "youtube" | "tiktok" | "instagram";
|
||||
file: string; // caminho ABSOLUTO do MP4 (dentro da raiz do projeto — o serviço confere)
|
||||
cover: string | null; // caminho absoluto de JPG/PNG ou null
|
||||
title: string; // YouTube: título (≤100); TikTok/Instagram: ignorado (usam caption)
|
||||
caption: string; // descrição / legenda com hashtags (≤2200)
|
||||
tags: string[];
|
||||
privacy: "public" | "unlisted" | "private"; // TikTok: public→PUBLIC_TO_EVERYONE, private→SELF_ONLY
|
||||
publishAt: string | null; // só YouTube oficial (agendamento nativo); demais ignoram
|
||||
aiGenerated: boolean; // containsSyntheticMedia / is_aigc / is_ai_generated
|
||||
madeForKids: boolean; // YouTube
|
||||
tiktokMode: "direct" | "draft"; // TikTok oficial: direct = Direct Post; draft = inbox
|
||||
};
|
||||
type Job = {
|
||||
jobId: string; profileId: string; platform: string;
|
||||
status: "queued" | "running" | "done" | "failed" | "needs_login" | "canceled";
|
||||
step: string; // texto curto em pt-BR para a UI ("Enviando vídeo…", "Aguardando processamento…")
|
||||
progress: number; // 0..1
|
||||
remoteId: string | null; url: string | null;
|
||||
draft: boolean; // true = foi para rascunho/inbox (TikTok draft), não está público
|
||||
error: string | null; createdAt: string; updatedAt: string;
|
||||
};
|
||||
```
|
||||
|
||||
### Implementação por rede
|
||||
|
||||
| Rede | Oficial | Sessão logada |
|
||||
|---|---|---|
|
||||
| YouTube | Cliente OAuth "Desktop app", PKCE, redirect `http://127.0.0.1:4530/oauth/callback/youtube`, escopo `youtube.upload` (+`youtube.readonly` p/ nome do canal). `videos.insert` resumable; `status.containsSyntheticMedia`, `selfDeclaredMadeForKids`, `publishAt` (com `private`). Capa via `thumbnails.set` depois do processamento. Refresh token. | `studio.youtube.com` → Criar → Enviar vídeos |
|
||||
| TikTok | Login Kit desktop, PKCE S256 **com desafio em hex**, redirect `http://127.0.0.1:4530/oauth/callback/tiktok`, escopos `user.info.basic,video.upload,video.publish`. `creator_info/query` antes; FILE_UPLOAD em blocos (5–64 MB). `draft` → `/v2/post/publish/inbox/video/init/`. Access 2 h; refresh 180 d **rotativo (gravar o novo sempre)**. Sem auditoria: Direct Post só `SELF_ONLY` — o serviço devolve isso no `step`/erro de forma clara. | `tiktok.com/tiktokstudio/upload` |
|
||||
| Instagram | **Token colado** (gerado no painel de desenvolvedor da Meta — Instagram API with Instagram Login; a Meta não aceita redirect localhost). Container `media_type=REELS` → upload resumable `rupload` com o arquivo local (testar com `graph.instagram.com`; se a rede recusar, erro claro dizendo que é preciso Facebook Login for Business) → polling `status_code` → `media_publish`. Token longo 60 d, renovar com `refresh_access_token` quando faltar < 10 d. | `instagram.com` → Criar → Reel |
|
||||
|
||||
**Modo sessão (comum às três):** localizar Chrome (preferido) ou Edge instalado; abrir como processo normal com
|
||||
`--user-data-dir=data/publisher/browser/<profileId> --remote-debugging-port=<livre em 4540–4549> --no-first-run`;
|
||||
conectar com Playwright Python `connect_over_cdp` (só o driver; não baixa navegador). Seletores por role/label/texto
|
||||
(PT e EN), screenshot em `data/publisher/logs/` quando falhar. Sessão expirada = página de login, botão "Entrar/Log in"
|
||||
ou ausência do campo de arquivo ⇒ `needs_login`. Um job por vez. Depois de publicar, ler a URL do vídeo se a tela
|
||||
mostrar; se não, `remoteId = null`, `url = null` e `step` explica ("publicado; link não encontrado na tela").
|
||||
|
||||
**Infra:** `publisher/.env` (`PUBLISHER_SERVICE_KEY`, `PUBLISHER_PORT=4530`), `publisher/.env.example`, `.venv`,
|
||||
`requirements.txt` com versões fixas, `pytest` com chamadas de rede simuladas. Entra em `scripts/dev.ts` (depois
|
||||
do Clipador, pula com aviso se faltar `.venv`/chave), `scripts/setup.ps1` (venv + chave) e `package.json`
|
||||
(`test:publisher`). Dados em `data/publisher/` (`publisher.db`, `vault`, `browser/`, `logs/`).
|
||||
|
||||
## 4. Painel — dados (migração v5 em `panel/src/lib/db.ts`)
|
||||
|
||||
- `account_networks`: o `status` deixa de ser `'mock'` → `'disconnected'|'connecting'|'connected'|'needs_login'|'expired'|'error'`
|
||||
(migrar `mock` → `disconnected`); novas colunas `mode TEXT NULL ('official'|'session')`, `enabled INTEGER DEFAULT 1`,
|
||||
`daily_limit INTEGER DEFAULT 3`, `privacy TEXT DEFAULT 'public'`, `tiktok_mode TEXT DEFAULT 'direct'`,
|
||||
`display_name TEXT`, `last_error TEXT`, `checked_at TEXT`. `handle` passa a aceitar NULL até a rede informar.
|
||||
- `accounts`: `approval_mode TEXT DEFAULT 'manual' ('manual'|'auto')`, `timing TEXT DEFAULT 'best_slot' ('now'|'best_slot')`,
|
||||
`ai_label TEXT DEFAULT 'auto' ('auto'|'always'|'never')`.
|
||||
- `publish_jobs`: `id, account_id, platform, source_kind ('clip'|'episode'), source_id TEXT, file, cover, title, caption,
|
||||
status ('awaiting_approval'|'scheduled'|'queued'|'publishing'|'published'|'failed'|'needs_login'|'canceled'),
|
||||
scheduled_at, publisher_job_id, step, progress, remote_id, url, draft, error, attempts, created_at, updated_at`,
|
||||
`UNIQUE(account_id, platform, source_kind, source_id)`.
|
||||
- `publications`: `episode_id` passa a NULL-ável, nova coluna `clip_id INTEGER`, `job_id`. Registro real (`simulated=0`) ao publicar.
|
||||
- `episodes`: `approved_at TEXT`, `approved_render_id INTEGER`, `publish_title TEXT`, `publish_caption TEXT`.
|
||||
- `app_settings(key PRIMARY KEY, value)`: `publishing_paused` (0/1), `slots` (JSON por rede, horário de Brasília —
|
||||
padrão: youtube 12:00/15:00/19:00, tiktok 08:00/12:00/19:00/21:00, instagram 12:00/19:00/21:00), `timezone`.
|
||||
|
||||
## 5. Painel — despachante (laço de 20 s)
|
||||
|
||||
1. **Cortes:** busca no Clipador os cortes `ready` e `approved` das fontes ligadas a canais ativos.
|
||||
- `ready` + canal com `approval_mode=auto` ⇒ aprova no Clipador (`PATCH status=approved`) e cria jobs.
|
||||
- `ready` + canal manual ⇒ cria job `awaiting_approval` (aparece em "Aguardando aprovação").
|
||||
- `approved` (por humano) ⇒ jobs `awaiting_approval` desse corte viram agendados/na fila.
|
||||
- Corte que **voltou para `pending`** (editado/exportado) ou foi rejeitado/apagado ⇒ cancela jobs ainda não enviados.
|
||||
2. **Episódios:** botão "Aprovar para publicar" (exige render final) cria os jobs; com canal `auto`, aprovar o render final
|
||||
já cria os jobs aprovados.
|
||||
3. **Agendar:** `timing=now` ⇒ `queued`. `best_slot` ⇒ próximo horário livre da rede em `slots`, respeitando `daily_limit`
|
||||
(conta publicados + agendados no dia) e espaçando ≥ 1 h na mesma rede/canal. YouTube oficial pode usar `publishAt`.
|
||||
4. **Enviar:** jobs `queued` (ou `scheduled` vencido) com perfil `connected`/`enabled` e sem `publishing_paused` ⇒
|
||||
`POST /v1/jobs` no Publicador; acompanha `GET /v1/jobs/{id}` até terminar; grava `step/progress`.
|
||||
5. **Terminar:** `done` ⇒ `published`, grava `publications` (real) e, se todos os jobs do corte terminaram, marca o corte
|
||||
`published` no Clipador. `needs_login` ⇒ perfil `needs_login`. `failed` ⇒ `failed` com erro e botão "Tentar de novo".
|
||||
6. **Legenda:** corte = `title`/`caption` do Clipador (crédito já vem no fim). Episódio = `publish_title`/`publish_caption`.
|
||||
`aiGenerated`: `always`/`never` pelo canal; `auto` = true só se o episódio usa voz RVC de personagem/voz clonada.
|
||||
|
||||
### API do painel (rotas novas; padrão `errorResponse`)
|
||||
|
||||
- `GET/PUT /api/settings` — `{ publishingPaused, slots, timezone }`.
|
||||
- `GET/PUT/DELETE /api/settings/apps/[platform]` — repassa ao Publicador (sem segredo na resposta).
|
||||
- `GET /api/publisher/status` — saúde do Publicador + navegador encontrado.
|
||||
- `PATCH /api/accounts/[id]` — aceita também `approvalMode`, `timing`, `aiLabel`.
|
||||
- `PUT /api/accounts/[id]/networks/[platform]` — `{ enabled?, dailyLimit?, privacy?, tiktokMode? }`.
|
||||
- `POST /api/accounts/[id]/networks/[platform]/connect` `{ mode }` → `{ network, next }`;
|
||||
`.../token` `{ accessToken }`; `.../check`; `.../reopen`; `DELETE .../networks/[platform]` desconecta.
|
||||
- `GET /api/publishing/jobs?status=&accountId=` → lista; `POST /api/publishing/jobs/[id]/(approve|publish-now|retry|cancel)`;
|
||||
`PATCH /api/publishing/jobs/[id]` `{ scheduledAt?, title?, caption? }`.
|
||||
- `POST /api/episodes/[id]/approve` `{ renderId, title, caption }`; `DELETE` desfaz.
|
||||
- `GET /api/publishing/summary` — contagens por status (para o menu e o dashboard).
|
||||
|
||||
## 6. Painel — telas (acessíveis)
|
||||
|
||||
- **Menu:** Distribuição → "Canais de publicação" (rota `/accounts`) e "Publicações" (`/publishing`, com contador de
|
||||
"aguardando aprovação"); rodapé → "Configurações" (`/settings`).
|
||||
- **Canais de publicação:** cartão por canal com as três redes. Cada rede mostra estado em palavras e ícone (nunca só
|
||||
cor): "Não conectado", "Conectado como @x", "Precisa entrar de novo", "Erro: …". Botão **Conectar** abre um passo a
|
||||
passo: 1) escolher o modo — dois cartões lado a lado, "Conta oficial (API)" vs "Sessão logada", com prós, contras e o
|
||||
aviso de termos; 2) instruções do modo (abrir login / colar token / "Já entrei"); 3) conferência. Configurações do
|
||||
canal em linguagem simples: "Aprovar sozinho os vídeos novos?" (Switch), "Quando publicar?" (Na hora / No próximo
|
||||
horário bom), "Máximo por dia" por rede, privacidade, rótulo de IA.
|
||||
- **Publicações:** abas "Aguardando aprovação", "Agendadas", "Publicando", "Publicadas", "Com problema". Cada item: capa,
|
||||
título, canal, rede, horário, estado em texto, progresso; ações: Aprovar, Publicar agora, Mudar horário, Cancelar,
|
||||
Tentar de novo, Entrar de novo. Aviso fixo se o Publicador estiver desligado ou "publicação pausada".
|
||||
- **Configurações:** abas "Publicação" (pausar tudo, horários bons por rede, fuso), "Apps das redes" (passo a passo para
|
||||
criar o app de cada rede, campos de Client ID/Secret, redirect pronto para copiar, estado configurado/não), "Navegador"
|
||||
(navegador encontrado, onde ficam as sessões, aviso de termos) e "Sobre os modos".
|
||||
- **Clipador:** "Canais" → "Fontes" nos textos; aba Aprovados mostra o estado da publicação por rede.
|
||||
- **Histórias/episódio:** botão "Aprovar para publicar" com prévia do vídeo final, título e legenda editáveis e os
|
||||
canais que vão receber.
|
||||
- **Acessibilidade:** WCAG 2.2 AA — contraste ≥ 4,5:1, foco visível, tudo por teclado, `aria-live` para progresso e
|
||||
resultados, rótulos em todos os campos, alvos ≥ 24 px, texto simples (sem jargão; "API"/"OAuth" só com explicação).
|
||||
|
||||
## 7. Divisão do trabalho
|
||||
|
||||
| Parte | Quem | Arquivos (dono exclusivo) |
|
||||
|---|---|---|
|
||||
| A — Publicador | agente geral | `publisher/**`, `scripts/dev.ts`, `scripts/setup.ps1`, `package.json` (raiz), `start.bat` |
|
||||
| B — Painel back-end | agente geral | `panel/src/lib/**`, `panel/src/app/api/**`, `panel/src/instrumentation.ts`, `clipper/**` (só se faltar algo) |
|
||||
| C — Painel UI | `cenaforge-dashboard-designer` | `panel/src/app/**/page.tsx` e layouts, `panel/src/components/**` |
|
||||
| D — Revisão + skill | revisores + `cenaforge-skill-updater` | só leitura / skill |
|
||||
|
||||
Regras: o painel (`pnpm panel`) é do usuário — não iniciar, não encerrar, não rodar `next build`; use
|
||||
`pnpm --filter cenaforge-panel typecheck`. Next.js 16 tem mudanças incompatíveis: ler `panel/node_modules/next/dist/docs/`
|
||||
antes. Portas só 4500–4599.
|
||||
|
||||
## 7b. Ajustes depois da revisão (17/11/2026)
|
||||
|
||||
- **Migração v6** do painel: `publish_jobs.schedule_source` (agendamento automático × manual) e `cancel_reason = 'unlinked'`.
|
||||
- **Idempotência:** `JobInput.clientRef` (≤ 80) = `"<publish_jobs.id>:<attempts>"`. O Publicador guarda UNIQUE e, com
|
||||
clientRef repetido, devolve **200** com o job existente (201 = novo). `attempts` só sobe em retry explícito.
|
||||
- `PublishJob.mayBeLive`: retry exige `{ confirm: true }` (409 sem) — conferir na rede antes de reenviar.
|
||||
- Agendamento automático vencido há > 30 min é reencaixado; encerrar fonte/história cancela jobs não enviados.
|
||||
- Publicador aceita `file`/`cover` só de `output/`, `stories/`, `assets/`.
|
||||
- API do painel protegida por `panel/src/proxy.ts`: Host local; métodos de escrita exigem `Origin` do mesmo host e
|
||||
`Content-Type: application/json`. **Script/curl:** mande `-H "Origin: http://127.0.0.1:4500" -H "Content-Type: application/json"`.
|
||||
|
||||
## 7c. "Publicar" no cartão do corte (17/11/2026)
|
||||
|
||||
- Corte **aprovado** (ou já publicado) no Clipador ganha o botão **Publicar** (aba Aprovados). O diálogo pede o canal de
|
||||
publicação, as redes (só as conectadas e ligadas; as que já têm o corte publicado, na fila ou em envio ficam
|
||||
desmarcadas com o motivo) e **quando sai** (agora ou no próximo horário bom). Título e legenda são os do cartão.
|
||||
- `POST /api/publishing/clips/[id]` `{accountId, platforms[], timing?: "now"|"best_slot"}` → `{jobs, skipped[{platform, reason}], placed}`.
|
||||
O clique é a aprovação humana. "Agora" ignora horário bom e limite do dia (como "Publicar agora").
|
||||
- **Não precisa ligar a fonte ao canal.** Banco **v7**: `publish_jobs.origin` = `link` (despachante, pelo vínculo) |
|
||||
`manual` (este botão). Job manual não é cancelado por "fonte desligada" (`planClipSync`, `linkActive`, `endChannel`);
|
||||
continua cancelado se o corte for editado, rejeitado ou apagado.
|
||||
|
||||
## 8. Pronto quando
|
||||
|
||||
- [ ] Publicador sobe pelo `pnpm dev`, `pytest` verde, typecheck do painel e da raiz verdes.
|
||||
- [ ] Conectar cada rede nos dois modos pela UI (fluxo completo até "Conectado" ou erro claro).
|
||||
- [ ] Corte aprovado (manual e automático) vira job, respeita horário/limite, sai e grava `publications` real.
|
||||
- [ ] Episódio aprovado idem.
|
||||
- [ ] Teste real de envio em pelo menos uma rede com conta do usuário (depende das credenciais dele).
|
||||
@@ -0,0 +1,68 @@
|
||||
# Guia de roteiro — regras comuns (todos os formatos)
|
||||
|
||||
Fonte única de regras de texto do CenaForge. Vale para **qualquer IA** que escreva roteiro:
|
||||
o Codex (pelo prompt do painel) e o subagente `cenaforge-story-writer` do Claude leem estes
|
||||
mesmos arquivos. Leia este e depois o guia do formato da história:
|
||||
|
||||
| Formato (`kind` no painel) | Guia |
|
||||
|---|---|
|
||||
| `interactive` — interativa, com votação | [ficcao.md](ficcao.md) |
|
||||
| `linear` — ficção em sequência, sem votação | [ficcao.md](ficcao.md) |
|
||||
| `documentary` — vídeo único sobre fatos reais | [documental.md](documental.md) |
|
||||
|
||||
O formato vem no pedido. Se não vier, está na primeira linha de `stories/<id>/biblia.md`
|
||||
(`Formato: interativa | linear | documental`). Na dúvida, pergunte em vez de supor.
|
||||
|
||||
## Idioma e tom
|
||||
|
||||
- Português do Brasil, natural e falado, para público amplo.
|
||||
- Vídeo vertical (9:16), curto. Narração: ~2,5 palavras por segundo de cena.
|
||||
- Na narração (o que a voz fala), números por extenso ("cinco", não "5"); no texto na tela,
|
||||
algarismos. Parágrafos de narração curtos: o áudio é gerado trecho a trecho.
|
||||
- Sem violência gráfica, sexo ou discurso de ódio. Tensão, humor e curiosidade, sim.
|
||||
|
||||
## Onde ler e onde escrever
|
||||
|
||||
- Antes de escrever, leia `stories/<id>/` (bíblia e episódios anteriores), se existir. Mantenha
|
||||
continuidade de nomes, fatos, tom e consequências.
|
||||
- Escreva **somente** dentro de `stories/<id>/`:
|
||||
- `biblia.md` — primeira linha `Formato: <formato>`; o resto segue o guia do formato;
|
||||
- `<file_key>.md` (ex.: `ep01.md`, `ep02-b.md`) — roteiro, no formato do guia;
|
||||
- `meta.json` — quando o pedido mandar: `{"title": "<até 60 caracteres>", "logline": "<1–2 frases>"}`.
|
||||
- Nunca edite `config/`, `godot/`, `scripts/`, `panel/`, `.claude/` nem a documentação do projeto.
|
||||
Não crie cena JSON nem renderize numa tarefa de roteiro.
|
||||
|
||||
## Estrutura de vídeo curto
|
||||
|
||||
| Bloco | Função |
|
||||
|---|---|
|
||||
| Gancho (0–2 s) | imagem forte + texto na tela: afirmação, pergunta ou ação já em andamento |
|
||||
| Contexto | o mínimo para entender o que está em jogo |
|
||||
| Escalada | cada beat aumenta tensão, graça ou surpresa; troca visual a cada 2–4 s |
|
||||
| Pagamento | a resposta, o susto, a risada — ou a escolha (interativa) |
|
||||
|
||||
Nunca prometa no gancho o que o vídeo não entrega.
|
||||
|
||||
## Limites de texto do contrato JSON (conte os caracteres)
|
||||
|
||||
| Campo | Limite |
|
||||
|---|---|
|
||||
| `overlay.title` | 1–80 caracteres, uma frase curta; ideal ≤ 30 para caber em 2 linhas |
|
||||
| `overlay.choiceA` / `choiceB` | 1–48 caracteres (só ficção interativa); ideal ≤ 24 |
|
||||
| quebra de linha, tabulação | proibidas nesses campos |
|
||||
|
||||
## Produção
|
||||
|
||||
A cena atual do projeto é limitada (rua com o entregador de moto: andar, frear, parar). Tudo que
|
||||
o roteiro pedir além disso (outro cenário, personagem, mapa, foto, animação, boca mexendo) vai na
|
||||
seção **Necessidades de produção**, em vez de fingir que já existe.
|
||||
|
||||
## Economia
|
||||
|
||||
Seja direto: não reescreva a bíblia inteira a cada episódio, só acrescente o que mudou. Não leia
|
||||
arquivos fora de `stories/` e de `doc/roteiro/` a menos que o pedido cite um.
|
||||
|
||||
## Retorno
|
||||
|
||||
Responda em poucas linhas: arquivos escritos, o bloco de overlay (com a contagem de caracteres de
|
||||
cada campo), as fontes (documental) e as necessidades de produção.
|
||||
@@ -0,0 +1,72 @@
|
||||
# Guia de roteiro — documental (formato `documentary`)
|
||||
|
||||
Leia antes [comum.md](comum.md). Um **vídeo único**, vertical, sobre um tema real: um lugar, um
|
||||
fenômeno, um fato histórico, uma curiosidade. Não é série interativa nem ficção. As restrições de
|
||||
[ficcao.md](ficcao.md) **não valem** aqui.
|
||||
|
||||
## Regras
|
||||
|
||||
- **Nomes reais:** cite pelo nome cidades, estados, países, lugares, instituições, espécies e
|
||||
pessoas públicas. É isso que dá credibilidade ao vídeo.
|
||||
- **Fato com fonte:** confira cada afirmação em fonte confiável (instituição científica, órgão
|
||||
público, universidade, imprensa reconhecida) e liste as fontes no roteiro. Número incerto vira
|
||||
"estima-se" ou sai. Fonte que discorda de outra: diga que há divergência.
|
||||
- **Mito × fato:** se o tema tem lenda famosa, conte a lenda como lenda e mostre o que se sabe.
|
||||
- **Sem sensacionalismo** que contrarie as fontes. Pessoas privadas não são citadas pelo nome.
|
||||
- **Duração:** 45–90 s de narração (110–220 palavras), salvo se o pedido indicar outra.
|
||||
- **Narração por trecho:** cada linha da tabela é um parágrafo curto (1 a 2 frases, até ~35
|
||||
palavras). O painel gera um áudio por trecho; parágrafo longo deixa a voz sintética estranha.
|
||||
- **Números na narração por extenso:** "cinco", "trinta e cinco quilômetros", "onze mil anos",
|
||||
"cinquenta e cinco por hectare". A voz lê melhor. Na coluna **Texto na tela**, use algarismos
|
||||
("35 km de Itanhaém"), que é o que o público lê rápido. O painel ainda converte o que escapar.
|
||||
- **Ritmo:** gancho forte nos 2 primeiros segundos; um fato surpreendente a cada 10–15 s; fecho com
|
||||
convite a seguir ou comentar. Sem votação, sem opções A/B.
|
||||
|
||||
## `biblia.md` — ficha de pauta
|
||||
|
||||
```markdown
|
||||
Formato: documental
|
||||
# <tema>
|
||||
## Ângulo (a pergunta que o vídeo responde)
|
||||
## Público e tom
|
||||
## Fatos confirmados
|
||||
| Fato | Fonte (instituição) | Link |
|
||||
## Mitos a desmentir (o que se diz × o que as fontes dizem)
|
||||
## Referências visuais (lugares, mapas, espécies, imagens de arquivo)
|
||||
```
|
||||
|
||||
## Como o vídeo é montado (painel → página do vídeo → Montagem)
|
||||
|
||||
Cada trecho vira um áudio próprio (voz escolhida, texto falado editável) e um visual escolhido
|
||||
pelo admin: **imagem** (com zoom lento), **clipe de vídeo**, **cena 3D do Godot** (vídeo já
|
||||
renderizado) ou **cartela de texto**; dá para misturar no mesmo vídeo. A coluna "Imagem / B-roll"
|
||||
é a orientação para escolher esse visual: descreva o que deve aparecer, de forma que dê para achar
|
||||
em banco livre (Wikimedia Commons, Pexels…) ou fotografar. Animação 2D no Godot ainda não existe.
|
||||
|
||||
## Vídeo todo em 3D (estilo "Tudo em 3D" da montagem)
|
||||
|
||||
Quando o pedido for um vídeo em 3D, cada trecho vira uma cena 3D do Godot (biblioteca em
|
||||
`godot/library/`, guia `doc/godot/cenas.md`), e fotos reais aparecem num **cartão** por cima.
|
||||
- Na coluna **Imagem / B-roll**, descreva a TOMADA 3D: lugar, personagem, ação e câmera
|
||||
(ex.: "Lancha balançando no mar agitado à noite, câmera baixa perto da água").
|
||||
- Quando uma foto real precisar aparecer, marque `[foto: termos de busca]`
|
||||
(ex.: `[foto: Bothrops insularis]`). Use nomes específicos: o nome científico ou o nome do lugar.
|
||||
- Personagem (pessoa real de notícia): descreva roupa, idade aproximada e ação. A cena 3D é
|
||||
estilizada e respeitosa, sem caricatura.
|
||||
- Liste em **Necessidades de produção** as cenas 3D que ainda não existem na biblioteca
|
||||
(ex.: "cena 3D: lancha naufragando perto da ilha à noite"). É a lista de trabalho do agente
|
||||
da tarefa "Cena no Godot".
|
||||
|
||||
## Formato do roteiro (`ep01.md`)
|
||||
|
||||
```markdown
|
||||
# <título do vídeo>
|
||||
Duração alvo: <N> s · Formato: documental (vídeo único)
|
||||
|
||||
## Gancho (0–2 s)
|
||||
## Roteiro cena a cena
|
||||
| t (s) | Imagem / B-roll | Texto na tela | Narração |
|
||||
## Texto de capa / overlay.title (até 80 caracteres, ideal ≤ 30)
|
||||
## Fontes (título, instituição, link e o fato que cada uma sustenta)
|
||||
## Necessidades de produção (cenário, imagens, mapas, animações que a cena atual ainda não faz)
|
||||
```
|
||||
@@ -0,0 +1,47 @@
|
||||
# Guia de roteiro — ficção (formatos `interactive` e `linear`)
|
||||
|
||||
Leia antes [comum.md](comum.md). Histórias animadas curtas, publicadas um episódio por vez
|
||||
(~12 s cada). Na **interativa**, o público escolhe nos comentários o que acontece no próximo
|
||||
episódio. Na **linear**, os episódios seguem em sequência, sem votação.
|
||||
|
||||
## Restrições do produto (não negociáveis)
|
||||
|
||||
- Sem nomes de cidade, bairro real, clube, empresa ou marca. Use bairro fictício de aparência
|
||||
brasileira e apps e lojas com nomes inventados e genéricos.
|
||||
- Sem pessoas reais.
|
||||
- **Interativa:** cada episódio termina numa decisão clara entre ações concretas e diferentes
|
||||
(2 a 4 opções, conforme a história). Nada de opção "certa" óbvia: todas precisam ter custo e graça.
|
||||
- **Linear:** cada episódio termina num gancho para o próximo, sem escolha do público.
|
||||
- Episódio de série abre com recapitulação em 1 frase, para quem chegou agora.
|
||||
|
||||
## `biblia.md`
|
||||
|
||||
```markdown
|
||||
Formato: interativa | linear
|
||||
# <título>
|
||||
## Premissa
|
||||
## Personagens (nome, traço, objetivo)
|
||||
## Lugar
|
||||
## Tom
|
||||
## Regras do mundo
|
||||
## Arco previsto
|
||||
```
|
||||
|
||||
## Formato de `<file_key>.md`
|
||||
|
||||
```markdown
|
||||
# Episódio NN — <título interno>
|
||||
Duração alvo: 12 s · Escolha anterior: <letra e o que foi> (ou "início")
|
||||
|
||||
## Resumo (2–3 frases)
|
||||
## Cena a cena
|
||||
| t (s) | Imagem | Narração / diálogo |
|
||||
## Chamada final
|
||||
## Campos de overlay (copiar para o JSON)
|
||||
{"title": "...", "choiceA": "A — ...", "choiceB": "B — ..."}
|
||||
## Consequência de cada escolha (semente do próximo episódio)
|
||||
## Necessidades de produção (o que a cena atual ainda não faz)
|
||||
```
|
||||
|
||||
Na linear, os campos de overlay têm só `title`, e a seção de consequências vira "Gancho para o
|
||||
próximo episódio". As opções seguem o formato `A — <ação>`, `B — <ação>`.
|
||||
Reference in New Issue
Block a user