Música de Fondo
Genera música instrumental original y libre de regalías para reels y videos demo a partir de un brief de texto - completamente fuera de línea. Un wrapper impulsa ACE-Step 1.5 (el modelo de música); tú (el modelo) das forma al brief para crear un buen prompt, generas un par de candidatos, dejas que el usuario elija y, opcionalmente, mezclas el ganador debajo de una narración.
Se combina con la habilidad clonación-de-voz-narración: genera la locución allí, la
música aquí, luego mix_voiceover.sh atenúa la música bajo la narración para obtener una
pista de audio de reel terminada.
flowchart LR
Brief["brief: género, estado de ánimo, bpm, duración"] --> Gen["generate_music.py<br/>ACE-Step 1.5 (MLX), instrumental"]
Gen --> Mp3["mp3s candidatos"]
Nar["narración.mp3 (opcional)"] -.-> Mix["mix_voiceover.sh<br/>ffmpeg sidechain ducking"]
Mp3 -.-> Mix
Mix -.-> Reel["reel-audio.mp3"]
Todo vive fuera del repositorio en ~/.bg-music/ (el checkout de ACE-Step,
pesos del modelo y audio generado).
Requisitos previos
- uv (gestor de paquetes) y git - el modelo es una aplicación
uv sync, no una instalación pip simple. La configuración lo instala en un entorno aislado. - ffmpeg en PATH (codificación MP3 + mezcla). Detente y pide al usuario que
ejecute
brew install ffmpegsi falta. - ~10 GB de disco libre para el código + los pesos del modelo (descargados una vez desde Hugging Face, anónimamente - sin token). Reserva más si usas variantes de modelo más grandes.
- Mac con Apple Silicon para la ruta nativa rápida (MLX). En CUDA/CPU recurre a PyTorch (más lento en CPU). 16 GB de memoria unificada son suficientes para el nivel 2B-turbo + 0.6B-LM predeterminado.
- Internet solo en la primera ejecución (para obtener código + pesos). La generación es offline.
Configuración
Resuelve el directorio de la habilidad y ejecuta la configuración una vez (clona ACE-Step 1.5 y sincroniza su entorno - la primera ejecución descarga dependencias y puede tardar varios minutos):
SKILL_DIR="<la carpeta donde vive este SKILL.md>" # ej. .cursor/skills/bg-music
bash "$SKILL_DIR/scripts/setup_env.sh"
Luego establece los manejadores utilizados por la generación (la configuración también los imprime):
BG_HOME="${BG_MUSIC_HOME:-$HOME/.bg-music}"
PY="$BG_HOME/ACE-Step-1.5/.venv/bin/python"
Flujo de trabajo
Copia esta lista de verificación y sigue el progreso:
- [ ] 1. Confirmar el brief: género, estado de ánimo, tempo (BPM), duración, instrumentos clave
- [ ] 2. Configuración: ejecutar setup_env.sh (solo la primera vez)
- [ ] 3. Escribir un prompt concreto; generar 2 candidatos
- [ ] 4. Reproducir/enlazar los candidatos; dejar que el usuario elija (regenerar si es necesario)
- [ ] 5. (Opcional) Mezclar el ganador bajo una narración en mp3 con ducking
- [ ] 6. Entregar los mp3(s)
Paso 1: Definir el brief
La calidad de la música depende de un prompt concreto. Obtén esto del usuario (o infiere y indica tus elecciones):
- Género/estilo: lo-fi hip hop, orquestal cinematográfico, ambiente corporativo, synthwave, folk acústico, pop animado...
- Estado de ánimo: tranquilo, edificante, tenso, soñador, enérgico, melancólico.
- Tempo: lento / medio / rápido, o un BPM explícito (ej. 90).
- Duración: segundos (10-600; los reels suelen durar 30-120).
- Instrumentos clave (opcional): piano Rhodes, pads cálidos, batería suave, guitarra nylon.
Paso 3: Generar
"$PY" "$SKILL_DIR/scripts/generate_music.py" \
--prompt "warm lo-fi hip hop, mellow Rhodes piano, soft vinyl crackle, laid-back drums, loopable, instrumental" \
--bpm 80 --duration 60 --count 2 \
--out "$BG_HOME/out/lofi.mp3"
- Las pistas son instrumentales por defecto (sin voces).
--count 2produce dos variaciones para elegir (lofi-1.mp3,lofi-2.mp3).- Escribe MP3s e imprime sus rutas + duraciones. La primera ejecución descarga los pesos del modelo; las ejecuciones posteriores son mucho más rápidas.
Los buenos prompts son específicos y separados por comas. Incluye género + estado de ánimo + 2-3 instrumentos + una palabra de tempo + "instrumental"/"loopable". Ejemplos:
"cinematic inspiring orchestral, soft strings, piano, subtle percussion building to a warm swell, instrumental""clean corporate ambient, gentle synth pads, light plucks, optimistic, minimal, instrumental""driving synthwave, analog bass, retro arpeggios, punchy drums, night-drive energy, instrumental"
Paso 5: Mezclar bajo una narración (opcional)
Si el usuario también tiene una locución (ej. de la habilidad clonación-de-voz-narración), atenúa la música automáticamente debajo de ella:
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
La música se baja automáticamente cuando la voz está hablando (compresión sidechain), luego
vuelve a subir en los silencios. Se repite para cubrir la narración y se desvanece al inicio/fin.
Ajusta con --music-gain (nivel de fondo, por defecto -8 dB), --duck (intensidad de atenuación,
por defecto 8) y --fade.
Paso 6: Entregar
Incrusta o enlaza el mp3 elegido. Los archivos generados permanecen en ~/.bg-music/out/.
Opciones clave (generate_music.py)
| Opción | Predeterminado | Propósito |
|---|---|---|
--prompt | (obligatorio) | Descripción de la música: género, estado de ánimo, instrumentos, ambiente. |
--duration | 60 | Longitud en segundos (10-600). |
--bpm | auto | Tempo en BPM (30-300); omite para que el modelo elija. |
--count | 2 | Cuántas variaciones generar. |
--out | out/music-<ts>.mp3 | Ruta de salida (o prefijo cuando --count > 1). |
--seed | aleatorio | Fijar para reproducibilidad. |
--keyscale | auto | Tono musical, ej. "La menor". |
--vocals | off (instrumental) | Permitir voces (rara vez se desea para música de fondo). |
--steps | 8 | Pasos de difusión (predeterminado turbo; más = más lento, marginalmente mejor). |
--mp3-quality | 2 | ffmpeg libmp3lame -q:a (0=mejor..9=más pequeño). |
--keep-wav | off | Conservar el wav intermedio. |
Opciones clave (mix_voiceover.sh)
| Opción | Predeterminado | Propósito |
|---|---|---|
--voice | (obligatorio) | mp3/wav de narración (se mantiene al nivel completo). |
--music | (obligatorio) | mp3/wav de música de fondo (se atenúa + se repite para cubrir la voz). |
--out | (obligatorio) | mp3 mezclado de salida. |
--music-gain | -8 | Nivel base de la música en dB (más bajo = fondo más silencioso). |
--duck | 8 | Intensidad de atenuación (relación del compresor); más alto = la música baja más bajo el habla. |
--fade | 2 | Segundos de desvanecimiento de entrada/salida de la música. |
--mp3-quality | 2 | ffmpeg libmp3lame -q:a. |
Seguridad
- Revela la música generada por IA donde la plataforma o el contexto lo requieran.
- Uso comercial: ACE-Step 1.5 tiene licencia MIT y está entrenado con datos con licencia / libres de regalías / sintéticos, por lo que las pistas generadas son generalmente seguras de usar. Aún así, según el propio descargo de responsabilidad del modelo, evita prompts que copien la identidad de un artista o pista específicos, y verifica la originalidad antes de la publicación comercial.
- Nunca subas briefs, prompts o audio generado a ningún servicio externo.
Todo permanece local en
~/.bg-music/.
Antipatrones
- Prompts vagos de una palabra ("música", "algo cool") - obtienes una salida genérica. Da género + estado de ánimo + instrumentos + tempo.
- Pedir voces cuando solo necesitas un fondo - mantenlo instrumental (el valor predeterminado) para que se asiente limpiamente debajo de la narración.
- Generar una sola toma y enviarla - genera
--count 2y deja que el usuario elija. - Superponer música manualmente debajo de una locución - usa
mix_voiceover.shpara que la música se atenúe automáticamente debajo del habla. - Preguntar por "una canción que suene exactamente como <artista/pista>" - riesgo de originalidad y licencia.
- Confirmar cualquier cosa de
~/.bg-music/en un repositorio.
Recursos
- Zoo de modelos (por qué 2B-turbo en 16 GB), la hoja de referencia de parámetros completa, patrones de prompt por estado de ánimo, justificación de licencias y solución de problemas: REFERENCE.md
- Generar la narración para mezclar debajo de la música: la habilidad clonación-de-voz-narración.
- Verificar el audio final en un video: la habilidad revisar-mp4.