¿Qué hace text-to-bgm?
Genera música de fondo (BGM) a partir de descripciones de texto usando IA local en Macs con Apple Silicon. Impulsado por mlx-audiocraft — MusicGen de Meta portado al framework MLX de Apple.
- 100% sin conexión — sin nube, sin claves API, sin internet después de descargar el modelo
- Privado — toda la generación ocurre en el dispositivo
- Rápido — aceleración GPU MLX en M1/M2/M3/M4
Cuándo usarlo
Usa este skill cuando el usuario pida:
- Generar música de fondo / BGM / música instrumental
- Crear música ambiental, beats lo-fi, banda sonora cinematográfica
- Hacer audio para videos, juegos, podcasts o sesiones de estudio/concentración
- Cualquier solicitud de texto a música en macOS Apple Silicon
NO uses para:
- Efectos de sonido → usa
audiogen-mlx(incluido en mlx-audiocraft) - Voces / canto → MusicGen es débil en voces
- Canciones completas producidas → considera ACE-Step para música más larga y estructurada
Requisitos
- macOS con Apple Silicon (M1, M2, M3, M4)
- Python 3.10+ (se recomienda 3.11)
- RAM: 8 GB mínimo para modelo pequeño, 16 GB+ para modelos grandes
- Disco: 1.2 GB (pequeño) a ~6.5 GB (estéreo-grande) por modelo
Instalación
# Instalación en una línea
pip install mlx-audiocraft
# Verificar
musicgen-mlx --help
O usa el script de instalación incluido:
bash setup.sh
Uso
Básico
musicgen-mlx "beats lo-fi chill para estudio con piano suave" -d 30 -o bgm.wav
Referencia completa de CLI
musicgen-mlx [-h] [-m MODELO] [-o ARCHIVO] [-d SEG] [--no-open]
[--top-k K] [--temperature T] [--cfg-coef C]
prompt
Argumentos:
prompt Descripción textual de la música a generar
Opciones:
-m, --model NOMBRE Modelo de HuggingFace (por defecto: facebook/musicgen-small)
-o, --output ARCHIVO Ruta de salida WAV (por defecto: ./musicgen_output.wav)
-d, --duration SEG Duración en segundos (por defecto: 8)
--no-open No abrir el archivo después de la generación
--top-k K Muestreo top-k (por defecto: 250)
--temperature T Temperatura de muestreo (por defecto: 1.0)
--cfg-coef C Coeficiente de guía libre de clasificador (por defecto: 3.0)
Modelos
| Modelo | Tamaño | Calidad | Velocidad (M4 Max) | Caso de uso |
|---|---|---|---|---|
facebook/musicgen-small | 300M / 1.2GB | Buena | 1.3x tiempo real | Opción predeterminada |
facebook/musicgen-medium | 1.5B / 3.4GB | Mejor | ~0.6x tiempo real | Mejor calidad |
facebook/musicgen-large | 3.3B / 5.5GB | La mejor (mono) | ~0.4x tiempo real | Alta calidad |
facebook/musicgen-stereo-large | 3.3B / 6.5GB | La mejor (estéreo) | ~0.3x tiempo real | Salida final |
Parámetros de generación
| Parámetro | Rango | Efecto |
|---|---|---|
--temperature | 0.5–1.5 | Más alto = más creativo/variado. Más bajo = más predecible |
--top-k | 100–500 | Más alto = opciones de notas más diversas |
--cfg-coef | 1.0–7.0 | Más alto = adherencia más estricta al prompt. Por defecto 3.0 es equilibrado |
Usando el script envolvente
Para mayor comodidad, usa generate_bgm.sh:
bash generate_bgm.sh "música de banda sonora orquestal épica para tráiler" -d 45
Opciones: -m <modelo>, -d <segundos>, -t <temperatura>, -o <salida>
API de Python
import mlx.core as mx
import numpy as np
import soundfile as sf
from audiocraft_mlx.models.musicgen import MusicGen
# Cargar modelo
mg = MusicGen.get_pretrained("facebook/musicgen-small")
# Establecer parámetros de generación
mg.set_generation_params(duration=30, temperature=1.0, top_k=250, cfg_coef=3.0)
# Generar
audio = mg.generate(["jazz lo-fi con saxo suave y batería relajante"])
# Guardar
wav = np.array(audio[0]) # [canales, muestras]
sf.write("output.wav", wav.T, mg.sample_rate)
Ingeniería de prompts
Consulta prompts.md para una guía completa con ejemplos.
Consejos rápidos:
- Empieza con género/estilo: "lo-fi hip hop", "orquestal cinematográfico", "electrónica ambiental"
- Añade instrumentos: "piano cálido", "pads de sintetizador suaves", "guitarra acústica"
- Describe estado de ánimo/atmósfera: "relajante", "edificante", "misterioso", "enérgico"
- Incluye cualidades de producción: "crujido de vinilo", "reverberación", "80 BPM", "compresión sidechain"
- Termina con propósito: "perfecto para estudiar", "fondo para podcast", "música de menú de juego"
⚠️ MusicGen funciona mejor con prompts en inglés y música instrumental.
Procedimiento (para Agentes de IA)
- Verificar instalación: Ejecuta
musicgen-mlx --help. Si falta, instala conpip install mlx-audiocraft. - Recopilar requisitos: Pregunta al usuario sobre género, estado de ánimo, duración. Si es vago, sugiere estilos BGM populares.
- Seleccionar modelo: Usa por defecto
facebook/musicgen-small(rápido, 300M). Usafacebook/musicgen-mediumpara mejor calidad ofacebook/musicgen-stereo-largepara los mejores resultados. - Elaborar prompt: Construye una descripción en inglés de 10 a 30 palabras siguiendo la guía de prompts en prompts.md.
- Establecer duración: 15–30 s para loops, 30–60 s para BGM corto, 60–120 s para piezas más largas.
- Generar: Ejecuta
musicgen-mlx "<prompt>" -m <modelo> -d <seg> -o <ruta>.wav - Informar: Dile al usuario la ruta del archivo de salida. Ofrece regenerar con parámetros ajustados si es necesario.
Problemas comunes
- ⚠️ La primera ejecución descarga modelos — 1.2–6.5 GB desde HuggingFace. Advierte al usuario.
- ⚠️ Solo Apple Silicon — NO funciona en Macs Intel.
- ⚠️ Duración predeterminada de 8 s — siempre especifica
-dpara BGM. - ⚠️ Solo instrumental — débil en voces/letras.
- ⚠️ Licencia no comercial — CC-BY-NC 4.0. No para uso comercial.
- ⚠️ Consume mucha RAM — máquinas de 8 GB deben usar solo modelos pequeños/medianos.
- ⚠️ Lento en modelos grandes — estéreo-grande es ~0.3x tiempo real. Una generación de 60 s toma ~3 minutos.
Verificación
# 1. Verificar CLI
musicgen-mlx --help
# 2. Prueba rápida
musicgen-mlx "melodía de piano" -d 5 -o /tmp/test_bgm.wav
# 3. Verificar salida
file /tmp/test_bgm.wav
# Esperado: RIFF (little-endian) data, WAVE audio
# 4. Escuchar
open /tmp/test_bgm.wav
Archivos
| Archivo | Propósito |
|---|---|
SKILL.md | Este archivo — definición del skill y referencia |
setup.sh | Script de instalación en un comando |
generate_bgm.sh | Envolvente para generación fácil para agentes |
prompts.md | Guía de ingeniería de prompts con plantillas de género |