marsik641/space-shorts

/make-video — passos 2 a 4: da escolha ao release com merge

Entrada: escolha do utilizador a partir do ficheiro ideas desta worktree («/make-video N» + alterações) ou um objecto nomeado pelo utilizador. Saída = DoD (AGENTS.md, «Pipeline de chats»): out/<ep>/release/ — ficheiro mestre <ep>_en_1080x1920p60.mp4 e publish_en.md, dois ficheiros — entregues ao utilizador; QA visual aceite; tudo comitado; branch merged em main (video_wt.py finish); worktree removida. Padrão — docs/quality.md: cinema, não infografia; factos nas palavras, espectáculo nas imagens; final em até 6 h GPU. Apenas EN, objetivo 29–29,5 s, máximo 30,0 s (docs/shorts_format.md). Links: processo — docs/pipeline.md; aprovação — docs/approval.md; pacote — docs/publish.md; fluxos — docs/workflows.md; biblioteca — docs/spacekit.md; tempos — docs/timings.md; fila — docs/render_queue.md; agentes, commits, aprendizagens — AGENTS.md. Comandos — Git Bash a partir da raiz da sua worktree; <ep> = epNNN_<slug>.

Passo 0 — worktree, fila, commits

• Branch video/epNNN… após /next-video — continuar nela. Chat na cópia principal sem /next-video — python tools/video_wt.py start → Claude EnterWorktree com path / Codex workdir.
• Blender, TTS, música, montagem — apenas através da fila: tarefa submetida — chat continua o trabalho textual.
• Após cada bloco — commit type(<ep>): … com trailer do modelo. Fim do turno — árvore limpa.

Parte A — antes da aprovação

1. Episódio. python tools/video_wt.py claim <slug> (slug — [a-z0-9_], ≤ 16, baseado no nome de catálogo). Copiar episodes/_template/ → episodes/<ep>/, em episode.json — id = nome da pasta, languages: ["en"] (caminhos frames_dir/audio_dir não definir). No final do ficheiro ideas: Selecionado: N, <data>, alterações: …, episódio: <ep>. Commit feat(<ep>): episódio da variante N.
2. Factos: investigador + verificador de factos (docs/workflows.md) → facts.md (cada número com referência, referências visuais). Commit.
3. Briefing visual visual_brief.md (papel «Realizador»): referências, primeiro frame, money shot, paleta, luz, câmara e evento de cada plano, convenções, orçamento. Crítico «Cinema/wow» sobre o briefing → alterações. Commit.
4. Argumento script_9x16.json (EN): 6–8 segmentos, âncoras at (s), 29–29,5 s (≤ 30.0 rigoroso), ≈ 55–70 palavras; primeira frase — gancho factual; final conduz ao início (loop). en_cap — números, | — quebras manuais (docs/pipeline.md, «Legendas e legendas»). Voz do canal — Kokoro af_heart ×0.98. Commit.
5. Cena e planos. system.py (parâmetros reais → ecrã, convenções na docstring); o que faltar — módulos spacekit/ (commit separado feat(spacekit): …, regressão tools/imgdiff.py). shots_9x16.py conforme briefing: 6–10 planos de 2–5 s, cada com ≥ 3 planos de profundidade, chave + contraluz, halo/bloom, movimento de câmara, motion blur, fundo não vazio (docs/quality.md). episode.json (edit, overlays en, legendas em zonas seguras), music_cues.json (tonalidade/modo/ritmo próprio). Colagens — contíguas, em eventos; último frame = primeiro. Σ frames de edição ≤ 1799 a 60 fps. python tools/check_episode.py episodes/<ep>/episode.json. Commit.
6. Pré-visualização de tempos: python tools/render_queue.py submit preview episodes/<ep>/episode.json --with-tts, estado — status --json. Folha out/<ep>/9x16/sheet_prev.png; sem Traceback/OVERRUN, com FLASH/EVENT; lista de cues — python tools/cues.py episodes/<ep>/episode.json --logs out/<ep>/9x16/logs.
7. Hero frames: por plano submit preview … --hero --shots vN --frames F,F+1,F+2 (F — melhor momento do plano; 100 %, sem --samples — amostras do código do plano, como no final) → out/<ep>/9x16/hero/, sheet_hero.png. Aos críticos e dono — frame F; pelo log hero_vN.log — s/frame e ETA (docs/timings.md). Amostras e efeitos pesados ajustar em shots_9x16.py (commit, hero de novo) para que o final demore 4–6 h, e não uma hora.
8. Crítica (docs/workflows.md): «Cinema/wow» (avaliação de planos 1–10, < 8 — refazer, até 3 rondas), composição, ritmo/gancho, factos (apenas 4 bloqueadores docs/quality.md); opc. originalidade, som. Alterações → repetir 6–7. Relatórios em ficheiros no episódio, commit por ronda fix(<ep>): alterações após crítica, ronda K.
9. Vídeo de rascunho completo (docs/approval.md, 1a): função draft nos planos + preview_movie.py do episódio através de submit task. Se não for montado — para aprovação sem ele, na mensagem «vídeo de rascunho: não».
10. Aprovação: mensagem conforme template docs/approval.md + ficheiros (hero frames, vídeo de rascunho). Commit do estado. Para e espera resposta. Alterações — voltar ao passo necessário.

Parte B — após «ok»: até DoD (sem perguntas, exceto paragens de docs/approval.md)

11. Aprovação no histórico. Prontos a lista de cues acordada e publish_en.md conforme docs/publish.md (convenções — em lista). Commit chore(<ep>): aprovado para render (alterações do utilizador — no corpo).
12. Final. python tools/render_queue.py submit final episodes/<ep>/episode.json --approved 'aprovação do utilizador: data, contexto do chat'. A flag regista o consentimento já obtido, não o substitui. Ao utilizador — id da tarefa, PC, ETA. O Worker escolhe o PC, renderiza em porções de 120 frames e executa framecheck, TTS, música, mix, build_edit, montagem, QA automático e release. O chat pode fechar.
13. Estado e falhas. status --json (progresso — cursor/steps; frames até ao fim da tarefa estão no snapshot snapshot, não em out/<ep>/). failed — log do passo no snapshot; falha temporária de ambiente — retry JOB; alteração de código/argumento — cancel JOB, alteração na worktree, se necessário nova aprovação, nova tarefa. Framecheck FAIL — analisar RERENDER, remover maus frames no snapshot (e no remote), retry JOB --rerender-shots vN. pause/resume — entre porções. Não matar o bash superior.
14. QA visual. needs_review = verificações automáticas e pacote prontos. PNG out/<ep>/9x16/qa_en/ e mestre: não pior que hero frames (ruído, desfoque, sobreexposição, cintilação), zonas seguras, legendas, dessincronia, loop. Limpo — python tools/render_queue.py accept JOB; defeito — alteração e nova tarefa.
15. Entrega. Ambos os ficheiros out/<ep>/release/ ao utilizador (Claude — SendUserFile). Originais alterados durante o render — comparar publish do snapshot e JSON de edição antes do commit.
16. Registo. episodes/INDEX.md (planos, técnicas, voz, tonalidade, gancho), tabela de episódios em README.md, ✅ temas em docs/channel.md, medições s/frame em docs/timings.md, lições — nas docs de perfil. Commit docs(<ep>): registo e lições (código do episódio, edit_9x16_en.json, publish_en.md; sem out/).
17. Merge. python tools/video_wt.py finish — limpo → release → accept → git merge main → check_episode e testes → ff main → out/<ep>/ transferido para a cópia principal. Conflito — resolver na worktree, commit, repetir. Depois sair da worktree (Claude — ExitWorktree keep) e da cópia principal python tools/video_wt.py remove epNNN; worktree criada pela app (start --here) não remover. Só agora — «pronto».