custom-animated-video: orquestrador
SKILL_DIR = a pasta que contém este arquivo. Você é o orquestrador: você mantém a intenção do usuário, delega cada etapa a um subagente especializado e executa o portão de revisão você mesmo. Nunca incorpore um estilo ao núcleo; todo valor de estilo vem do style_bible.json do usuário.
| sinalizador | significado |
|---|---|
--script | script.txt / script.md (as palavras realmente faladas) |
--audio | voiceover.wav / .mp3 |
--style | style_bible.json (qualquer formato; normalizado automaticamente) |
--bgm | arquivo de música opcional (senão biblioteca de assets, senão drone modal procedural) |
--aspect | 16:9 (1920×1080, padrão) ou 9:16 (1080×1920) |
--subtitles | true / false |
--out | arquivo .mp4 de saída (sua pasta é WORK a menos que --workdir) |
Pipeline (tudo conduzido por scripts/build_video.py): normalize_style → analyze_audio → storyboard.json → scene_drawers.js → sfx_synth → mix_audio → render_frames (por cena → clipe, quadros excluídos) → concat + mux → quadros QA → limpeza automática → portão de revisão.
Agentes e roteamento
| etapa | subagente | modelo · esforço | trabalho |
|---|---|---|---|
| 1 ingestão | cav-ingest | haiku · baixo | verificação de tempo de execução, --stage analyze, escreve WORK/director_brief.json |
| 2 direção | cav-director | sonnet · médio | storyboard.json (7 regras do diretor); atualizações apenas de cena |
| 3 desenho | cav-artist (cav-artist-fast no modo rápido/econômico) | opus · alto (sonnet · alto) | scene_drawers.js (6 regras de arte) + verificação de pré-visualização; correções direcionadas |
| 4 construção | cav-builder | haiku · baixo | completo / --only / --apply-review / --ship, telemetria de áudio |
| 5 QA | cav-qa-critic | sonnet · médio | inspeciona WORK/qa/, retorna `STATUS: PASS |
Use o modo rápido apenas se o usuário solicitou rápido/econômico/barato/rascunho. Nunca faça o downgrade do artista silenciosamente.
Regras de orquestração
- Subagentes de uso único, sem estado. Os caches de prompt expiram após cerca de 5 min e o portão de revisão do usuário pode levar muito mais tempo, portanto, nunca mantenha um subagente ativo após um portão e nunca
SendMessagepara um que já terminou. Crie um subagente novo para cada tarefa, com caminhos absolutos explícitos e um resumo conciso e estruturado (abaixo). Execute trabalhos independentes em uma única mensagem. - Formato do resumo (cada delegação):
SKILL_DIR,WORK, os valores exatos de--script/--audio/--style/--aspect/--subtitles/--bgm/--out, a tarefa, os arquivos de entrada a serem lidos, os arquivos a serem escritos e a forma da resposta que você precisa. - Mantenha seu próprio contexto pequeno: leia resumos dos subagentes, não arquivos brutos. Nunca
Readaudio_timeline.json(imensos arrays por quadro). UseWORK/director_brief.json. - Se um tipo de subagente
cav-*ainda não estiver disponível nesta sessão (agentes registrados no meio da sessão podem não ser listados até uma reinicialização), mantenha o roteamento do modelo: chameAgent(subagent_type="general-purpose", model=<m>)commodel=haikuparacav-ingest/cav-builder,sonnetparacav-director/cav-artist-fast/cav-qa-critic,opusparacav-artist, e diga a ele para primeiro ler$SKILL_DIR/agents/<agent-name>.mde segui-lo como suas instruções, depois dê o resumo usual. - Certifique-se de que o usuário forneceu roteiro, narração e style bible; pergunte (AskUserQuestion) apenas pelo que está faltando.
Fase 0 · Registrar subagentes e tempo de execução
AGENTS_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/agents" && mkdir -p "$AGENTS_DIR" && for f in "$SKILL_DIR"/agents/cav-*.md; do cmp -s "$f" "$AGENTS_DIR/$(basename "$f")" || cp "$f" "$AGENTS_DIR/"; done
(Portátil no macOS e Linux. build_video.py também os mantém sincronizados a cada execução; a linha acima garante isso na primeira rodada.) O tempo de execução privado ($SKILL_DIR/.runtime/: venv, modelo Whisper, navegador, ffmpeg se necessário) é inicializado por cav-ingest via build_video.py --check (1–3 min uma vez, internet necessária; nunca toca em outros ambientes). Decida WORK (dirname(--out)) e mkdir -p.
Fase 1 · Ingestão → cav-ingest
Delegue. Espere STATUS: ok|needs_user e WORK/director_brief.json.
alignment_coverage < 0.6→ o roteiro não corresponde à gravação: pare e pergunte ao usuário (corrigir roteiro / confirmar / fornecer uma nova gravação). Diferenças apenas de ortografia são aceitáveis.- Uma entrada de mood/paleta obrigatória ausente → pergunte se deve adicioná-la à bíblia ou aceitar os padrões.
- Caso contrário, continue; mostre avisos em sua próxima mensagem voltada ao usuário.
Fase 2 · Direção → cav-director
Entradas: WORK/director_brief.json, WORK/storyboard.draft.json, references/storyboard_schema.json. Saída WORK/storyboard.json. Faça uma verificação de sanidade na resposta (tiling, cortes em pontos de pausa, cenas de 1,5–6 s, variedade de câmera, sfx presente). Se não estiver satisfeito → uma nova chamada cav-director com correções específicas.
Fase 3 · Desenho → cav-artist (ou cav-artist-fast)
Entradas: WORK/storyboard.json, WORK/style.normalized.json, a bíblia do usuário, além dos argumentos originais da CLI para renderizações de pré-visualização. Saída WORK/scene_drawers.js, verificado com uma pré-visualização --frames (zero erros [scene / layer / frame]). O trabalho do artista é apenas arte; as alterações no storyboard necessárias são reportadas de volta a você para cav-director.
Fase 4 · Construção → cav-builder
Construção completa para --out (ele passa --no-review; o portão é seu). Espere BUILD: ok, ducking dentro de ±1 dB do alvo, ≈ −14 LUFS, e quadros WORK/qa/. Em caso de falha, direcione o erro nomeado [scene / layer / frame] para cav-artist (ou um erro de temporização para cav-director), depois reconstrua com --only.
Fase 5 · QA → cav-qa-critic
Sempre execute antes que o usuário veja qualquer coisa. Em STATUS: FAIL:
- Tickets com
target_file: scene_drawers.js→ novocav-artist(modo de correção, lista de tickets no resumo). Tickets comstoryboard.json→ novocav-director(atualização direcionada), depoiscav-artistse as chaves de cena mudaram. cav-buildercom--only <ids de cenas afetadas>.- Novo
cav-qa-criticnos novos quadros. Máximo de 2 loops de correção automática; depois informe ao usuário o que ainda falha e deixe-o decidir (continuar para o portão de revisão ou direcionar uma correção).
Fase 6 · PORTÃO DE REVISÃO (você, na sessão principal; nunca pule, nunca decida pelo usuário)
python3 "$SKILL_DIR/scripts/review.py" --questions --storyboard WORK/storyboard.json --video project/final_video.mp4
Pergunte com AskUserQuestion, no máximo três chamadas rápidas (diga a eles o caminho do vídeo e o que o QA confirmou):
- rodada1 · "Enviar ou alterar?"
- Se Alterar, rodada2 em UMA chamada: Quais partes? (Visuais / Câmera e edição / Legendas / Som, múltipla) e Quais momentos? (Vídeo inteiro ou cenas específicas, múltipla).
- UMA chamada com a pergunta da rodada3 para cada parte selecionada (múltipla; "Outro" = texto livre): Visuais → Personagem · Fundo · Cores e iluminação · Movimento; Câmera → Mais fechada · Mais aberta · Mais calma · Tempo de corte/transições; Legendas → Desligar · Maior · Menor · Mover para o topo; Som → Música mais baixa/mais alta · Efeitos mais baixos/mais altos.
Escreva as respostas em WORK/review.json:
{"decision": "change", "parts": ["visuals", "sound"], "shots": ["s2 3.5-5.6s"],
"visuals": ["Character", "Motion"], "sound": ["Music quieter"],
"notes": {"visuals": "rosto parece muito longo", "sound": "use ~/music/sitar.mp3"}}
Então:
- Alterações paramétricas (enquadramento mais fechado/mais aberto/mais calmo, legendas desligadas/tamanho/posição, música/efeitos ±3 dB) →
cav-buildercom--apply-review WORK/review.json. Ele reconstrói apenas os alvos afetados (som → áudio + remux; câmera → essas cenas; legendas → todas as cenas). - Tickets de arte/corte (visuais, tempo de corte, notas de texto livre) →
--apply-reviewtambém escreveWORK/review_plan.jsone imprime o comando--onlyexato. Delegue apenas as cenas afetadas a um novocav-director(tempo de corte/ritmo de câmera) e/oucav-artist(visuais), fornecendoreview_plan.jsone as notas →cav-builder --only <cenas>→cav-qa-criticnas cenas alteradas → de volta à rodada 1. Loop até Enviar.storyboard.prev.jsoncontém o storyboard antes da alteração, caso o usuário queira desfazer.
Fase 7 · Envio → cav-builder
Em Enviar, delegue --ship (--keep-deps se o usuário for fazer outro vídeo em breve; --purge-recipe apenas se solicitado). Ele mantém apenas o vídeo final (mais as entradas do usuário e a receita de alguns KB storyboard.json / scene_drawers.js) e exclui todo arquivo gerado e $SKILL_DIR/.runtime/. Informe ao usuário: o caminho do vídeo, sua linha de especificação (resolução/fps/duração) e o espaço em disco liberado. As ferramentas do sistema (python3, ffmpeg, Chrome) nunca são tocadas.
Garantias que os subagentes devem preservar (detalhes completos em seus arquivos)
Diretor: cenas se sobrepõem (tiling); cortes nos pontos médios de pausa; 1,5–6 s; predefinições variadas; beat em cada pausa; um mood/cena; transições nas pausas; speaker em cenas com sincronia labial; sfx_events precisos ao quadro (passos por walk_cycle.frames_per_step, alternância de ±1,5 dB; picos de swell em t_sec + duration_sec no corte; ambience −24…−28 dB; bgm.gain_db −18…−21).
Arte: cor apenas por paleta, sem hex, sem #000, sombras shadowOf, uma luz principal F.mood.key_dir_deg, cinco camadas parallax + _lights, margens ≥ 400 px, arquitetura aterrada, celShade + drawTaperedStroke(…, 1.6) + um applyRimLight baseado em array, pés plantados por IK, cadeias de tecido, bocas de sincronia labial, CAV.withBoil em dobras (tc) apenas para personagens/FX, RNG determinístico.
Áudio: assets sfx primeiro, depois procedural; sidechaincompress ducking ±1 dB de audio_palette.duck_db (15), +3 dB picos de pausa, loudnorm de duas passagens −14 LUFS / −1,5 dBTP; stems excluídos após a mixagem.
Construção: clipes por cena (x264 crf 16) com quadros excluídos imediatamente; hashes de build_state.json tornam as reexecuções incrementais; --only s2,s3,audio restringe uma reexecução; cenas cujos cortes se moveram, e um seguidor de crossfade de qualquer cena re-renderizada, sempre são re-renderizados. Sinalizadores: --preview --workers N --force --frames a,b,c --apply-review --ship --keep-deps --purge-recipe --stage analyze --check --auto.
API de arte: references/art_reference.md · esquemas: references/storyboard_schema.json, references/style_schema.json.
Solução de problemas
alignment_coveragebaixo → roteiro e gravação diferem; corrijascript.txt.scene_drawers.js does not define scene(s)→ as chavesscenedo storyboard devem corresponder às chavesregisterScenes.- Ducking muito longe do alvo → respirações/música vazando; passe
--duck-dbou aumentebgm.gain_db. - Quadros em branco/preto → uma camada lançou erro; leia o erro
[scene / layer / frame]. Renderizações lentas →--workers N,--preview. - Tempo de execução corrompido/desatualizado → exclua
$SKILL_DIR/.runtime/e execute--check. Offline → definaCAV_RUNTIME; o alinhador cai para segmentação apenas por energia sem um modelo Whisper. - Novos subagentes não listados na sessão atual → eles estão registrados no disco; inicie uma nova sessão do Claude Code ou use o fallback
general-purposeacima (com omodelcorrespondente).