Orquestração de Inserções Animadas para o Vídeo
Você conduz todo o caminho: material bruto → motion-plan → MP4 prontos com timecodes, que o usuário insere em sua montagem. Você mesmo quase não constrói nada — planeja, distribui e aceita o trabalho.
Seu principal valor aqui é a aceitação. Os subagentes montam as composições diligentemente, mas as falhas de composição só são vistas por quem olha os quadros de fora. Uma falha na aceitação custa mais caro do que uma falha na montagem.
Pipeline v4 (padrão)
Estilo — ../motion-build/references/style-v4.md. Ordem comprovada (stream 41 min, 34 inserções + intro):
- Texto e quadros.
/watchno original (transcript), para o plano — marcação palavra por palavra dos trechos. - Plano via
/motion-plan→ mostrar ao usuário, alinhar ajustes (duração da intro, densidade, layouts onde o autor desenha). Não iniciar a montagem sem aprovação. - Pasta de trabalho
Wno scratchpad//tmp:scenes.json({NN: start, dur, layout, title}),scenes/,img/,clips/. - Imagens:
prompts.tsv→zsh ../motion-build/scripts/gen_images.sh prompts.tsv W/raw→alpha.py W/raw W/img. Veja a lista de todas as imagens: duplicatas e malsucedidas (fundo sobrou, objeto não é o certo) — regenere. - Clipes:
python3 ../motion-build/scripts/cut_clips.py W source.mp4 --cam x,y,w,h(meça a webcam pelo quadro). - Briefing: copie
references/build-brief-v4.mdparaW/BUILD-BRIEF.md, preencha caminhos e ajustes do plano. As cenas aprovadas anteriormente coloque emW/scenes/como referências. - Distribuição: 7–8 subagentes em uma única mensagem, 3–5 cenas do mesmo layout por agente (kinetic — para um
agente inteiro). Na tarefa: briefing, referência de layout de
recipes/v4/, especificações, «olhe os quadros com os olhos». - Aceitação — pelo quadro em tamanho real do final de cada cena (corte do painel), o contato 3×3 mente no tamanho da fonte. Retorne com especificações: «legendas ≥30px, personagem ≥240px, metade inferior do painel vazia». Quando encontrar um erro comum — envie-o imediatamente para os agentes ainda trabalhando.
- Montagem:
python3 scripts/assemble_v4.py W source.mp4 [--intro intro.mp4 --cut SEC]— inserções com seu próprio SFX + rascunho. Capture quadros do rascunho nos pontos das inserções e nas emendas. - Entrega — na pasta ao lado do original:
draft.mp4,inserts/NN_MM-SS-D_tema.mp4+index.mdcom timecodes, base limpa (se houve nova intro), imagens,music.mdcom links (não incorporar música).
Ordem (geral)
1. Marcação
Carregue /motion-plan e percorra-o. Na saída — MOTION.md: lista de cenas com timecodes,
técnica escolhida, conteúdo do quadro e justificativa de por que essa técnica mostra esse pensamento.
Mostre o plano ao usuário antes da montagem. Montar dez cenas é caro; refazer o plano depois disso é doloroso. Pergunte o que remover, o que adicionar, onde a técnica não correspondeu ao pensamento.
2. Especificações
Cada cena do plano precisa de sua especificação quadro a quadro — o subagente não deve supor. Coloque-a
em <projeto>/SPEC.md dentro do diretório da cena. O formato da especificação está em /motion-plan,
seção «Especificação da cena».
Crie um diretório de projeto separado para cada cena. Os subagentes trabalham em paralelo,
check verifica o projeto inteiro, e a composição quebrada do vizinho atrapalhará.
Faça o template uma vez e depois multiplique por cópia:
./node_modules/.bin/hyperframes init _template --example blank --non-interactive --resolution landscape --skill motion-graphics
Copie para o template a pasta assets/ da skill motion-build inteira
(.claude/skills/motion-build/assets/) — tokens.css puxa fontes via @import,
e a estrutura de diretórios deve coincidir:
cp -R .claude/skills/motion-build/assets/. _template/assets/
Depois, uma cópia por cena:
for name in scene-01 scene-02 scene-03; do cp -R _template "$name"; done
2b. Monte você mesmo uma cena de referência
Antes da distribuição, escolha uma cena — de preferência de complexidade média, com um número ou par de cartões — e monte-a com suas próprias mãos até o render. Isso leva dez minutos e resolve três problemas de uma vez:
- Verifica o pipeline. Se
init, tokens, fontes ou o render travarem em algum ponto, você saberá uma vez, e não com nove relatórios idênticos. - Define as constantes transversais do vídeo. Tamanhos de fonte, cadência de digitação, mecânica de fundo, drift, entrada em dois estágios — tudo isso deve ser igual em todas as cenas, e por padrão cada montador escolhe o seu. O sistema de design define faixas, não números.
- Dá aos montadores um exemplo, não uma descrição. Ler uma cena pronta do mesmo vídeo é muito mais confiável do que extrair as mesmas regras dos manuais.
Ao lado, coloque um arquivo curto de constantes transversais (BUILD-BRIEF.md) e, na tarefa de cada
subagente, indique tanto ele quanto o caminho para a composição de referência: «leia ins-b2/index.html — dela
herdam-se tipografia, ritmo, fundo e estrutura da timeline; muda apenas o conteúdo».
No briefing deve constar: tabela de tamanhos de fonte com números específicos, paleta e substituições de cor proibidas, mecânica de fundo e aproximação transversal literalmente, regra do quadro 0, cadências de digitação, lista de proibições do motor, coordenadas keep-out da âncora transversal e comandos do pipeline.
Testado em um vídeo de nove cenas: nove montagens independentes saíram visualmente como um único sistema, nenhuma passagem de alinhamento após o render foi necessária.
3. Distribuição
Dispare os subagentes em uma única mensagem, todos de uma vez — eles trabalham em paralelo, e isso é muito mais rápido do que a montagem sequencial.
Na tarefa de cada um:
- diretório de trabalho — apenas sua cena, não mexer nas dos outros;
- ler
SPEC.md, depois carregar a skillmotion-builde segui-la; - olhar os quadros com os olhos via Read, e não apenas executar
check; - renderizar MP4 e deixá-lo em
renders/do seu projeto, sem copiar para lugar nenhum; não excluir a pasta de trabalho; - retornar resumidamente: o que resultou, caminho para o MP4, o que foi difícil, o que ficou imperfeito.
Peça explicitamente para nomear as divergências com a especificação. Você escreve a especificação sem ver os quadros; o subagente vê os quadros. As correções dele são a parte mais útil do relatório.
Oito cenas em uma única onda passam normalmente — o render leva segundos, o tempo principal vai para a autoria, e a máquina não trava nisso. Divida em ondas quando houver mais de dez cenas: não é a máquina que fica pesada, mas a análise dos relatórios.
Sobre a coleta dos resultados, combine com antecedência. Sem instrução explícita, os montadores
colocam MP4 em qualquer lugar: em renders/, em output/ comum, na pasta do CLAUDE.md, às vezes
em dois lugares ao mesmo tempo «para o orquestrador encontrar com certeza». Uma vez isso custou
a busca de renders com find por todo o disco. A regra é simples: cada um deixa o arquivo em seu
próprio renders/ e informa o caminho no relatório; você mesmo organiza por nomes e timecodes
na entrega.
4. Aceitação
Para cada cena, capture os quadros você mesmo e olhe-os:
cd scene-01 && ../node_modules/.bin/hyperframes snapshot . --frames 8 -o review
Leia review/contact-sheet.jpg via Read. Não confie no contato que o subagente anexou —
ele pode ser de uma iteração anterior.
No que prestar atenção em primeiro lugar, pela experiência:
- Escala. O problema mais comum: texto em 40px onde precisa de 54, ícones em 90px nas bordas.
- Quadro vazio. Especialmente logo após o movimento mais caro — a técnica não tem onde pousar.
- A técnica existe formalmente, mas não é legível. O preenchimento transita imperceptivelmente, a costura parece um crossfade, a perspectiva não aparece na estática.
- Artefatos. Anéis de banding em gradientes, sujeira quente no meio da mudança de cor, marcador cortando no meio da palavra.
- Hierarquia. Um elemento secundário (marca, kicker) não deve pesar mais que a mensagem.
Envie correções via SendMessage para o mesmo agente — ele tem todo o contexto da cena, reiniciar é mais caro. Na correção, diga o que não mexer: sem isso, o agente reconstrói o que já está bom.
Aceite a cena quando a aceitação for legível nos quadros, e não quando check estiver verde.
5. Montagem bruta — etapa obrigatória
Não entregue uma pasta de arquivos sem montar um rascunho a partir deles. Parte das falhas só é visível no vídeo montado e invisível cena a cena — por mais que você aceite cada uma individualmente, o todo não é verificado por elas.
Monte os MP4 prontos em uma pasta com nomes no formato NN_MM-SS-D_técnica.mp4 (timecode no nome —
é dele que o script tira a posição), depois:
python3 <caminho-para-skill>/scripts/assemble.py --root <pasta-de-trabalho> \
--source m1=~/Desktop/part1.mp4 --source m2=~/Desktop/part2.mp4 \
--anchor 1245,690,650,345
A inserção substitui a imagem em sua duração, o áudio original segue contínuo, o cronometragem não muda, as emendas são rígidas.
--anchor — sobre a âncora transversal, e isso é o principal nesta etapa. Se no original houver
uma câmera PiP ou outro elemento fixo, a inserção em tela cheia o remove: o locutor desaparece do
quadro em cada inserção e retorna. Vinte vezes em um vídeo, isso desmonta a edição em slides separados
e viola diretamente a lei 16. A flag sobrepõe a área da âncora sobre todas as inserções de uma vez.
Meça as coordenadas da âncora pelo quadro original, não adivinhe: extraia um quadro
(ffmpeg -ss 300 -i src.mp4 -frames:v 1 f.png), olhe-o e tire o retângulo. A posição
pode diferir entre as partes — verifique cada uma.
6. Aceitação do montado
Capture quadros do rascunho e olhe-os: pontos dentro das inserções, entre elas, e obrigatoriamente a emenda das partes. No que prestar atenção:
- a âncora não desaparece nas inserções;
- as inserções estão em seus timecodes, e não se deslocaram;
- o áudio não quebra nas fronteiras;
- na emenda das partes não há salto de brilho ou volume;
- duas cenas com a mesma técnica seguidas não são lidas como um único quadro duas vezes.
7. Entrega
Entregue ao usuário o rascunho mais uma tabela: timecode, arquivo, duração, o que mostra — para que ele possa substituir qualquer inserção em sua montagem sem remontar tudo.
Se houver muitas cenas e quiser mostrar tudo de uma vez — monte uma página com prévias e publique como artefato. Comprima o vídeo para 1280px / CRF 30 e incorpore como data-URI: dez cenas cabem em aproximadamente um megabyte e meio, o limite do artefato é 16 MB.
ffmpeg -y -i in.mp4 -vf scale=1280:-2 -c:v libx264 -preset slow -crf 30 -pix_fmt yuv420p -an out.mp4
O que não fazer
Não construa cenas você mesmo quando houver mais de duas. O sentido da orquestração é que seu contexto permaneça limpo para a aceitação. Se você montar três cenas manualmente, na quarta parará de notar falhas de composição.
Não aceite pelo relatório. O relatório do subagente diz o que ele fez, não como ficou. Olhe os quadros.
Não reescreva o plano em andamento. Se durante o processo ficar claro que a técnica foi mal
escolhida, diga isso ao usuário e corrija MOTION.md, e não monte silenciosamente outra coisa.
Não considere o trabalho concluído em uma pasta de MP4. Enquanto o rascunho não estiver montado, você não sabe como tudo fica junto: âncora desaparecendo, timecodes errados, duas cenas iguais seguidas — tudo isso é descoberto apenas no conjunto.