sagearbor/claude-music-video-skill

---

nome: music-video descrição: Crie um videoclipe completo para uma música, desenhado inteiramente a partir de CÓDIGO (p5.js em Chrome headless: um cartoon pintado à mão com p5.brush, ou motion design vetorial nítido via --style, ffmpeg para áudio), sem geração de imagem/vídeo por IA e sem gastos de API além do plano Claude. Storyboard guiado por letras, grade de batidas ajustada por fase, legendas karaokê, um piloto de 30 segundos e, em seguida, capítulos construídos em paralelo por subagentes. Use quando solicitado a criar, animar ou storyboard um videoclipe, lyric video ou animação sincronizada com batidas, em QUALQUER repositório. metadados: autor: Sage Arbor

music-video

Subcomandos (verifique estes primeiro)

Invocação	Ação
/music-video help, /music-video sem música, ou "como uso isso?"	Imprima o bloco Ajuda abaixo literalmente, então verifique os pré-requisitos (node -v, ffmpeg -version, uv --version, Chrome presente) e reporte cada um como ✅/❌ com o comando de instalação. Pare; não inicie um vídeo.
/music-video lessons	Imprima LESSONS.md (a entrada mais recente por completo, as mais antigas apenas como cabeçalhos).
/music-video <arquivo_de_música> [lyrics.srt] [flags] [notas]	Analise as Flags abaixo, diga em uma linha quais portões estão ativos e quais escolhas já estão definidas, então execute o pipeline.

Ajuda

/music-video: transforme uma música em um videoclipe sincronizado com batidas, desenhado inteiramente em código,
             de cartoon pintado à mão a motion design nítido no estilo marketing.

USO
  /music-video ~/Downloads/song.mp3                     Arquivos Suno com letras embutidas não precisam de mais nada
  /music-video ~/Downloads/song.mp3 letras.srt          outras músicas: forneça letras com tempo (.srt)
  /music-video song.mp3 "estilo noir, detetive gato"     direção criativa opcional
  /music-video song.mp3 --auto --style=editorial --human=~/me.jpg --dir=~/musicaVideos
                                                        totalmente automatizado: cada escolha definida por flags
  /music-video help | lessons

FLAGS (padrão: pare no storyboard E no piloto para sua aprovação)
  --skip=storyboard        não espere pelo storyboard; ainda espere pelo piloto
  --skip=pilot             espere pelo storyboard; não espere pelo piloto
  --skip=all  (ou --auto)  sem paradas: música entra, MP4 sai, totalmente autônomo
  --design                 MAIS planejamento: adiciona uma etapa de design (folhas de modelo de personagem,
                           amostras de paleta, um quadro de estilo por capítulo)
                           e para para que você possa iterar na aparência antes de qualquer animação.
                           Combine: --design --skip=pilot

ESCOLHAS (as não definidas são perguntadas em uma breve entrevista; sob --auto, assumem o padrão)
  --style=pintado|editorial|keynote|geométrico|híbrido
                           pintado   = cartoon aquarela pintado à mão (o visual original)
                           editorial = papel quente, linhas finas precisas, serifa, calmo
                           keynote   = quase preto, gradientes brilhantes, feixes de luz, partículas
                           geométrico = grade suíça, blocos de cor, curvas paramétricas, sem serifa ousada
                           híbrido    = versos editoriais, refrões keynote
                           perguntar (padrão) = renderize um still de cada estilo e deixe você escolher
                           padrão auto: editorial
  --lyrics=cinética|barra|refrões|desligado   tipo cinético / barra de legenda / apenas linhas de refrão / nenhum
                           (padrão: cinético para estilos vetoriais, barra para pintado)
  --densidade=audaciosa|cada-linha|abstrata
                           audaciosa (padrão) = uma imagem forte a cada 2–4 linhas, piadas extras como
                           easter eggs de fundo; cada-linha = uma piada por linha de letra
  --human=FOTO|pip        quem interpreta "você": caricatura a partir de uma foto, ou o Pip padrão
  --dir=PAI               onde as pastas de música vão (padrão ~/PROJETOS); PAI/_shared/
                           mantém itens reutilizáveis (sua foto, seu personagem) entre vídeos
  --interview / --no-interview   force ou pule a entrevista inicial (G0)

  Portões pulados não significam trabalho pulado: o artefato ainda é criado e auto-revisado,
  e as escolhas feitas são listadas em DECISIONS.md para você ler depois.

O QUE ACONTECE (cerca de 1,5–2 h com paradas; cerca de 45–60 min com --auto)
  1. Analisa a música: andamento, quedas, seções, tempo da letra
  1b. Entrevista: stills de estilo + quaisquer escolhas não definidas, PARA      (a menos que --auto / tudo definido)
  2. Escreve STORYBOARD.md e PARA para sua aprovação                            (a menos que --skip)
  2b. Com --design: folhas de modelo + quadros de estilo, PARA para iterar
  3. Constrói um clipe piloto de 30 s e PARA para que você possa assisti-lo      (a menos que --skip)
  4. Constrói o resto em paralelo (subagentes), verifica cada mudança de cena
  5. Renderiza out/<música>_full.mp4 (1080p, H.264 + AAC), pronto para YouTube

PRECISA   Node 20+, Google Chrome, ffmpeg, uv  (Mac: brew install node ffmpeg uv)
CUSTO    nenhum gasto de API; usa seu plano Claude (uma música completa consome uma parte considerável do uso)
SAÍDA    uma pasta de projeto (padrão ~/PROJETOS/<música>-video/, ou --dir), fora de qualquer repositório
APÓS     "adicione as lições de hoje à skill music-video" torna o próximo vídeo melhor

O exemplo finalizado é o vídeo zoo2 ("Please Select Your Ending", 4:30): cerca de 100 cenas, construído em cerca de 1 h 40 min de relógio. examples/zoo2/ tem seu storyboard, cada arquivo de capítulo e o making-of com cronograma, tokens e custo. Leia LESSONS.md antes de começar: é o registro de melhorias e substitui qualquer coisa aqui que contradiga.

Por que código, não geração

Modelos de imagem (Deforum, SDXL-Turbo img2img, etc.) adivinham novamente a cada quadro, o que causa flicker, rostos derretendo e mãos ruins. A tentativa 1 do zoo2 fez isso durante a noite e foi rejeitada. Quadros desenhados em código são funções puras do tempo da música: suaves, no modelo e exatamente na batida. Modelos de vídeo em nuvem (Kling, Seedance, Veo) são a outra rota, a cerca de $70–300 por música.

Flags e portões

Analise as flags dos argumentos e de palavras simples: "sem paradas", "totalmente autônomo", "apenas faça" significam --skip=all; "pule a aprovação do storyboard" significa --skip=storyboard; "deixe-me ver os personagens primeiro", "planeje mais" significam --design. Os valores combinam com vírgulas (--skip=storyboard,design). Flag desconhecida: informe e pare.

Portão	Padrão	Quando pulado
G0 entrevista	PARE quando qualquer escolha abaixo estiver não definida	Sob --auto/--no-interview, escolhas não definidas assumem seus padrões e são registradas em DECISIONS.md.
G1 storyboard	PARE	Escreva, execute uma passagem de autocrítica contra a folha de letras (uma ideia por linha? todo refrão uma recompensa? o motivo retorna no final?), então continue.
G2 design (apenas com --design)	PARE, itere até aprovação	--skip=design mantém a etapa mas autocritica as folhas em vez de esperar.
G3 piloto	PARE	Ainda construa o piloto (ele cria os SETS compartilhados que os capítulos precisam). Faça duas passagens de revisão de folha de contato e corrija os bugs usuais de primeira passagem antes de continuar.

Escolhas (--style, --lyrics, --densidade, --human, --dir; tabela na Ajuda). Palavras simples também contam: "limpo", "corporativo", "marketing", "não infantil", "nítido" significam um estilo vetorial (pergunte qual, ou editorial sob --auto); "como o vídeo zoo", "pintado à mão" significam pintado. Registre as escolhas finais no topo de STORYBOARD.md e em src/config.js como PROJECT.style, PROJECT.lyrics, para que os subagentes as herdem.

Um portão é pulado apenas quando o usuário disse isso; em caso de dúvida, pare. Uma PARADA é real: termine o turno e espere. Para cada portão pulado, anexe a DIR/DECISIONS.md: o portão, o que foi decidido, as alternativas que você ponderou, e os caminhos das imagens que você revisou. Vincule DECISIONS.md no relatório final para que o usuário possa auditá-lo. Nunca pule a verificação final do ffprobe e a verificação pontual de letra/quadro na etapa 8: essas são verificação, não aprovação.

Pipeline (faça nestas ordem; as PARADAs são reais a menos que uma flag as tenha pulado)

1. Projeto. Crie a pasta do projeto fora de qualquer repositório: PAI/<slug-da-musica>/ onde PAI é --dir (padrão ~/PROJETOS), e mova a música para dentro de assets/. Coloque uma foto de referência (--human) em PAI/_shared/. bash ~/.claude/skills/music-video/scripts/setup_project.sh PAI/<slug-da-musica> Isso clona ClaudeAnimationBase em UPSTREAM_PIN, adiciona src/cast.js (Pip, adereços, karaokê) e conecta o karaokê. Precisa de Node 20+, Chrome, ffmpeg, uv e git.
2. Analise. uv run ~/.claude/skills/music-video/scripts/analyze_song.py MUSICA --project DIR [--srt LETRAS.srt] Isso escreve src/config.js (bpm e deslocamento ajustados por fase), src/lyrics.js e analysis.json. Nunca confie no BPM do librosa. Use o valor ajustado. Verifique energy_drops com os inícios da seção [Refrão]. Exportações do Suno incorporam uma faixa SRT com tags [Seção]; para outras músicas, obtenha os tempos primeiro (pergunte ao usuário, ou alinhe com whisper). O BPM ajustado pode sair em dobro do andamento sentido (baixa coerência, uma linha de letra = dois "compassos"): anote o andamento sentido no storyboard e use bt(2k) para batidas sentidas. 2b. Entrevista (G0). Pule apenas quando cada escolha estiver definida ou --auto/--no-interview foi fornecido. Caso contrário:
   • Estilo primeiro, como imagens. Se --style não estiver definido, renderize os stills de comparação: node design/style_tests.mjs (copiado pelo setup) desenha o MESMO momento de letra em editorial, keynote, geométrico e híbrido (--line1/--line2/--stamp definem as palavras), em out/design/style_test_*.jpg e style_tests_all.jpg. Envie eles, mais um quadro pintado do exemplo zoo2 se o usuário não o viu. As pessoas não conseguem escolher um estilo a partir de palavras.
   • Então pergunte as escolhas restantes não definidas em uma rodada AskUserQuestion (letras, densidade, humano), além das decisões específicas da música que um storyboard não pode tomar sozinho: quão literalmente mostrar marcas ou produtos reais, e como mostrar linhas de letra sensíveis (violência, escândalo, eventos reais).
   • Reutilize antes de redesenhar: se PAI/_shared/cast/ já tem um personagem para esta pessoa (ex.: <nome>.js + <nome>_body.js, aprovado em um vídeo anterior), copie esses arquivos para src/vec/, adicione suas tags <script> após vec.js, e use-os como estão (controles de expressão e pose incluídos). Redesenhe apenas se o usuário pedir mudanças. Após uma nova pessoa ser aprovada, copie seus arquivos para PAI/_shared/cast/ (com uma linha em _shared/README.md) para que o próximo vídeo os reutilize.
   • Com uma nova foto --human, olhe para ela e escreva os traços da caricatura em STORYBOARD.md (formato da cabeça, cabelo ou nenhum, pelo facial, sobrancelha, olhos, roupas usuais). Desenhe a partir dos traços; nunca trace ou cole a foto no vídeo. G0 — PARE após enviar os stills e perguntas. Combine as respostas nas escolhas, então prossiga.
3. Leia DIR/ANIMATION_GUIDE.md (as regras do kit), LESSONS.md e um capítulo de exemplo (examples/zoo2/scenes/c01_pilot.js) antes de escrever qualquer coisa. Para um estilo vetorial (qualquer um exceto pintado), o guia ainda se aplica nas seções de motor (timeline, shots(), câmera, easing, batida, loop de revisão), mas suas regras de aparência são invertidas: veja Estilos vetoriais abaixo.
4. Storyboard. Escreva DIR/STORYBOARD.md (formato: examples/zoo2/STORYBOARD.md) com a logline, elenco, arco de paleta, motivo, uma tabela de capítulos para toda a música, e o piloto cena por cena com "leituras" temporizadas. A densidade de imagem segue --densidade (audaciosa: uma imagem forte a cada 2–4 linhas, com o resto como easter eggs de fundo; cada-linha: uma por linha, atuada por personagens). G1 — PARE: mostre ao usuário e espere aprovação (com --skip=storyboard/all: autocritique, registre em DECISIONS.md, continue). 4b. Design (apenas com --design). Antes de qualquer animação, estabeleça a aparência como imagens estáticas em out/design/:
   • cast_<nome>.jpg folha de modelo por personagem: frente, três quartos e vista lateral, 4 expressões (neutra, alegria, medo, determinação), 3 poses de ação do storyboard, e uma linha de altura de todo o elenco;
   • palette.jpg: faixa de amostras por capítulo, mostrando o arco de paleta através da música;
   • style_<capítulo>.jpg: um quadro-chave finalizado por capítulo no momento heroico do storyboard, com letras. Desenhe-os com um scenes/design.js descartável (um capítulo apenas de folha fora do intervalo de tempo da música) e node render.mjs --sheet=...; o código do personagem vai em adições a src/cast.js que os capítulos reutilizarão, então designs aprovados vão direto para o vídeo. G2 — PARE: mostre as folhas; anote notas ("olhos maiores", "paleta de refrão mais quente"), re-renderize, repita até o usuário aprovar. Então atualize STORYBOARD.md para corresponder.
5. Piloto. Escolha cerca de 30 s que cruza um limite de seção para dentro de um refrão. Construa como um arquivo de capítulo com conjuntos compartilhados exportados em window.SETS (veja o final de c01_pilot.js). Verifique com node render.mjs --sheet=... --out=out/check/x.jpg e --strip=a:b, e olhe para as imagens. Os bugs usuais de primeira passagem: personagens muito pequenos (empurre a câmera para 1,3–1,5×), formas de fundo não largas o suficiente para panorâmicas rápidas, adereços escondidos sob a barra de karaokê. Para um estilo vetorial, construa em src/scenes/sets.js (o setup copia um funcional: sala, janela, corredor, rolagem, mescla de emoções; adapte-o). Renderize node render.mjs --clip --range=a:b --out=out/pilot.mp4. G3 — PARE: o usuário assiste e aprova ou solicita alterações (com --skip=pilot/all: duas passagens de revisão, registre em DECISIONS.md, continue).
6. Capítulos em paralelo. Adicione arquivos stub e suas tags <script> em studio.html para cada capítulo primeiro (um agente nunca deve editar um arquivo compartilhado). Então lance um subagente por capítulo (tipo fork, para que herde este contexto). Dê a cada um seu intervalo de tempo, suas linhas de letra, seu resumo de capítulo do storyboard, "SEU ARQUIVO APENAS", os SETS e globais compartilhados, e o contrato de emenda:
   • entre capítulos, uma transição com as MESMAS cores em ambos os lados (pintado: brushWipe, saída p<.5 nos últimos 0,3 s, entrada .5+lt/.6; vetorial: V.wipe, veja CHAPTER_BRIEF.md