g1304458637-afk/cinematic-music-video-studio

Diretor de Videoclipe Cinematográfico

Um skill de produção para criar um curta-metragem assistível cuja espinha dorsal é uma música — não um modelo de letra, não um slideshow, não uma pilha de clipes generativos não relacionados. Cada quadro é desenhado por código e é reproduzível a partir de um número inteiro de quadro.

O skill é deliberadamente música-primeiro e evidência-primeiro:

1. meça a música antes de imaginar imagens;
2. escreva uma tese e uma nota do diretor antes de escrever uma única tomada;
3. trave uma edição precisa por quadro antes de renderizar;
4. prove o visual e o movimento em um piloto de 10–20 s;
5. renderize em unidades de tomada retomáveis;
6. verifique o arquivo que você realmente enviou.

Regra dura: nunca invente um timestamp, um BPM, uma linha de letra, um resultado de renderização ou uma aprovação de QC. Se faltar evidência, marque o item como não verificado e diga isso nas notas de entrega.

---

Quando usar

Use quando o usuário pedir um videoclipe, um curta animado cortado para música, uma sequência de abertura ou uma tarefa de "transformar minha música em filme", e a renderização local com código for aceitável. A saída padrão é 9:16, 1080×1920, 24 fps, H.264 + AAC, com um arquivo de legenda opcional.

Não use este skill para baixar áudio protegido por direitos autorais, para clonar a semelhança de um artista vivo ou para reproduzir um MV existente tomada por tomada. Peça ao usuário áudio que ele tenha o direito de usar.

Pré-requisitos (verifique, não assuma)

• Node 20+, ffmpeg/ffprobe, Google Chrome ou Chromium.
• Python 3.10–3.13 com numpy scipy soundfile librosa (matplotlib opcional, Pillow para folhas de contato).
• puppeteer-core, p5, p5.brush no node_modules do projeto.
• Disco suficiente para quadros: JPEG 1080×1920 q94 ≈ 0,2–0,5 MB/quadro; um filme de 4 minutos ≈ 1–3 GB.
• Para letras em chinês, um arquivo LRC/SRT do usuário ou um modelo Whisper local; nunca raspe e apresente o tempo de um site aleatório de letras como verificado.

Execute scripts/doctor.sh (ou os comandos equivalentes em references/render-recovery.md) e registre o resultado. Se faltar um pré-requisito, corrija-o ou relate o bloqueio.

---

O loop de produção

0. Recepção e direitos

Colete: caminho do áudio, texto da letra e qualquer arquivo de tempo, proporção/resolução/fps, prazo, idioma e contexto de uso. Copie o áudio como somente leitura para assets/; nunca sobrescreva o original. Declare a suposição de direitos em README.md (por exemplo, "áudio fornecido pelo usuário, uso privado apenas").

1. Master musical (portão M)

python scripts/analyze_music.py assets/song.m4a \
  --out analysis --lrc assets/song.lrc --sections analysis/sections.json \
  --asr analysis/asr/whisper.json --fps 24

Produz analysis/audiomap.json, lyrics.json, lyrics.srt, analysis.md, analysis.png. O mapa contém duração, grade de tempo ajustada por fase, batidas/tempos fortes, curvas de energia/espectral, janelas de clímax candidatas, intervalos de seção e tempo de linha de letra com proveniência.

Aceitação:

• duração e taxa de amostragem correspondem ao arquivo fornecido;
• coerência de tempo é relatada; se < 0,6, inspecione de ouvido/espectrograma e considere um mapa de tempo;
• toda linha de letra tem uma fonte de tempo (lrc_line, srt_line, cross_checked, sem_tempo);
• loudness não é tratado como clímax emocional sem uma verificação cruzada estrutural.

Se o usuário não fornecer tempo de letra, execute scripts/align_lyrics.py com uma transcrição ASR local e revise-a. Mantenha tempo de frase (marca de barra/frase, usada para cortes) separado de início vocal (usado para legendas). Nunca desloque silenciosamente a música inteira para fazer um corte parecer limpo.

2. Três conceitos, depois um (portão D1)

Escreva storyboard/concepts.md com três filmes genuinamente diferentes. Avalie cada um em adequação de letra/música, completude da história, impacto emocional, originalidade visual, viabilidade de código e capacidade de ser assistido em formato longo. Selecione um e escreva o motivo. Não comece o código de tomada até que isso exista.

Em seguida, escreva storyboard/director_score.json: tese, antítese, curva emocional, capítulos visuais (mundo/paleta/espaço/câmera/gramática), mapa de contraste, motivos e recompensas, desejos/necessidades/arcos do elenco, papéis das tomadas e transições, mapa som–visual.

Uma tomada que não pode declarar seu papel, transição de entrada e transição de saída não está pronta.

3. Linguagem visual e testes (portão D2)

Escreva style-guide.md e uma bíblia de arte/personagens antes de animar. Defina: paleta com valores hexadecimais e um roteiro de cores; gramática de lente/composição para 9:16; regras de linha e textura; proporções de personagens, silhuetas, continuidade de guarda-roupa e alcance de expressão; iluminação; vocabulário de transição; as coisas exatas que o filme não fará (por exemplo, "sem partículas flutuantes sem causa narrativa").

Renderize 1–3 quadros de estilo e uma folha de personagens. Julgue-os em resolução total, não em miniaturas. Se o visual for fraco, mude a linguagem agora — não depois de 40 tomadas.

4. Edição precisa por quadro (portão E)

Escreva storyboard/timeline.json com fps, total_frames, shots[] e, para cada tomada: id, start_frame, end_frame, section, lyric_refs, size, composition, environment, action, expression, camera, transition_in/out, emotion, function, implementation, complexity. As tomadas devem ser contíguas e cobrir todo o áudio.

python scripts/validate_timeline.py \
  --timeline storyboard/timeline.json --audiomap analysis/audiomap.json \
  --out analysis/timeline_validation.md

O validador é um portão rígido: sem lacunas, sem sobreposições, último quadro ≥ ceil(duração×fps), toda linha de letra contabilizada, nenhum corte absurdamente longe de uma batida/letra/seção sem um motivo escrito.

5. Piloto (portão P)

Renderize 10–20 s contendo pelo menos: uma tomada de estabelecimento ampla, um plano médio de personagem, um close-up, uma ação rápida ou impacto, e uma transição. Construa uma folha de contato e um clipe assistível com o áudio real. Verifique:

• O estilo se mantém em 100%?
• As proporções do personagem, figurino e luz são contínuos?
• O movimento da câmera é motivado ou deriva sem motivo?
• Os cortes caem em eventos musicais?
• O renderizador sobrevive a 300+ quadros sem uma exceção?
• Qual é o ms/quadro medido e o custo de disco?

Corrija o piloto antes da passagem completa. Registre o desempenho medido em LESSONS.md.

6. Renderização completa (portão R)

Use um contrato de página determinístico: window.renderAt(t) -> dataURL, sem Math.random, ruído com semente, índices de quadro inteiros. Renderize tomada por tomada ou quadro por quadro com escritas atômicas; mantenha um manifesto de unidades concluídas e hashes para que uma tomada alterada invalide apenas a si mesma.

node scripts/render.mjs --project . --start 0 --end 232.6 --out renders/frames

Prefira unidades por tomada e um caminho --force/--shot em vez de "apagar tudo e começar de novo". Não renderize a mesma tomada aprovada duas vezes. Nunca deixe um quadro com falha passar como completo: um quadro deve existir, ser não nulo e decodificar.

7. Montagem (portão A)

ffmpeg -y -framerate 24 -i renders/frames/f_%06d.jpg -i assets/song.m4a \
  -c:v libx264 -preset slow -crf 16 -pix_fmt yuv420p -profile:v high -level 4.2 \
  -c:a aac -b:a 256k -ar 44100 -shortest -movflags +faststart output/final.mp4

O áudio master é imutável. Não fade, re-time ou re-codifique a música para se ajustar à imagem. A última tomada deve cobrir a cauda do áudio; sem cauda preta, sem acorde final truncado.

8. QC (portão Q)

Execute ambos e anexe a evidência:

python scripts/qc_video.py output/final.mp4 --audio assets/song.m4a \
  --expected-frames 5583 --timeline storyboard/timeline.json --out analysis/qc

Técnico: decodificação, duração vs áudio (tolerância ≤ 0,12 s), contagens de fluxo, resolução, fps, pix_fmt, contagem de quadros, blackdetect, freezedetect, cobertura, quadros ausentes/substitutos. Visual: folhas de contato em resolução total, quadros-chave por cena, tiras de quadros consecutivos nos cortes, verificações pontuais de sincronia A/V, inspeção de continuidade de personagem, segurança de título/legenda.

QC visual não é automatizado. Diga exatamente quais tomadas você assistiu, em que resolução e o que encontrou. Um ffprobe limpo não é uma aprovação visual.

9. Entrega

Envie: MP4 master, pré-visualização de baixa resolução, storyboard.md, timeline.json, style-guide.md, qc-report.md, README.md, SRT opcional e a fonte reproduzível. Mantenha o áudio e as letras localmente, a menos que o usuário tenha os direitos de publicá-los. Adicione uma entrada datada em LESSONS.md.

---

Contrato de arquivos

projeto/
  assets/            # song.m4a, lyrics.lrc/srt, referências fornecidas pelo usuário (não sobrescrever)
  analysis/          # audiomap.json, lyrics.json, sections.json, validação, QC
  storyboard/        # concepts.md, director_score.json, timeline.json, storyboard.md
  characters/        # bíblia de arte, folhas de modelo
  src/               # código de desenho determinístico: lib/, custom_shots.js, shots.js
  studio.html        # contrato window.renderAt(t)
  renders/           # frames/ (sequência global), pilot/, manifests
  previews/          # pilot.mp4, folhas de contato, painel de revisão
  output/            # MP4 final, pré-visualização, SRT, storyboard.md, timeline.json, style-guide.md, QC

Regras de ofício não negociáveis

• A música é a linha do tempo master. A imagem é cortada para a música; a música nunca é cortada para a imagem.
• Um filme, não uma playlist de visuais. Motivos retornam e mudam.
• Um refrão repetido pode rimar visualmente; não pode reutilizar a mesma composição inalterada.
• Personagens precisam de desejo, obstáculo, escolha, consequência. Rostos e mãos devem atuar.
• Movimentos de câmera precisam de uma motivação (revelar, pressionar, liberar), não um Ken Burns padrão.
• Cada tomada deve conter pelo menos um elemento em movimento que pertença ao mundo da história.
• Não esconda uma história ausente atrás de partículas, rampas de velocidade ou bloom gratuito.
• Se o resultado honesto for estilizado e limitado, diga isso no relatório de QC; não o chame de fotorrealista.

Falha e recuperação

O renderizador é projetado para falhar alto e retomar barato:

• escritas de quadro atômicas (*.tmp → renomear), nunca meio JPEG contado como concluído;
• um manifesto por tomada com hash de origem, quadro inicial/final e status;
• --shot / --start/--end re-renderiza apenas o intervalo afetado;
• mantenha a última codificação boa conhecida; nunca sobrescreva o master até que o QC passe.

Se o navegador ou GPU falhar, tente a unidade duas vezes com uma nova página/perfil. Se um quadro falhar três vezes, pare, isole a tomada e relate o número do quadro e o erro. Não preencha com um quadro duplicado ou um still.

Índice de referência

• references/directing.md — seleção de conceito, nota do diretor, duração, ritmo, finais.
• references/visual-language.md — composição 9:16, câmeras, cor, personagem, textura.
• references/audio-lyrics.md — medição, tempo ajustado por fase, seções, alinhamento honesto.
• references/render-recovery.md — contrato determinístico, manifestos, codificação, retomada.
• references/qc.md — portões rígidos/suaves, folhas de contato, o que a automação não pode ver.
• templates/ — nota do diretor, linha do tempo, cartão de tomada, guia de estilo, configuração do projeto.
• tests/ — testes de analisador, cobertura e validador; execute bash tests/run_tests.sh.
• LESSONS.md — o que quebrou em produções reais e o que consertou.

Créditos e licenças

Os padrões do motor são informados pelo ClaudeAnimationBase (John Heibel) licenciado sob MIT e pelo claude-music-video-skill (Sage Arbor). Os conceitos de fluxo de trabalho foram estudados do musical-mv-storyboard, que não tem licença; nenhum código ou texto dele é copiado. Consulte THIRD_PARTY_LICENSES.md. p5 é LGPL-2.1, p5.brush MIT, puppeteer-core Apache-2.0, librosa ISC, ffmpeg GPL. A música e as letras usadas em um projeto não fazem parte deste skill.