O que Música de Fundo faz?
Gere música instrumental original e livre de royalties para reels e vídeos demo a partir de um briefing textual - totalmente offline. Um wrapper controla o ACE-Step 1.5 (o modelo de música); você (o modelo) transforma o briefing em um bom prompt, gera alguns candidatos, deixa o usuário escolher e, opcionalmente, mixa o vencedor sob uma narração.
Combina com a skill clonagem-de-voz-narração: gere a narração lá, a
música aqui, depois use mix_voiceover.sh para abaixar a música sob a narração,
criando uma faixa de áudio final para o reel.
flowchart LR
Brief["brief: gênero, clima, bpm, duração"] --> Gen["generate_music.py<br/>ACE-Step 1.5 (MLX), instrumental"]
Gen --> Mp3["mp3 candidatos"]
Nar["narration.mp3 (opcional)"] -.-> Mix["mix_voiceover.sh<br/>sidechain ffmpeg"]
Mp3 -.-> Mix
Mix -.-> Reel["reel-audio.mp3"]
Tudo reside fora do repositório em ~/.bg-music/ (o checkout do ACE-Step,
pesos do modelo e áudio gerado).
Pré-requisitos
- uv (gerenciador de pacotes) e git - o modelo é um app
uv sync, não uma instalação pip simples. A configuração o instala em um ambiente isolado. - ffmpeg no PATH (codificação MP3 + mixagem). Peça ao usuário para
brew install ffmpegse estiver faltando. - ~10 GB de espaço livre em disco para o código + pesos do modelo (baixados uma vez do Hugging Face, anonimamente - sem token). Reserve mais se for usar variantes maiores do modelo.
- Mac com Apple Silicon para o caminho nativo rápido (MLX). Em CUDA/CPU ele usa PyTorch como fallback (mais lento em CPU). 16 GB de memória unificada são suficientes para o nível padrão 2B-turbo + 0.6B-LM.
- Internet apenas na primeira execução (para buscar código + pesos). A geração é offline.
Configuração
Resolva o diretório da skill e execute a configuração uma vez (clona o ACE-Step 1.5 e sincroniza seu ambiente - a primeira execução baixa as dependências e pode levar vários minutos):
SKILL_DIR="<a pasta onde este SKILL.md reside>" # ex: .cursor/skills/bg-music
bash "$SKILL_DIR/scripts/setup_env.sh"
Depois defina os handles usados pela geração (a configuração também os imprime):
BG_HOME="${BG_MUSIC_HOME:-$HOME/.bg-music}"
PY="$BG_HOME/ACE-Step-1.5/.venv/bin/python"
Fluxo de Trabalho
Copie esta lista de verificação e acompanhe o progresso:
- [ ] 1. Confirmar o briefing: gênero, clima, andamento (BPM), duração, instrumentos-chave
- [ ] 2. Configuração: executar setup_env.sh (apenas na primeira vez)
- [ ] 3. Escrever um prompt concreto; gerar 2 candidatos
- [ ] 4. Tocar/fornecer links dos candidatos; deixar o usuário escolher (regenerar se necessário)
- [ ] 5. (opcional) Mixar o vencedor sob uma narração mp3 com ducking
- [ ] 6. Entregar o(s) mp3(s)
Passo 1: Definir o briefing
A qualidade da música depende de um prompt concreto. Extraia estes elementos do usuário (ou deduza e explicite suas escolhas):
- Gênero/estilo: lo-fi hip hop, orquestral cinematográfico, ambiente corporativo, synthwave, folk acústico, pop animado...
- Clima: calmo, edificante, tenso, sonhador, enérgico, melancólico.
- Andamento: lento / médio / rápido, ou um BPM explícito (ex: 90).
- Duração: segundos (10-600; reels geralmente têm 30-120).
- Instrumentos-chave (opcional): piano Rhodes, pads quentes, bateria suave, guitarra de nylon.
Passo 3: Gerar
"$PY" "$SKILL_DIR/scripts/generate_music.py" \
--prompt "lo-fi hip hop quente, piano Rhodes suave, chiado suave de vinil, bateria descontraída, loopável, instrumental" \
--bpm 80 --duration 60 --count 2 \
--out "$BG_HOME/out/lofi.mp3"
- As faixas são instrumentais por padrão (sem vocais).
--count 2produz duas variações para escolha (lofi-1.mp3,lofi-2.mp3).- Escreve os MP3s e imprime seus caminhos + durações. A primeira execução baixa os pesos do modelo; as execuções subsequentes são muito mais rápidas.
Bons prompts são específicos e separados por vírgula. Inclua gênero + clima + 2-3 instrumentos + uma palavra de andamento + "instrumental"/"loopável". Exemplos:
"orquestral inspirador cinematográfico, cordas suaves, piano, percussão sutil que cresce para um inchaço caloroso, instrumental""ambiente corporativo limpo, pads synth suaves, plucks leves, otimista, minimalista, instrumental""synthwave intenso, baixo analógico, arpejos retrô, bateria forte, energia de direção noturna, instrumental"
Passo 5: Mixar sob uma narração (opcional)
Se o usuário também tiver um voiceover (ex: da skill clonagem-de-voz-narração), abaixe a música sob ele automaticamente:
bash "$SKILL_DIR/scripts/mix_voiceover.sh" \
--voice ~/.voice-clone-narration/out/test-en.mp3 \
--music "$BG_HOME/out/lofi-1.mp3" \
--out ~/Desktop/reel-audio.mp3
A música abaixa automaticamente sempre que a voz está falando (compressão sidechain), depois
volta nos intervalos. Ela é repetida para cobrir a narração e tem fade in/out. Ajuste com
--music-gain (nível de fundo, padrão -8 dB), --duck (força do ducking, padrão 8) e --fade.
Passo 6: Entregar
Incorpore ou forneça link do mp3 escolhido. Os arquivos gerados ficam em ~/.bg-music/out/.
Opções principais (generate_music.py)
| Opção | Padrão | Finalidade |
|---|---|---|
--prompt | (obrigatório) | Descrição da música: gênero, clima, instrumentos, vibe. |
--duration | 60 | Duração em segundos (10-600). |
--bpm | auto | Andamento em BPM (30-300); omita para deixar o modelo escolher. |
--count | 2 | Quantas variações gerar. |
--out | out/music-<ts>.mp3 | Caminho de saída (ou prefixo quando --count > 1). |
--seed | aleatório | Fixar para reprodutibilidade. |
--keyscale | auto | Tom musical, ex: "Lá menor". |
--vocals | desligado (instrumental) | Permitir vocais (raramente desejado para música de fundo). |
--steps | 8 | Etapas de difusão (padrão turbo; mais = mais lento, marginalmente melhor). |
--mp3-quality | 2 | ffmpeg libmp3lame -q:a (0=melhor..9=menor). |
--keep-wav | desligado | Manter o wav intermediário. |
Opções principais (mix_voiceover.sh)
| Opção | Padrão | Finalidade |
|---|---|---|
--voice | (obrigatório) | Narração mp3/wav (permanece no nível total). |
--music | (obrigatório) | Música de fundo mp3/wav (sofre ducking + repetição para cobrir a voz). |
--out | (obrigatório) | Mp3 mixado de saída. |
--music-gain | -8 | Nível base da música em dB (menor = fundo mais baixo). |
--duck | 8 | Força do ducking (razão do compressor); maior = a música abaixa mais sob a fala. |
--fade | 2 | Segundos de fade in/out da música. |
--mp3-quality | 2 | ffmpeg libmp3lame -q:a. |
Segurança
- Divulgue que a música foi gerada por IA onde a plataforma ou contexto assim exigir.
- Uso comercial: ACE-Step 1.5 é licenciado sob MIT e treinado em dados licenciados / livres de royalties / sintéticos, portanto as faixas geradas são geralmente seguras para uso. Ainda assim, conforme o aviso do próprio modelo, evite prompts que copiem a identidade de um artista ou faixa específicos e verifique a originalidade antes do lançamento comercial.
- Nunca envie briefings, prompts ou áudio gerado para qualquer serviço externo.
Tudo permanece local em
~/.bg-music/.
Anti-padrões
- Prompts vagos de uma palavra ("música", "algo legal") - você obtém saída genérica. Dê gênero + clima + instrumentos + andamento.
- Pedir vocais quando você só precisa de um fundo - mantenha instrumental (o padrão) para que se assente sob a narração de forma limpa.
- Gerar uma única faixa e entregá-la - gere
--count 2e deixe o usuário escolher. - Sobrepor música sob um voiceover manualmente - use
mix_voiceover.shpara que a música abaixe sob a fala automaticamente. - Pedir "uma música que soe exatamente como <artista/faixa>" - risco de originalidade e licenciamento.
- Commitar qualquer coisa de
~/.bg-music/em um repositório.
Recursos
- Zoológico de modelos (por que 2B-turbo em 16 GB), a cheatsheet completa de parâmetros, padrões de prompt por clima, justificativa de licenciamento e solução de problemas: REFERENCE.md
- Gerar a narração para mixar sob a música: a skill clonagem-de-voz-narração.
- Verificar o áudio final em um vídeo: a skill revisar-mp4.