Communitygithub.com

craft-music-video

Mostra a um agente como planejar, construir ou editar um "videoclipe artesanal" para que o resultado concreto seja um movimento que o agente possa defender quadro a quadro. O procedimento percorre Craft Music Video (`FilmCraft` + `EffectCraft`), 0. Pré-requis MCP e Sandbox (a verificar antes de iniciar), 1. Distribuição de papéis: EffectCraft vs FilmCraft. Use quando uma nova tarefa exigir esse ofício.

O que é craft-music-video?

Esta skill define um workflow completo para produzir videoclipes sincronizados com 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). Ela garante que o agente planeje e execute a produção de forma coerente, usando um arquivo JSON de timing editável (`lyrics_timing.json`) para centralizar letras, seções e marcos incertos, e um sandbox MCP (EffectCraft e FilmCraft) com configurações específicas para Linux Flatpak, evitando conflitos entre GUI e headless. A skill enfatiza a sincronia musical feita a ouvido, a separação entre letras em camada transparente (V2) e cenas visuais opacas (V1), e a exportação dupla (com e sem letras) para máxima flexibilidade. Plataformas suportadas: EffectCraft e FilmCraft, com scripts auxiliares em Python (`audio_cues.py`, `lyrics_overlay.py`, `assemble_filmcraft.py`).

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/NelaBDV/craft-video-kit/tree/HEAD/skills/craft-music-video

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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)

  1. Verificar se os servidores MCP effectcraft e filmcraft estão expostos na sessão atual (ou alternar corretamente para as CLIs effectcraft-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.effectcraft ou binário nativo, em modo headless ou bridge).
  2. Atenção Flatpak (Linux): por padrão, ai.storyteller.effectcraft só tem acesso a xdg-documents, xdg-pictures e xdg-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
  3. Conflito GUI vs Headless: nunca abrir o mesmo .ecproj ou .fcproj simultaneamente no aplicativo gráfico e em MCP/CLI headless. Usar --bridge para controlar uma janela aberta.

1. Distribuição de papéis: EffectCraft vs FilmCraft

DomínioEffectCraft (.ecproj)FilmCraft (.fcproj)
Uso principalCenas 2D animadas (V01..Vnn), letras em camadas transparentes independentes (L01..Lnn), títulos cinéticos, partículas, composição 2D/3DMontagem 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çãocomp.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 musicalReferências exatas de audio/lyrics_timing.json + escuta a ouvido; opcionalmente keys.audioToKeyframes apenas se um efeito reativo medido for desejadomarkers.add em cada seção, último acento e corte ao preto; alinhamento exato ao quadro (frame: f0)
Estilização & ColorimetriaEstilos 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
ÁudioNenhum á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 com image_sequence: true.
    • Proibido para alpha: H264, Hevc e Av1 não gerenciam o canal alpha (alpha: false).
  • 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, hevc e av1 podem estar indisponíveis.)

Alinhamento de resolução, taxa de quadros (FPS) e colorimetria

  1. Travar desde o início um par único (width, height, fps) compartilhado entre EffectCraft (comp.new) e FilmCraft (file.newSequence), ex. 1920×1080 a 30 ou 24 fps.
  2. 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.
  3. Espaço de cor: workingSpace: "rec709" em SDR em ambos os softwares (file.projectSettings no EffectCraft, sequence.colorSettings no FilmCraft; autoToneMap: true se rushes HDR/Log).
  4. Conversão de tempo: EffectCraft trabalha em segundos (f64); FilmCraft usa ticks (254016000000 ticks = 1 s) e também aceita frame / seconds em timeline.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

  1. Sempre medir a faixa original a 44,1 kHz (hop = 441 = 10.000 ms exatos) via audio_cues.py analyze (nunca usar passo arredondado em 22,05 kHz que cria uma deriva de várias centenas de milissegundos em 3 minutos).
  2. 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.
  3. 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: limites start_ms / end_ms alinhados ao quadro.
  • phrases:
    • start_ms, end_ms e display_end_ms (prolongado de +250 a +600 ms se necessário para deixar a última palavra legível mesmo se o plano ou a seção mudar).
    • type: "lead" para o vocal principal e type: "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

  1. 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) quando display_end_ms atravessar um corte de seção.
  2. 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 em V2 no FilmCraft.
  3. Manter o texto do cenário em V1: letreiros, telas, cópias, quadros permanecem nas cenas V01..Vnn.
  4. Exportação dupla rigorosamente idêntica: exportar a versão com letras (V2 ativada), depois desativar V2 (timeline.setTrack {"track": "V2", "enabled": false}) para exportar a versão clean com montagem e áudio 100 % idênticos, depois reativar V2 antes da salvaguarda final do .fcproj.

D. Ações visuais durante as passagens instrumentais (Zero curva de áudio genérica)

  1. 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.
  2. 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.
  3. 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.
  4. 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

  1. 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.
  2. 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.
  3. Inicializar e preencher audio/lyrics_timing.json marcando 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)

  1. Redigir um plano de montagem curto (tabela tempo / seção / local & enquadramento / ação visual desenhada / tratamento das letras).
  2. 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

  1. Construir as cenas 2D (V01..Vnn) seguindo as regras de âncoras, parenting neutro e empilhamento de craft-2d-animation (usando ec_runtime.py).
  2. Gerar as composições de letras transparentes (L01..Lnn, exceto instrumentais) diretamente de audio/lyrics_timing.json via lyrics_overlay.py.
  3. Controle rápido por capturas (render-frame --max-side 960) nos planos chave (e --transparent nas letras) para corrigir imediatamente qualquer sobreposição ou deslocamento de âncora antes do render de vídeo.
  4. 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.
  5. Render completo de baixo consumo para ./renders_vfx/ via render_ec_batch.sh (sequencial 1 render por vez, ProRes HQ RGB para V*, ProRes 4444 RGBA para L*, retomada automática via ffprobe).
  6. Salvar projects/<clip>.ecproj.

Etapa 4 — Montagem & Exportação dupla no FilmCraft

  1. Montar a sequência Rec.709 via assemble_filmcraft.py (ou via MCP file.newProject, file.newSequence, media_import, timeline.place, markers.add):
    • A1: áudio master original intacto (volumeDb: 0.0)
    • V1: V01..Vnn.mov colocados em seu quadro exato (frame: f0)
    • V2: L01..Lnn.mov (ProRes 4444 RGBA) colocados nos mesmos quadros exatos (audio: false)
  2. Verificar a sequência (inspect sequence) + renderizar alguns quadros compostos V1+V2 e V1 sozinho para confirmar a decupagem alpha e a presença do texto diegético na versão clean.
  3. Exportar a versão com letras (*_lyrics.mp4), desativar V2, exportar a versão clean (*_clean.mp4), depois reativar V2 e salvar projects/<clip>.fcproj.

Etapa 5 — Auditoria final obrigatória (Com som + Sem som)

  1. 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.
  2. 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.
  3. Apresentar os entregáveis e listar explicitamente os marcos marcados "uncertain": true em lyrics_timing.json.

5. Ferramentas compartilhadas T3 Code & Dependências

As ferramentas reutilizáveis estão em ~/.t3/shared/craft-video/:

FerramentaCaminhoUso clipe musical
Análise & corte de áudio 44,1 kHz~/.t3/shared/craft-video/audio_cues.pyDur... [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.json antes de iniciar renders longos.
  • Manter backups dos projetos .ecproj e .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.

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

Habilidades Relacionadas