MilkteaTW1/bgm-music-skill

bgm-music

Crie música de fundo que esteja na tonalidade, no andamento, com o volume correto, sem aspereza e com a duração certa - e então prove isso com medições antes de entregá-la.

Os scripts ficam em scripts/ ao lado deste arquivo (resolva com o diretório da skill, geralmente ~/.claude/skills/bgm-music/scripts). Requer apenas Python 3 + numpy + ffmpeg.

Limitações honestas - leia primeiro

• Você não consegue ouvir áudio. "Bom" aqui significa medido como bom: tonalidade, andamento, loudness, equilíbrio espectral, aspereza, dinâmica, emendas. A audição humana ainda é o juiz final.
• O compositor procedural cria música de produção limpa, de bom gosto e genérica: pads, plucks, bateria simples, uma melodia cativante de 4 compassos. Não soará como uma faixa do Suno. É ideal para BGM sob voz/interface, que é a maior parte do trabalho com vídeo.
• Para música mais rica e "produzida", use a camada neural (ACE-Step 1.5, instalação opcional de ~17 GB, 6-8 GB de VRAM). Veja references/neural-tier.md para configuração. Sempre pergunte antes de baixar.

Caminho rápido: pontuar um vídeo (use este primeiro)

S=~/.claude/skills/bgm-music/scripts
python $S/score_video.py --video out/video.mp4 [--voice vo.wav] --brief "<o que é>" --out out/final.mp4
python $S/score_video.py --frames 900 --fps 30 --brief "<o que é>" --audio-out public/bgm.mp3   # Remotion

Humor inferido a partir da descrição, duração exata, seções em cortes de cena detectados (--cuts 6,14 para defini-los), melhor de 4 sementes pelo avaliador, volume reduzido sob narração, relatório JSON (código de saída 2 se nenhum atingir 85). A skill de vídeo e a skill gsap-remotion chamam isso automaticamente. O fluxo de trabalho manual abaixo é para controle personalizado.

Fluxo de trabalho

1. Briefing. Obtenha: humor/gênero, duração total (corresponda ao comprimento do vídeo), loop ou faixa única, se há narração sobre ele, pontos de sincronia fixos (opcional). Use o humor que se encaixa no conteúdo (demo de produto -> corporate/uplifting, tutorial -> calm/lofi, trailer -> cinematic, bug/horror/alerta -> tense, infantil/jogo -> playful).
2. Composição.

   python scripts/bgm.py --mood corporate --duration 45 --out bgm.wav            # faixa única com fade-out
   python scripts/bgm.py --mood lofi --duration 32 --loop --out loop.wav          # loop sem emendas
   python scripts/bgm.py --mood uplifting --duration 30 --key D --seed 4 --lufs -20 --out bgm.mp3
   

   O andamento é ajustado para que compassos inteiros preencham exatamente a duração (seguro para comprimento de vídeo). Mesma semente = mesma faixa; mude --seed para uma melodia diferente, --key/--scale/--bpm a gosto.
3. Avaliação - obrigatória. Passe os mesmos fatos com os quais compôs:

   python scripts/evaluate.py bgm.wav --mood corporate --key G --scale major --bpm 104 \
       --spectrogram bgm.png [--loop]
   

   Leia o PNG: procure por paredes verticais/horizontais sólidas e brilhantes acima de ~8 kHz (chiado), lacunas ou seções planas. As métricas perdem coisas que a imagem mostra.
4. Iteração. Se a pontuação < 85 ou qualquer linha for FRACA/RUIM, aplique a correção impressa ao lado dela (veja tabela), re-renderize, re-avalie. Pare ao atingir >= 85 sem RUIM, ou após ~4 rodadas e diga o que resta. Nunca afirme qualidade que não mediu.
5. Entrega / mixagem.

   python scripts/mix_under_voice.py --voice vo.wav --music bgm.wav --out mixed.wav
   python scripts/mix_under_voice.py --video clip.mp4 --voice vo.wav --music bgm.wav --out final.mp4
   python scripts/mix_under_voice.py --video clip.mp4 --music bgm.wav --out scored.mp4
   

   A música tem volume reduzido em ~12 dB sob fala, fade in/out, normalizada para -16 LUFS.

Para Remotion: renderize bgm.mp3 em public/, use <Audio src={staticFile('bgm.mp3')} volume={0.35} loop />; o arquivo gerado já tem a loudness gerenciada.

Uso rápido da camada neural (ACE-Step)

cd ~/ace-step-1.5 && .venv/Scripts/python ~/.claude/skills/bgm-music/scripts/ace_generate.py   --prompt "uplifting corporate pop, plucked synth arpeggio, warm pad, soft kick"   --duration 30 --bpm 113 --key "C major" --n 3 --out bgm_ace.wav

Renderiza N sementes, pós-processa (corta silêncio final, doma agudos, fades, -18 LUFS), avalia cada uma e mantém a melhor. Cerca de 1-2 min por semente após o primeiro carregamento do modelo. Medido em uma RTX 3050 8 GB: a saída fica 2-5 s mais curta que o solicitado e a qualidade varia muito por semente (74-96 no mesmo prompt), então sempre mantenha a melhor-de-N e deixe mix_under_voice.py fazer loop/aparar. Prefira o método procedural quando comprimento exato, emendas de loop ou tonalidade garantida importam; prefira ACE quando timbre mais rico e arranjo importam e um humano ouvirá para confirmar.

O que o avaliador verifica (e a correção)

Critério	Aprovação	Correção típica
loudness	-21..-15 LUFS	--lufs -18
headroom	pico <= -1 dBFS, sem clipping	abaixe --lufs
brilho	6-16 kHz está 38-62 dB abaixo de 250-2k	hats/ruído muito alto: abaixe o ganho do ruído da bateria, abaixe tone_hz em master()
espectro	bandas compartilhadas na faixa (sem lama, sem estouro)	mude registro do pad / ganho do baixo / quantidade de reverb no humor
tonalidade	>= 90% da energia tonal na escala	tonalidade/escala errada passada, ou notas da melodia fora da escala
ritmo	andamento corresponde, pulso claro	aumente bateria/arp; ambientes/calmos/cinematográficos podem ter pulso fraco
dinâmica	2-9 dB de variação de nível ao longo da peça	muito plano: mais contraste entre seções; muito saltitante: menos
variedade	não congelado, não caótico	mude --seed, duração mais longa adiciona seções
estéreo	correlação L/R 0.25-0.97	muito mono: desafine/panorâmica; com fase: reduza largura do reverb
finais	fade out / emenda de loop inaudível	use --loop para loops; fade-out é automático

Uma falha crítica (tonalidade errada, clipping, loudness muito fora, chiado) limita a pontuação a 55-100 proporcionalmente, então um desastre não pode se esconder por trás das médias.

Benchmark de regressão

Após editar bgm.py, execute python scripts/bench.py <outdir>. Ele renderiza todos os humores (mais um loop e um corte de 15 s), imprime pontuações e escreve imagens PNG de espectrograma. Linha de base quando esta skill foi escrita: média 97,5, mínima 89,9 (ambient; pulso intencionalmente fraco). Controles negativos que o avaliador deve continuar reprovando: ruído branco (~41), senoide com clipping (~41), notas aleatórias (~60), tonalidade errada (limitada).

Extensão

• Novo humor = um dicionário em MOODS (escala, bpm, progressão prog de 4 acordes em graus da escala, nome do padrão de bateria, voz de teclas/lead, reverb, brilho). Grades de bateria ficam em DRUMS (16 passos/compasso; x = batida).
• Lições já pagas: a percussão de ruído deve ser filtrada com passa-baixas antes do reverb ou a faixa chia (descoberto apenas via espectrograma); as vozes dos acordes devem ter condução de vozes ou os pads saltam; a melodia usa notas do acorde em tempos fortes com uma forma de frase A-A-B-A'; a largura estéreo vem de vozes de pad desafinadas e uma IR de reverb parcialmente correlacionada.
• Ideias ainda não implementadas: modulação de tonalidade para o último refrão, variantes de walking bass para a linha de baixo, pontos de sincronia precisos por amostra (--hit-at), exportação de stems por seção.