motion-build

Construção Papercut

Construa cada episódio a partir da biblioteca em vez de escrever um projeto Remotion do zero. Leia $MOTION_LIB/core/README.md uma vez.

Pré-voo

• Instalação: Standard ou Completa. Precisa da biblioteca, node 20+, npm, ffmpeg, ferramentas Python (numpy, Pillow, soundfile) e Chrome ou Chromium para o render de áudio. Teste com os comandos em motion-explainer; se faltar algo, execute ./install.sh --doctor e passe para motion-setup.
• Biblioteca: $MOTION_LIB, senão a linha MOTION_LIB= em ~/.config/motion-explainer/config.env, senão pergunte uma vez. Sem biblioteca, construa a partir dos esboços em $MOTION_LIB/style/$MOTION_STYLE/remotion/RECIPES.md.
• Carregue a skill de melhores práticas do Remotion primeiro apenas para o engine remotion (remotion-best-practices, do plugin Remotion, ou npx skills add remotion-dev/skills -g -y -a <seu harness id>; install.sh --mode standard faz isso) e siga seu roteamento para marcação, legendas e Studio. Para kyfram, carregue a skill kyfram.
• Precisa de video/STORYBOARD.md e narration/script.json das etapas anteriores.
• Teste rápido de toda a toolchain: $MOTION_LIB/core/tools/selftest.sh constrói examples/hello-reel/ em uma pasta descartável e renderiza um still.

1. Scaffold e Verifique o Engine

O projeto do episódio já deve estar com scaffold feito a partir da etapa de intake / motion-strategy. Verifique video/episode.json para o engine registrado:

• Se ainda não estiver com scaffold, pergunte ao usuário (remotion, fframes ou kyfram) e execute:

  $MOTION_LIB/new_episode.sh <series-dir> NN-slug CompId [out-name] --engine remotion|fframes|kyfram
  

• Comandos de preview a partir de video/:

  • fframes: cargo run --release -- preview (ou instale a CLI: cargo install --locked cargo-fframes)
  • kyfram: renderize uma vez, depois kyfram view out/cache/kyfram/build/<Scene>.lgv (o script compilado: prelúdios + cabeçalho gerado + sua cena)
  • remotion: npx remotion studio (ou npm run dev)

• fframes: o projeto do episódio é um crate Rust (media/, src/main.rs). Renderize com cargo run --release -- render ou $MOTION_LIB/core/tools/render.sh.

• kyfram: o projeto do episódio são scripts .lgv (scenes/, media/fonts/, src/plan.json). Renderize com $MOTION_LIB/core/tools/render.sh (ele faz cache por cena e concatena). Invoque a skill kyfram primeiro.

• remotion: projeto React (src/, package.json). Renderize com npx remotion render <CompId> out/<out>.mp4 ou render.sh.

2. Planeje: episode.json, voz, timing

A partir do storyboard, preencha video/episode.json:

• scenes: [["S01Hook", "l1_hook", 0], ["S02Name", "l2_name", "called"], ...] (id da cena, id da linha de narração, primeira palavra como índice ou a palavra exata).
• banners: {"S01Hook": "TAKEAWAY EM MAIÚSCULO"}. hook: veja motion-hook. cuts: a coluna de cortes da tabela Câmera / Corte. bed, whipScene, cutSfx, gaps (batida extra após uma linha, em segundos).

Em seguida, execute motion-voice através de sua etapa de timing (ela termina com build_vo.py e timing_md.py). Então, a partir de video/:

python3 $MOTION_LIB/core/tools/stubs.py        # gera stubs de cena em múltiplos arquivos baseados no engine

build_vo.py sinaliza qualquer cena com menos de 1,2 s; mescle-a em uma vizinha. timing_md.py escreve a seção de Timing de STORYBOARD.md (quadros absolutos e dicas de palavra), para que agentes nunca abram plan.json.

3. Assets

Siga $MOTION_LIB/style/$MOTION_STYLE/docs/asset-prompts.md: uma ferramenta de imagem (qualquer coisa que produza PNGs transparentes) para fundos e props estáticos complexos, código para personagens, todo texto, tags, medidores, botões e UI. Nenhum texto dentro de imagens geradas. Sem ferramenta de imagem, construa cada prop em código com o filtro paper; o estilo se sustenta. Fundos: use o conjunto <Backdrop> da biblioteca (style/$MOTION_STYLE/remotion/public/bg/backdrops/_sheet.jpg); gere um novo apenas quando um episódio precisar de um lugar que a biblioteca não possui. A captura de tela de prova: node $MOTION_LIB/core/tools/capture.mjs <url> public/proof/x.png, mostrada com o RealShot do kit.

4. Cenas (Arquitetura de Múltiplos Arquivos Estrita)

NUNCA coloque todas as cenas em um único arquivo. Cada cena deve viver em seu próprio arquivo isolado para permitir trabalho paralelo de agentes, testes independentes e diffs limpos no Git.

Verifique engine em video/episode.json:

Para Remotion (engine: "remotion")

• Estrutura de Arquivos:
  • src/scenes/<Scene>.tsx (ex.: S01Hook.tsx, S02Name.tsx) — exatamente um arquivo por cena.
  • src/scenes/<Scene>.parts.tsx (opcional) — para sub-componentes privados apenas daquela cena.
  • src/scenes/index.ts — array de registro SCENES gerenciado automaticamente por stubs.py. Nunca coloque corpos de cena aqui.

1. Construa S01Hook primeiro você mesmo em src/scenes/S01Hook.tsx, a partir do bloco HOOK. É a cena de referência que os agentes devem seguir (constantes de dica, a câmera, interpolate com clamp).
2. Passe o restante para agentes de cena em paralelo, agrupados por cena (2-3 cenas cada). O briefing é style/$MOTION_STYLE/remotion/AGENT_BRIEF.md.
3. Posse do arquivo: um agente escreve apenas src/scenes/<Scene>.tsx, opcionalmente <Scene>.parts.tsx e tools/cue_sheet.d/<Scene>.json. Nunca edite outras cenas ou index.ts.
4. Agentes leem style/$MOTION_STYLE/remotion/CATALOG.md e $MOTION_LIB/core/audio/CATALOG.md.

Para fframes (engine: "fframes")

• Estrutura de Arquivos:
  • src/scenes/<scene_snake>.rs (ex.: s01_hook.rs, s02_name.rs) — exatamente um arquivo por cena, definindo sua struct e impl Scene for <Scene>.
  • src/scenes/mod.rs — registra automaticamente todos os módulos de cena via stubs.py (pub mod s01_hook; pub use s01_hook::*;).
  • src/main.rs / lib.rs — apenas monta as cenas através de Video::define_scenes(). Nunca escreva código de desenho de cena dentro de main.rs.

1. Construa s01_hook.rs primeiro como cena de referência.
2. Passe as cenas restantes para agentes em paralelo (cada agente possui apenas src/scenes/<scene_snake>.rs).
3. Leia style/$MOTION_STYLE/fframes/src/ para structs de câmera, cenário e prop disponíveis em vez de componentes TSX.

Para kyfram (engine: "kyfram")

• Estrutura de Arquivos:
  • scenes/<Scene>.lgv (ex.: S01Hook.lgv) — exatamente um script por cena, apenas formas.
  • O renderizador precede $MOTION_LIB/core/kyfram/lgv/core.lgv, style/$MOTION_STYLE/kyfram/PRELUDE.lgv e um cabeçalho gerado (SCENE_ID, BANNER, DUR, FPSR, CAPS e a chamada scene()), então uma cena nunca chama scene(), nunca codifica sua duração ou dicas de legenda, e nunca redeclara um helper.

1. Invoque a skill kyfram. Construa S01Hook.lgv você mesmo primeiro como cena de referência, e verifique-a com bash $MOTION_LIB/core/tools/render.sh mais bash $MOTION_LIB/core/tools/qa.sh hook 0-<N> 6 0.3 6.
2. Passe as cenas restantes para agentes em paralelo (cada agente possui apenas scenes/<Scene>.lgv), com a skill kyfram nomeada no briefing.
3. Agentes leem style/$MOTION_STYLE/kyfram/PRELUDE.lgv para tokens e mobília (drawRoom, drawHero, drawBanner, drawCaptions), e out/cache/kyfram/build/<Scene>.lgv após um render para o script compilado exato.
4. A conexão de SFX e música de fundo segue o fluxo do remotion abaixo; render.sh --voice multiplexa public/vo/voiceover.wav no mp4 assim que esse arquivo existir.

Regras de construção: 1080x1920, 30 fps, cenas encadeadas na série de transição do kit. Camadas globais: VO e música <Audio>, o banner adesivado com <Boil>, <WordTagCaptions>, <GrainOverlay>. Cada prop é envolto em <Paper>, entradas usam <PopIn>, cada cena roda dentro de sua câmera do storyboard. Sem animações CSS. Mantenha os 20% inferiores limpos. Cenas vizinhas nunca compartilham um fundo. O herói padrão é uma criatura laranja quadrada (token C.hero #D67354, sombra C.heroLo #A9553B, alias you); acessórios e pílulas de nome diferenciam o elenco.

5. Som

Escolha SFX pelo nome de $MOTION_LIB/core/audio/sfx/*.js e a música de fundo por preset de $MOTION_LIB/core/audio/beds/*.json. Para kyfram, invoque a skill kyfram primeiro e escreva linhas de SFX por cena em tools/cue_sheet.d/<Scene>.json; ele possui o mesmo pipeline de som compartilhado que fframes e Remotion. A partir de video/:

python3 $MOTION_LIB/core/tools/cues.py && node $MOTION_LIB/core/audio/render.mjs

cues.py mescla as linhas dos agentes em tools/cues.json e imprime uma nota se sons aéreos excederem um por 2,5 s. render.mjs escreve public/audio/music.wav e fx.wav.

6. Renderize

Preview: cargo run --release -- preview (fframes), npx remotion studio (remotion) ou kyfram view out/cache/kyfram/build/<Scene>.lgv (kyfram). Renderize apenas quando solicitado, sempre através do wrapper — ele escolhe o engine a partir de episode.json:

$MOTION_LIB/core/tools/render.sh        # -> out/<out>.mp4

Flags: --workers N (padrão 3), --conc N, --force, --keep. Cada cena é armazenada em cache, então após uma correção apenas a cena alterada é re-renderizada; uma alteração no kit, plano, voz ou legendas re-renderiza tudo. A primeira execução baixa o Chrome headless do Remotion, e out/cache ocupa vários GB de ProRes.

Para corrigir ou reconstruir uma cena: edite src/scenes/<Scene>.tsx, verifique com motion-qa, então execute render.sh novamente.

7. Colheita (após o episódio)

python3 $MOTION_LIB/core/tools/harvest.py .       # a partir de video/; relatório somente leitura
python3 $MOTION_LIB/core/tools/catalog.py         # regenera ambos os catálogos

Promova correções de kit, componentes reutilizáveis, novos SFX e batidas recorrentes como descrito em library/HARVEST.md, e adicione uma entrada em library/CHANGELOG.md.

• Quando um movimento parecer rígido ou confuso, verifique $MOTION_LIB/style/$MOTION_STYLE/docs/motion-principles.md para o princípio correspondente e seu helper de kit.

Passagem

O próximo é motion-qa, que lê stills do projeto e STORYBOARD.md. Execute-o por cena durante a construção e uma vez no reel completo antes do render final. Após a postagem, motion-strategy executa a autópsia.