Communitygithub.com

haoyiyin/text-to-bgm

Skill de agente de IA: Genera música de fondo a partir de descripciones de texto, 100% local en Macs con Apple Silicon

¿Qué es text-to-bgm?

Este skill permite a agentes de IA generar música de fondo (BGM) a partir de descripciones textuales, ejecutándose completamente en el dispositivo en Macs con Apple Silicon (M1-M4). Utiliza **mlx-audiocraft** — la adaptación oficial de MusicGen de Meta al framework MLX de Apple, ofreciendo aceleración GPU nativa y total privacidad al no requerir conexión a internet ni servicios en la nube. Soporta múltiples modelos (small, medium, large y stereo-large) que varían en tamaño y calidad, permitiendo generar desde 8 segundos hasta varios minutos de música instrumental. Es ideal para crear ambientes, bandas sonoras, beats lo-fi y música para videos, juegos o podcasts, pero no es adecuado para efectos de sonido ni voz cantada. El skill incluye un procedimiento detallado para agentes de IA, cubriendo instalación, selección de modelo, elaboración de prompts y generación mediante CLI o API de Python.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add haoyiyin/text-to-bgm

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

¿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

ModeloTamañoCalidadVelocidad (M4 Max)Caso de uso
facebook/musicgen-small300M / 1.2GBBuena1.3x tiempo realOpción predeterminada
facebook/musicgen-medium1.5B / 3.4GBMejor~0.6x tiempo realMejor calidad
facebook/musicgen-large3.3B / 5.5GBLa mejor (mono)~0.4x tiempo realAlta calidad
facebook/musicgen-stereo-large3.3B / 6.5GBLa mejor (estéreo)~0.3x tiempo realSalida final

Parámetros de generación

ParámetroRangoEfecto
--temperature0.5–1.5Más alto = más creativo/variado. Más bajo = más predecible
--top-k100–500Más alto = opciones de notas más diversas
--cfg-coef1.0–7.0Má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)

  1. Verificar instalación: Ejecuta musicgen-mlx --help. Si falta, instala con pip install mlx-audiocraft.
  2. Recopilar requisitos: Pregunta al usuario sobre género, estado de ánimo, duración. Si es vago, sugiere estilos BGM populares.
  3. Seleccionar modelo: Usa por defecto facebook/musicgen-small (rápido, 300M). Usa facebook/musicgen-medium para mejor calidad o facebook/musicgen-stereo-large para los mejores resultados.
  4. Elaborar prompt: Construye una descripción en inglés de 10 a 30 palabras siguiendo la guía de prompts en prompts.md.
  5. Establecer duración: 15–30 s para loops, 30–60 s para BGM corto, 60–120 s para piezas más largas.
  6. Generar: Ejecuta musicgen-mlx "<prompt>" -m <modelo> -d <seg> -o <ruta>.wav
  7. 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 -d para 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

ArchivoPropósito
SKILL.mdEste archivo — definición del skill y referencia
setup.shScript de instalación en un comando
generate_bgm.shEnvolvente para generación fácil para agentes
prompts.mdGuía de ingeniería de prompts con plantillas de género

Skills relacionados