Communitygithub.com

Música de Fundo

Gere músicas instrumentais originais e livres de royalties para reels e vídeos demo, totalmente offline no seu Mac Apple Silicon.

O que é Música de Fundo?

Esta skill permite gerar música instrumental original e livre de royalties a partir de uma breve descrição textual, utilizando o modelo ACE-Step 1.5 rodando localmente via MLX (Apple Silicon). Toda a execução é offline, sem necessidade de chaves de API ou conexão com a nuvem. O fluxo de trabalho guia o usuário na criação de um prompt concreto (gênero, clima, BPM, duração), gera duas variações para escolha e, opcionalmente, mixa a faixa escolhida com uma narração (gerada pela skill voice-clone-narration) usando compressão sidechain. A skill é ideal para produtores de conteúdo que precisam de trilhas sonoras personalizadas sem depender de serviços externos ou conexão com a internet.

Funciona com✓Claude Code~Codex CLI✓Cursor
npx skills add puntorigen/skills

Perguntar na sua IA favorita

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

Documentação

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 ffmpeg se 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 2 produz 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çãoPadrãoFinalidade
--prompt(obrigatório)Descrição da música: gênero, clima, instrumentos, vibe.
--duration60Duração em segundos (10-600).
--bpmautoAndamento em BPM (30-300); omita para deixar o modelo escolher.
--count2Quantas variações gerar.
--outout/music-<ts>.mp3Caminho de saída (ou prefixo quando --count > 1).
--seedaleatórioFixar para reprodutibilidade.
--keyscaleautoTom musical, ex: "Lá menor".
--vocalsdesligado (instrumental)Permitir vocais (raramente desejado para música de fundo).
--steps8Etapas de difusão (padrão turbo; mais = mais lento, marginalmente melhor).
--mp3-quality2ffmpeg libmp3lame -q:a (0=melhor..9=menor).
--keep-wavdesligadoManter o wav intermediário.

Opções principais (mix_voiceover.sh)

OpçãoPadrãoFinalidade
--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-8Nível base da música em dB (menor = fundo mais baixo).
--duck8Força do ducking (razão do compressor); maior = a música abaixa mais sob a fala.
--fade2Segundos de fade in/out da música.
--mp3-quality2ffmpeg 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 2 e deixe o usuário escolher.
  • Sobrepor música sob um voiceover manualmente - use mix_voiceover.sh para 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.

Habilidades Relacionadas