Communitygithub.com

puntorigen/skills

Compétences d'agent locales pour Cursor et autres agents de codage IA — 100% sur votre machine, sans cloud, sans clés API. Optimisé pour Apple Silicon (MLX/Metal) : génération d'images locale, clonage vocal, musique de fond, vidéo parlante, vidéo→splat 3D & STL imprimable, enregistrement d'actions web et édition de documents Word .docx.

Qu'est-ce que skills ?

Cette compétence pour agents IA (comme Claude Code, Cursor, ou Codex) permet de générer de la musique instrumentale originale et libre de droits, entièrement hors ligne, à partir d'une simple description textuelle. Elle exploite le modèle ACE-Step 1.5 via MLX sur Apple Silicon pour des performances natives rapides. L'agent orchestre le processus : affiner le brief utilisateur en une consigne précise (genre, ambiance, tempo, instruments), générer plusieurs variantes, laisser l'utilisateur choisir, et éventuellement mixer la piste retenue sous une narration vocale via un script dédié. La compétence est 100% locale : code, poids du modèle et fichiers audio résident dans `~/.bg-music/`, sans aucune dépendance externe ni appel API. Elle est particulièrement utile pour les créateurs de contenu, développeurs et équipes produit qui ont besoin de musiques de fond personnalisées pour des démos, reels ou vidéos, tout en garantissant la confidentialité des données et la liberté d'utilisation commerciale.

Compatible avec✓Claude Code~Codex CLI✓Cursor
npx skills add puntorigen/skills

Demander à votre IA préférée

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

Documentation

Musique de fond

Générez de la musique instrumentale originale, libre de droits, pour des reels et vidéos de démo à partir d'un brief textuel - entièrement hors ligne. Un wrapper pilote ACE-Step 1.5 (le modèle de musique) ; vous (le modèle) transformez le brief en une bonne consigne, générez quelques candidats, laissez l'utilisateur choisir, et éventuellement mixez le gagnant sous une narration.

Fonctionne en tandem avec la compétence voice-clone-narration : générez la voix off là-bas, la musique ici, puis mix_voiceover.sh réduit automatiquement la musique sous la narration pour une piste audio de reel finalisée.

flowchart LR
  Brief["brief : genre, ambiance, bpm, durée"] --> Gen["generate_music.py<br/>ACE-Step 1.5 (MLX), instrumental"]
  Gen --> Mp3["mp3 candidats"]
  Nar["narration.mp3 (optionnel)"] -.-> Mix["mix_voiceover.sh<br/>ffmpeg sidechain ducking"]
  Mp3 -.-> Mix
  Mix -.-> Reel["reel-audio.mp3"]

Tout se trouve en dehors du dépôt dans ~/.bg-music/ (le checkout d'ACE-Step, les poids du modèle et l'audio généré).

Prérequis

  • uv (gestionnaire de paquets) et git - le modèle est une application uv sync, pas une simple installation pip. L'installation le configure dans un environnement isolé.
  • ffmpeg dans le PATH (encodage MP3 + mixage). Arrêtez-vous et demandez à l'utilisateur de brew install ffmpeg s'il manque.
  • ~10 Go d'espace disque libre pour le code + les poids du modèle (téléchargés une fois depuis Hugging Face, anonymement - sans jeton). Prévoyez plus si vous utilisez des variantes de modèle plus grandes.
  • Mac Apple Silicon pour le chemin natif rapide (MLX). Sur CUDA/CPU, il utilise PyTorch en secours (plus lent sur CPU). 16 Go de mémoire unifiée suffisent pour le niveau par défaut 2B-turbo + 0.6B-LM.
  • Internet uniquement au premier lancement (pour récupérer le code + les poids). La génération est hors ligne.

Configuration

Résolvez le répertoire de la compétence et exécutez la configuration une fois (clone ACE-Step 1.5 et synchronise son environnement - le premier lancement télécharge les dépendances et peut prendre plusieurs minutes) :

SKILL_DIR="<le dossier où se trouve ce SKILL.md>"   # ex. .cursor/skills/bg-music
bash "$SKILL_DIR/scripts/setup_env.sh"

Définissez ensuite les chemins utilisés par la génération (la configuration les affiche aussi) :

BG_HOME="${BG_MUSIC_HOME:-$HOME/.bg-music}"
PY="$BG_HOME/ACE-Step-1.5/.venv/bin/python"

Flux de travail

Copiez cette liste de vérification et suivez la progression :

- [ ] 1. Confirmer le brief : genre, ambiance, tempo (BPM), durée, instruments clés
- [ ] 2. Configuration : exécuter setup_env.sh (première fois uniquement)
- [ ] 3. Écrire une consigne concrète ; générer 2 candidats
- [ ] 4. Lire/lié les candidats ; laisser l'utilisateur choisir (régénérer si nécessaire)
- [ ] 5. (optionnel) Mixer le gagnant sous une narration mp3 avec ducking
- [ ] 6. Fournir le(s) mp3

Étape 1 : Affiner le brief

La qualité de la musique dépend d'une consigne concrète. Obtenez ces informations de l'utilisateur (ou inférez-les et annoncez vos choix) :

  • Genre/style : lo-fi hip hop, orchestral cinématique, ambient corporate, synthwave, folk acoustique, pop entraînante...
  • Ambiance : calme, inspirante, tendue, rêveuse, énergique, mélancolique.
  • Tempo : lent / moyen / rapide, ou un BPM explicite (ex. 90).
  • Durée : secondes (10-600 ; les reels durent généralement 30-120).
  • Instruments clés (optionnel) : piano Rhodes, nappes chaudes, batterie douce, guitare nylon.

Étape 3 : Générer

"$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"
  • Les pistes sont instrumentales par défaut (pas de voix).
  • --count 2 produit deux variations parmi lesquelles choisir (lofi-1.mp3, lofi-2.mp3).
  • Écrit les MP3 et affiche leurs chemins + durées. Le premier lancement télécharge les poids du modèle ; les lancements suivants sont beaucoup plus rapides.

Les bonnes consignes sont spécifiques et séparées par des virgules. Incluez genre + ambiance + 2-3 instruments + un mot de tempo + "instrumental"/"loopable". Exemples :

  • "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"

Étape 5 : Mixer sous une narration (optionnel)

Si l'utilisateur a aussi une voix off (par exemple depuis la compétence voice-clone-narration), réduisez la musique automatiquement en dessous :

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 musique baisse automatiquement lorsque la voix parle (compression sidechain), puis remonte dans les silences. Elle est bouclée pour couvrir la narration et fondue en entrée/sortie. Réglez avec --music-gain (niveau de fond, par défaut -8 dB), --duck (force du ducking, par défaut 8) et --fade.

Étape 6 : Fournir

Incorporez ou liez le mp3 choisi. Les fichiers générés restent dans ~/.bg-music/out/.

Options clés (generate_music.py)

OptionDéfautObjectif
--prompt(obligatoire)Description de la musique : genre, ambiance, instruments, atmosphère.
--duration60Durée en secondes (10-600).
--bpmautoTempo en BPM (30-300) ; omettre pour laisser le modèle choisir.
--count2Combien de variations générer.
--outout/music-<ts>.mp3Chemin de sortie (ou préfixe quand --count > 1).
--seedaléatoireFixe pour la reproductibilité.
--keyscaleautoTon musical, ex. "A minor".
--vocalsdésactivé (instrumental)Autoriser les voix (rarement souhaité pour une musique de fond).
--steps8Étapes de diffusion (turbo par défaut ; plus = plus lent, légèrement meilleur).
--mp3-quality2ffmpeg libmp3lame -q:a (0=meilleur..9=plus petit).
--keep-wavdésactivéConserver le wav intermédiaire.

Options clés (mix_voiceover.sh)

OptionDéfautObjectif
--voice(obligatoire)Narration mp3/wav (reste à plein volume).
--music(obligatoire)Musique de fond mp3/wav (réduite + bouclée pour couvrir la voix).
--out(obligatoire)Mp3 mixé en sortie.
--music-gain-8Niveau de base de la musique en dB (plus bas = fond plus silencieux).
--duck8Force du ducking (ratio du compresseur) ; plus élevé = la musique baisse plus sous la parole.
--fade2Secondes de fondu entrée/sortie de la musique.
--mp3-quality2ffmpeg libmp3lame -q:a.

Sécurité

  • Signalez la musique générée par IA là où la plateforme ou le contexte l'exige.
  • Utilisation commerciale : ACE-Step 1.5 est sous licence MIT et entraîné sur des données sous licence / libres de droits / synthétiques, donc les pistes générées sont généralement sûres à utiliser. Néanmoins, selon l'avertissement du modèle, évitez les consignes qui copient l'identité d'un artiste ou d'un morceau spécifique, et vérifiez l'originalité avant une publication commerciale.
  • Ne téléchargez jamais les briefs, consignes ou audio généré vers un service externe. Tout reste local dans ~/.bg-music/.

Anti-patrons

  • Consignes vagues d'un mot ("musique", "quelque chose de cool") - vous obtenez un résultat générique. Donnez genre + ambiance + instruments + tempo.
  • Demander des voix alors que vous n'avez besoin que d'un fond - gardez-le instrumental (le défaut) pour qu'il se place proprement sous la narration.
  • Générer une seule piste et l'envoyer - générez --count 2 et laissez l'utilisateur choisir.
  • Superposer la musique sous une voix off manuellement - utilisez mix_voiceover.sh pour que la musique baisse automatiquement sous la parole.
  • Demander "une chanson qui ressemble exactement à <artiste/morceau>" - risque d'originalité et de licence.
  • Commettre quoi que ce soit de ~/.bg-music/ dans un dépôt.

Ressources

  • Zoo de modèles (pourquoi 2B-turbo sur 16 Go), l'aide-mémoire complet des paramètres, les modèles de consigne par ambiance, la justification des licences et le dépannage : REFERENCE.md
  • Générer la narration à mixer sous la musique : la compétence voice-clone-narration.
  • Vérifier l'audio final dans une vidéo : la compétence review-mp4.

Skills associés