haoyiyin/text-to-bgm

O que text-to-bgm faz?

Gere música de fundo (BGM) a partir de descrições de texto usando IA local em Macs com Apple Silicon. Desenvolvido com mlx-audiocraft — uma adaptação do MusicGen da Meta para o framework MLX da Apple.

• 100% offline — sem nuvem, sem chaves de API, sem internet após o download do modelo
• Privado — toda a geração ocorre no dispositivo
• Rápido — aceleração por GPU MLX em M1/M2/M3/M4

Quando Usar

Use esta habilidade quando o usuário pedir para:

• Gerar música de fundo / BGM / música instrumental
• Criar música ambiente, batidas lo-fi, trilha sonora cinematográfica
• Produzir áudio para vídeos, jogos, podcasts ou sessões de estudo/foco
• Qualquer solicitação de texto para música em macOS Apple Silicon

NÃO use para:

• Efeitos sonoros → use audiogen-mlx (incluído no mlx-audiocraft)
• Vocais / canto → MusicGen é fraco em vocais
• Músicas completas de produção → considere ACE-Step para músicas mais longas e estruturadas

Requisitos

• macOS com Apple Silicon (M1, M2, M3, M4)
• Python 3.10+ (recomendado 3.11)
• RAM: 8 GB mínimo para modelo pequeno, 16 GB+ para modelos grandes
• Disco: 1,2 GB (pequeno) a ~6,5 GB (estéreo-grande) por modelo

Instalação

# Instalação em uma linha
pip install mlx-audiocraft

# Verificar
musicgen-mlx --help

Ou use o script de configuração incluso:

bash setup.sh

Uso

Básico

musicgen-mlx "batidas lo-fi relaxantes para estudo com piano suave" -d 30 -o bgm.wav

Referência Completa da CLI

musicgen-mlx [-h] [-m MODEL] [-o FILE] [-d SEC] [--no-open]
             [--top-k K] [--temperature T] [--cfg-coef C]
             prompt

Argumentos:
  prompt              Descrição textual da música a ser gerada

Opções:
  -m, --model NOME    Modelo do HuggingFace (padrão: facebook/musicgen-small)
  -o, --output ARQUIVO   Caminho WAV de saída (padrão: ./musicgen_output.wav)
  -d, --duration SEG   Duração em segundos (padrão: 8)
  --no-open           Não abrir o arquivo após a geração
  --top-k K           Amostragem top-k (padrão: 250)
  --temperature T     Temperatura de amostragem (padrão: 1.0)
  --cfg-coef C        Coeficiente de orientação livre de classificador (padrão: 3.0)

Modelos

Modelo	Tamanho	Qualidade	Velocidade (M4 Max)	Caso de Uso
facebook/musicgen-small	300M / 1,2GB	Boa	1,3x tempo real	Escolha padrão
facebook/musicgen-medium	1,5B / 3,4GB	Melhor	~0,6x tempo real	Melhor qualidade
facebook/musicgen-large	3,3B / 5,5GB	Melhor (mono)	~0,4x tempo real	Alta qualidade
facebook/musicgen-stereo-large	3,3B / 6,5GB	Melhor (estéreo)	~0,3x tempo real	Saída final

Parâmetros de Geração

Parâmetro	Intervalo	Efeito
--temperature	0,5–1,5	Maior = mais criativo/variado. Menor = mais previsível
--top-k	100–500	Maior = escolhas de notas mais diversas
--cfg-coef	1,0–7,0	Maior = aderência mais estrita ao prompt. Padrão 3,0 é equilibrado

Usando o Script de Wrapper

Para conveniência, use generate_bgm.sh:

bash generate_bgm.sh "música de trilha cinematográfica épica para trailer" -d 45

Opções: -m <modelo>, -d <segundos>, -t <temperatura>, -o <saída>

API Python

import mlx.core as mx
import numpy as np
import soundfile as sf
from audiocraft_mlx.models.musicgen import MusicGen

# Carregar modelo
mg = MusicGen.get_pretrained("facebook/musicgen-small")

# Configurar parâmetros de geração
mg.set_generation_params(duration=30, temperature=1.0, top_k=250, cfg_coef=3.0)

# Gerar
audio = mg.generate(["jazz lo-fi com saxofone suave e batidas tranquilas"])

# Salvar
wav = np.array(audio[0])  # [canais, amostras]
sf.write("output.wav", wav.T, mg.sample_rate)

Engenharia de Prompts

Consulte prompts.md para um guia completo com exemplos.

Dicas rápidas:

• Comece com gênero/estilo: "lo-fi hip hop", "orquestral cinematográfico", "eletrônico ambiente"
• Adicione instrumentos: "piano suave", "pads de sintetizador suaves", "violão acústico"
• Descreva humor/atmosfera: "relaxante", "edificante", "misterioso", "energético"
• Inclua qualidades de produção: "chiado de vinil", "reverberação", "80 BPM", "compressão sidechain"
• Termine com propósito: "perfeito para estudar", "fundo para podcast", "música de menu de jogo"

⚠️ MusicGen funciona melhor com prompts em inglês e música instrumental.

Procedimento (para Agentes de IA)

1. Verificar instalação: Execute musicgen-mlx --help. Se ausente, instale via pip install mlx-audiocraft.
2. Coletar requisitos: Pergunte ao usuário sobre gênero, humor, duração. Se vago, sugira estilos populares de BGM.
3. Selecionar modelo: Padrão: facebook/musicgen-small (rápido, 300M). Use facebook/musicgen-medium para melhor qualidade ou facebook/musicgen-stereo-large para melhores resultados.
4. Criar prompt: Construa uma descrição em inglês de 10 a 30 palavras seguindo o guia de prompts em prompts.md.
5. Definir duração: 15–30s para loops, 30–60s para BGM curto, 60–120s para peças mais longas.
6. Gerar: Execute musicgen-mlx "<prompt>" -m <modelo> -d <seg> -o <caminho>.wav
7. Relatar: Informe ao usuário o caminho do arquivo de saída. Ofereça-se para regenerar com parâmetros ajustados, se necessário.

Armadilhas

• ⚠️ Primeira execução baixa modelos — 1,2–6,5 GB do HuggingFace. Avise o usuário.
• ⚠️ Apenas Apple Silicon — NÃO funciona em Macs Intel.
• ⚠️ Duração padrão de 8s — sempre especifique -d para BGM.
• ⚠️ Apenas instrumental — fraco em vocais/letras.
• ⚠️ Licença não comercial — CC-BY-NC 4.0. Não é para uso comercial.
• ⚠️ Consumo de RAM — máquinas com 8 GB devem usar apenas modelos pequenos/médios.
• ⚠️ Lento em modelos grandes — estéreo-grande é ~0,3x tempo real. Uma geração de 60s leva ~3 minutos.

Verificação

# 1. Verificar CLI
musicgen-mlx --help

# 2. Teste rápido
musicgen-mlx "melodia de piano" -d 5 -o /tmp/test_bgm.wav

# 3. Verificar saída
file /tmp/test_bgm.wav
# Esperado: RIFF (little-endian) data, WAVE audio

# 4. Ouvir
open /tmp/test_bgm.wav

Arquivos

Arquivo	Propósito
SKILL.md	Este arquivo — definição e referência da habilidade
setup.sh	Script de instalação em um comando
generate_bgm.sh	Wrapper para geração fácil e amigável ao agente
prompts.md	Guia de engenharia de prompts com modelos de gênero