Communitygithub.com

haoyiyin/text-to-bgm

Compétence d'agent IA pour générer de la musique de fond à partir de descriptions textuelles, 100 % en local sur les Mac Apple Silicon.

Qu'est-ce que text-to-bgm ?

Cette compétence permet à un agent IA (comme Claude Code, Cursor, ou Codex) de générer de la musique de fond instrumentale directement sur un Mac Apple Silicon, sans aucune connexion cloud ni clé API. Elle s'appuie sur **mlx-audiocraft**, une version optimisée avec MLX du modèle MusicGen de Meta, offrant une accélération GPU sur les puces M1/M2/M3/M4. L'utilisateur fournit une simple description textuelle en anglais, et l'agent utilise la ligne de commande `musicgen-mlx` pour produire un fichier WAV. La compétence gère la sélection du modèle (petit, moyen, grand, stéréo), les paramètres de génération (température, top-k, CFG), et l'ingénierie de prompt pour obtenir le style et l'ambiance souhaités. Elle est idéale pour créer des boucles lo-fi, des ambiances cinématiques, ou des fonds sonores pour vidéos, jeux ou podcasts, avec des performances allant de 1,3× le temps réel (petit modèle) à 0,3× le temps réel (stéréo grand).

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

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Que fait text-to-bgm ?

Générer de la musique de fond (BGM) à partir de descriptions textuelles en utilisant l'IA locale sur les Mac Apple Silicon. Propulsé par mlx-audiocraft — le portage de MusicGen de Meta vers le framework MLX d'Apple.

  • 100 % hors ligne — pas de cloud, pas de clés API, pas de connexion Internet après le téléchargement du modèle
  • Privé — toute la génération se fait sur l'appareil
  • Rapide — accélération GPU MLX sur M1/M2/M3/M4

Quand l'utiliser

Utilisez cette compétence lorsque l'utilisateur demande :

  • Générer de la musique de fond / BGM / musique instrumentale
  • Créer de la musique d'ambiance, des beats lo-fi, une bande-son cinématographique
  • Faire de l'audio pour des vidéos, jeux, podcasts ou des sessions d'étude/concentration
  • Toute demande de texte vers musique sur macOS Apple Silicon

À NE PAS utiliser pour :

  • Les effets sonores → utiliser audiogen-mlx (inclus dans mlx-audiocraft)
  • Les voix / le chant → MusicGen est faible sur les voix
  • Les chansons de production complètes → envisager ACE-Step pour une musique plus longue et structurée

Prérequis

  • macOS avec Apple Silicon (M1, M2, M3, M4)
  • Python 3.10+ (3.11 recommandé)
  • RAM : 8 Go minimum pour le petit modèle, 16 Go+ pour les grands modèles
  • Disque : 1,2 Go (petit) à ~6,5 Go (stéréo-grand) par modèle

Installation

# Installation en une ligne
pip install mlx-audiocraft

# Vérifier
musicgen-mlx --help

Ou utiliser le script d'installation inclus :

bash setup.sh

Utilisation

Basique

musicgen-mlx "lo-fi chill study beats with soft piano" -d 30 -o bgm.wav

Référence complète de l'interface en ligne de commande

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

Arguments :
  prompt              Description textuelle de la musique à générer

Options :
  -m, --model NOM     Modèle HuggingFace (défaut : facebook/musicgen-small)
  -o, --output FICHIER Chemin de sortie WAV (défaut : ./musicgen_output.wav)
  -d, --duration SEC  Durée en secondes (défaut : 8)
  --no-open           Ne pas ouvrir le fichier après génération
  --top-k K           Échantillonnage top-k (défaut : 250)
  --temperature T     Température d'échantillonnage (défaut : 1.0)
  --cfg-coef C        Coefficient de guidance sans classifieur (défaut : 3.0)

Modèles

ModèleTailleQualitéVitesse (M4 Max)Cas d'usage
facebook/musicgen-small300M / 1,2 GoBonne1,3× temps réelChoix par défaut
facebook/musicgen-medium1,5B / 3,4 GoMeilleure~0,6× temps réelMeilleure qualité
facebook/musicgen-large3,3B / 5,5 GoMeilleure (mono)~0,4× temps réelHaute qualité
facebook/musicgen-stereo-large3,3B / 6,5 GoMeilleure (stéréo)~0,3× temps réelSortie finale

Paramètres de génération

ParamètrePlageEffet
--temperature0,5–1,5Plus élevé = plus créatif/varié. Plus bas = plus prévisible
--top-k100–500Plus élevé = choix de notes plus diversifiés
--cfg-coef1,0–7,0Plus élevé = adhérence plus stricte au prompt. Défaut 3,0 est équilibré

Utilisation du script d'encapsulation

Pour plus de commodité, utilisez generate_bgm.sh :

bash generate_bgm.sh "cinematic orchestral epic trailer music" -d 45

Options : -m <modèle>, -d <secondes>, -t <température>, -o <sortie>

API Python

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

# Charger le modèle
mg = MusicGen.get_pretrained("facebook/musicgen-small")

# Définir les paramètres de génération
mg.set_generation_params(duration=30, temperature=1.0, top_k=250, cfg_coef=3.0)

# Générer
audio = mg.generate(["lo-fi jazz hop with smooth saxophone and chill drums"])

# Sauvegarder
wav = np.array(audio[0])  # [canaux, échantillons]
sf.write("output.wav", wav.T, mg.sample_rate)

Ingénierie de prompt

Consultez prompts.md pour un guide complet avec des exemples.

Conseils rapides :

  • Commencez par le genre/style : "lo-fi hip hop", "cinematic orchestral", "ambient electronic"
  • Ajoutez des instruments : "warm piano", "soft synth pads", "acoustic guitar"
  • Décrivez l'humeur/atmosphère : "relaxing", "uplifting", "mysterious", "energetic"
  • Incluez des qualités de production : "vinyl crackle", "reverb", "80 BPM", "sidechain compression"
  • Terminez par l'objectif : "perfect for study", "background for podcast", "game menu music"

⚠️ MusicGen fonctionne mieux avec des prompts en anglais et de la musique instrumentale.

Procédure (pour les agents IA)

  1. Vérifier l'installation : Exécuter musicgen-mlx --help. Si manquant, installer via pip install mlx-audiocraft.
  2. Recueillir les exigences : Demander à l'utilisateur le genre, l'humeur, la durée. Si vague, suggérer des styles BGM populaires.
  3. Sélectionner le modèle : Par défaut, utiliser facebook/musicgen-small (rapide, 300M). Utiliser facebook/musicgen-medium pour une meilleure qualité ou facebook/musicgen-stereo-large pour les meilleurs résultats.
  4. Rédiger le prompt : Construire une description anglaise de 10 à 30 mots en suivant le guide de prompt dans prompts.md.
  5. Définir la durée : 15–30 s pour les boucles, 30–60 s pour les BGM courts, 60–120 s pour les morceaux plus longs.
  6. Générer : Exécuter musicgen-mlx "<prompt>" -m <modèle> -d <sec> -o <chemin>.wav
  7. Rendre compte : Informer l'utilisateur du chemin du fichier de sortie. Proposer de régénérer avec des paramètres ajustés si nécessaire.

Pièges

  • ⚠️ Première exécution télécharge les modèles — 1,2–6,5 Go depuis HuggingFace. Avertir l'utilisateur.
  • ⚠️ Apple Silicon uniquement — ne fonctionne PAS sur les Mac Intel.
  • ⚠️ Durée par défaut de 8 s — toujours spécifier -d pour le BGM.
  • ⚠️ Instrumental uniquement — faible sur les voix/paroles.
  • ⚠️ Licence non commerciale — CC-BY-NC 4.0. Pas pour un usage commercial.
  • ⚠️ Gourmand en RAM — les machines avec 8 Go doivent utiliser uniquement les modèles petits/moyens.
  • ⚠️ Lent sur les grands modèles — stéréo-grand est ~0,3× le temps réel. Une génération de 60 s prend environ 3 minutes.

Vérification

# 1. Vérifier l'interface en ligne de commande
musicgen-mlx --help

# 2. Test rapide
musicgen-mlx "piano melody" -d 5 -o /tmp/test_bgm.wav

# 3. Vérifier la sortie
file /tmp/test_bgm.wav
# Attendu : RIFF (little-endian) data, WAVE audio

# 4. Écouter
open /tmp/test_bgm.wav

Fichiers

FichierObjectif
SKILL.mdCe fichier — définition et référence de la compétence
setup.shScript d'installation en une commande
generate_bgm.shScript d'encapsulation pour une génération facile par l'agent
prompts.mdGuide d'ingénierie de prompt avec des modèles de genres

Skills associés