Craft Music Video (FilmCraft + EffectCraft)
Workflow reutilizável para produzir videoclipes sincronizados em uma faixa de áudio combinando EffectCraft (cenas 2D, motion graphics, VFX, camada de letras alpha independente) e FilmCraft (montagem principal multi-pistas, sincronia rítmica, mixagem/masterização de áudio, correção de cor global, exportação dupla Master + Clean).
Métodos comuns de animação 2D (enquadramentos, mudanças de pose com antecipação, âncoras de personagens/câmeras, armadilhas de parenting EffectCraft, ordem de empilhamento e legibilidade do texto): seguir craft-2d-animation.
Referência completa MCP, comandos de motor verificados e configurações Flatpak: references/mcp-and-commands.md.
0. Pré-requis MCP e Sandbox (a verificar antes de iniciar)
- Verificar se os servidores MCP
effectcraftefilmcraftestão expostos na sessão atual (ou alternar corretamente para as CLIseffectcraft-cli/filmcraft-cli).- Se faltarem, não inventar chamadas: consultar references/mcp-and-commands.md para a configuração exata (Flatpak Linux
ai.storyteller.filmcraft/ai.storyteller.effectcraftou binário nativo, em modo headless ou bridge).
- Se faltarem, não inventar chamadas: consultar references/mcp-and-commands.md para a configuração exata (Flatpak Linux
- Atenção Flatpak (Linux): por padrão,
ai.storyteller.effectcraftsó tem acesso axdg-documents,xdg-picturesexdg-videos. Se o projeto residir em outro local (ex.~/.t3/projects/...), passar--filesystem=<raiz_do_projeto>ou configurar o override:flatpak override --user --filesystem=home ai.storyteller.effectcraft - Conflito GUI vs Headless: nunca abrir o mesmo
.ecprojou.fcprojsimultaneamente no aplicativo gráfico e em MCP/CLI headless. Usar--bridgepara controlar uma janela aberta.
1. Distribuição de papéis: EffectCraft vs FilmCraft
| Domínio | EffectCraft (.ecproj) | FilmCraft (.fcproj) |
|---|---|---|
| Uso principal | Cenas 2D animadas (V01..Vnn), letras em camadas transparentes independentes (L01..Lnn), títulos cinéticos, partículas, composição 2D/3D | Montagem principal multi-pistas (V1 cenas + V2 letras RGBA + A1 áudio master), sincronia ao quadro, transições, correção de cor global, exportação dupla (com letras + clean) |
| Criação | comp.new, layer.newText, layer.newShape, layer.newSolid, layer.newAdjustment, add_effect, scripts JSX (ec_runtime.py) | file.newSequence, timeline.place, timeline.setTrack, timeline.razor, timeline.trim, timeline.move, clip.speedDuration |
| Sincronia musical | Referências exatas de audio/lyrics_timing.json + escuta a ouvido; opcionalmente keys.audioToKeyframes apenas se um efeito reativo medido for desejado | markers.add em cada seção, último acento e corte ao preto; alinhamento exato ao quadro (frame: f0) |
| Estilização & Colorimetria | Estilos de camada, máscaras, Bézier, brilhos, sombras projetadas, pré-composições (layer.precompose) | Lumetri Color (lumetri.applyPreset, lumetri.setLook, lumetri.applyMatch), sequence.colorSettings, sequence.applyVideoTransition |
| Áudio | Nenhum áudio exportado nos renders intermediários (--audio off) | Faixa master original em A1 (deixada a 0.0 dB por padrão para preservar o master original; essentialSound.* ou sequence.normalizeMixTrack apenas sob demanda) |
2. Pipeline de troca de arquivos & Coerência técnica
Convenção de pasta do projeto
<project_root>/
├── audio/ # Faixa master (WAV/FLAC/MP3) + lyrics_timing.json (fonte única editável)
├── footage/ # Rushes de vídeo, fotos, logotipos eventuais
├── renders_vfx/ # Renders intermediários EffectCraft: V01..Vnn.mov (RGB) + L01..Lnn.mov (RGBA)
├── previews/ # Capturas PNG (render-frame) + MP4 curtos de pré-visualização com som (ex. refrão, solo)
├── projects/ # Arquivos .ecproj e .fcproj
├── scripts/ # Geradores específicos do clipe (importante as ferramentas compartilhadas T3 Code)
└── exports/ # Entregáveis finais 1080p: *_lyrics.mp4 e *_clean.mp4
Formatos de troca compatíveis
- Letras & Overlays com transparência (
V2) do EffectCraft → FilmCraft:- Recomendado (arquivo único): QuickTime Apple ProRes 4444 (
.mov),format: "prores",proresProfile: "4444",channels: "rgba",audio: "off". - Alternativa sem perdas: Sequência PNG ou OpenEXR (
channels: "rgba"), importada no FilmCraft comimage_sequence: true. - Proibido para alpha:
H264,HevceAv1não gerenciam o canal alpha (alpha: false).
- Recomendado (arquivo único): QuickTime Apple ProRes 4444 (
- Cenas visuais opacas (
V1) do EffectCraft:format: "prores",proresProfile: "hq",channels: "rgb",audio: "off".
- Entrega final do FilmCraft:
- Web/Distribuição:
format: "h264"(.mp4, preset"High Quality 1080p HD"). - Master archive:
format: "prores". (Nota: no Linux sem codificador de hardware,hevceav1podem estar indisponíveis.)
- Web/Distribuição:
Alinhamento de resolução, taxa de quadros (FPS) e colorimetria
- Travar desde o início um par único
(width, height, fps)compartilhado entre EffectCraft (comp.new) e FilmCraft (file.newSequence), ex.1920×1080a30ou24fps. - Seções alinhadas ao quadro: calcular cada limite de seção em número inteiro de quadros (
f0 / fps .. f1 / fps) para que a soma das seções cubra exatamente a duração real da faixa de áudio sem deriva ou buraco. - Espaço de cor:
workingSpace: "rec709"em SDR em ambos os softwares (file.projectSettingsno EffectCraft,sequence.colorSettingsno FilmCraft;autoToneMap: truese rushes HDR/Log). - Conversão de tempo: EffectCraft trabalha em segundos (
f64); FilmCraft usa ticks (254016000000ticks =1s) e também aceitaframe/secondsemtimeline.place.
3. Método musical chave (Alinhamento a ouvido, Timing editável, Letras independentes & Instrumentais)
A. Alinhamento a ouvido e medição exata do final no áudio master
- Sempre medir a faixa original a 44,1 kHz (
hop = 441= 10.000 ms exatos) viaaudio_cues.py analyze(nunca usar passo arredondado em 22,05 kHz que cria uma deriva de várias centenas de milissegundos em 3 minutos). - Verificar o final exato no MP3/WAV antes de travar a montagem: localizar o último acento forte, a última batida/instrumento (ex. corte ao preto) e o fim real da reverberação até o silêncio final.
- Ouvir realmente a faixa por trechos: dividir a música em trechos que se sobrepõem (ex. 18 s com 2 s de sobreposição) depois extrair trechos curtos ao redor das transições, refrões, coros e finais de frases (
audio_cues.py slice) e ouvi-los para travar o BPM exato e cada entrada vocal a ouvido.
B. Arquivo único de timing editável (audio/lyrics_timing.json) e marcos incertos
Centralizar todo o timing das letras em um único arquivo JSON editável manualmente (audio/lyrics_timing.json), relido pelo gerador EffectCraft:
meta: arquivo de áudio, duração áudio/vídeo em ms,fps,bpm,first_drum_hit_ms,last_accent_ms,black_cut_ms.sections: limitesstart_ms/end_msalinhados ao quadro.phrases:start_ms,end_msedisplay_end_ms(prolongado de+250a+600 msse necessário para deixar a última palavra legível mesmo se o plano ou a seção mudar).type: "lead"para o vocal principal etype: "echo"em entradas separadas para coros, respostas e ad-libs.words(divisão por palavras/grupos) apenas onde uma animação ou acento visual precisar; caso contrário, exibir a frase inteira corretamente."uncertain": true+"review_note": "..."em todo marco ambíguo (coros, ecos, vocalises sobrepostos, gritos breves) para permitir que o usuário os reajuste facilmente manualmente sem tocar no código.
C. Letras em uma camada independente (V2 RGBA) & Exportação dupla Master / Clean
- Nenhuma barra preta permanente: colocar cada frase no espaço livre do plano (ver craft-2d-animation §5), com sombra projetada suave, margens de segurança e continuidade automática (
isContIn/isContOut) quandodisplay_end_msatravessar um corte de seção. - Faixa transparente dedicada: gerar as letras em composições separadas
L01..Lnn(omitindo as seções puramente instrumentais) renderizadas em ProRes 4444 RGBA e colocadas emV2no FilmCraft. - Manter o texto do cenário em
V1: letreiros, telas, cópias, quadros permanecem nas cenasV01..Vnn. - Exportação dupla rigorosamente idêntica: exportar a versão com letras (
V2ativada), depois desativarV2(timeline.setTrack {"track": "V2", "enabled": false}) para exportar a versão clean com montagem e áudio 100 % idênticos, depois reativarV2antes da salvaguarda final do.fcproj.
D. Ações visuais durante as passagens instrumentais (Zero curva de áudio genérica)
- Banir as muletas visuais genéricas: sem curvas de áudio, sem ziguezagues de osciloscópio, sem círculos flutuantes decorativos em intros, solos ou interlúdios.
- Coreografar ações desenhadas em acentos escolhidos a ouvido: uma porta bate, uma série de luminárias de teto acende uma por uma, um cenário se desdobra em papelão/papel 3D nos riffs, um objeto desliza ou um personagem muda de pose com antecipação e sustentação.
- Segurar os planos entre os acentos: deixar uma imagem clara e estável entre dois tempos fortes para que a ação permaneça legível.
- Aplicar as regras 2D comuns: enquadramentos variados (aberto / OTS / perfil / close-up), silhuetas cheias, hierarquia de âncoras neutras antes da transformação (ver craft-2d-animation).
4. Workflow passo a passo
Etapa 1 — Análise de áudio a ouvido & Esqueleto de timing
- Sondar o master (
audio_cues.py analyze) a 44,1 kHz para obter a duração exata, os transitórios de 10 ms e o detalhe do final da faixa. - Extrair trechos de escuta (
audio_cues.py slice) e ouvi-los para fixar o BPM exato, os limites das seções alinhados aos quadros, as frases, os ecos e o corte final. - Inicializar e preencher
audio/lyrics_timing.jsonmarcando os marcos duvidosos com"uncertain": true+"review_note", depois validar o JSON (lyrics_overlay.py --validate).
Etapa 2 — Decupagem / Storyboard curto (antes de qualquer render grande)
- Redigir um plano de montagem curto (tabela tempo / seção / local & enquadramento / ação visual desenhada / tratamento das letras).
- Apresentar a decupagem (e as escolhas de acentos para as passagens instrumentais) ao usuário antes de lançar renders completos.
Etapa 3 — Criação das cenas (V01..Vnn) e letras (L01..Lnn) no EffectCraft
- Construir as cenas 2D (
V01..Vnn) seguindo as regras de âncoras, parenting neutro e empilhamento de craft-2d-animation (usandoec_runtime.py). - Gerar as composições de letras transparentes (
L01..Lnn, exceto instrumentais) diretamente deaudio/lyrics_timing.jsonvialyrics_overlay.py. - Controle rápido por capturas (
render-frame --max-side 960) nos planos chave (e--transparentnas letras) para corrigir imediatamente qualquer sobreposição ou deslocamento de âncora antes do render de vídeo. - Pré-visualizações MP4 curtas com o som (ex. 1 refrão + 1 solo): renderizar apenas essas 1–2 seções, mixar com o trecho exato do áudio master, assisti-las e ouvi-las para reajustar se necessário as entradas de ecos, a sustentação da última palavra entre planos e a legibilidade do solo.
- Render completo de baixo consumo para
./renders_vfx/viarender_ec_batch.sh(sequencial 1 render por vez, ProRes HQ RGB paraV*, ProRes 4444 RGBA paraL*, retomada automática viaffprobe). - Salvar
projects/<clip>.ecproj.
Etapa 4 — Montagem & Exportação dupla no FilmCraft
- Montar a sequência Rec.709 via
assemble_filmcraft.py(ou via MCPfile.newProject,file.newSequence,media_import,timeline.place,markers.add):A1: áudio master original intacto (volumeDb: 0.0)V1:V01..Vnn.movcolocados em seu quadro exato (frame: f0)V2:L01..Lnn.mov(ProRes 4444 RGBA) colocados nos mesmos quadros exatos (audio: false)
- Verificar a sequência (
inspect sequence) + renderizar alguns quadros compostosV1+V2eV1sozinho para confirmar a decupagem alpha e a presença do texto diegético na versão clean. - Exportar a versão com letras (
*_lyrics.mp4), desativarV2, exportar a versão clean (*_clean.mp4), depois reativarV2e salvarprojects/<clip>.fcproj.
Etapa 5 — Auditoria final obrigatória (Com som + Sem som)
- Controle COM o som no export
*_lyrics.mp4: verificar os finais de frases, os cortes de refrões, a entrada dos ecos, o corte ao preto exato e o fim limpo da faixa de áudio original. - Controle SEM o som (mudo) nas passagens instrumentais (solo, interlúdio) do
*_clean.mp4: verificar que o objetivo do personagem e a progressão visual são 100 % compreensíveis sem áudio, sem nenhuma curva de áudio residual e com o texto do cenário intacto. - Apresentar os entregáveis e listar explicitamente os marcos marcados
"uncertain": trueemlyrics_timing.json.
5. Ferramentas compartilhadas T3 Code & Dependências
As ferramentas reutilizáveis estão em ~/.t3/shared/craft-video/:
| Ferramenta | Caminho | Uso clipe musical |
|---|---|---|
| Análise & corte de áudio 44,1 kHz | ~/.t3/shared/craft-video/audio_cues.py | Dur... [truncated for translation] |
... (conteúdo truncado para tradução)
6. Exemplos de chamadas MCP
// EffectCraft: criar uma nova composição 1920×1080 a 30 fps
effectcraft comp.new width=1920 height=1080 fps=30 duration=10.0 name="V01_intro"
// FilmCraft: importar mídia e colocar na timeline
filmcraft media_import path="/path/to/renders_vfx/V01_intro.mov"
filmcraft timeline.place mediaName="V01_intro.mov" track="V1" frame=0
7. Notas Finais
- Sempre validar
lyrics_timing.jsonantes de iniciar renders longos. - Manter backups dos projetos
.ecproje.fcproj. - Se o usuário solicitar ajustes, editar o JSON ou os scripts, nunca modificar os renders finais diretamente.
- Para animações 2D complexas, consultar craft-2d-animation.