haoyiyin/text-to-bgm

Was macht text-to-bgm?

Generiere Hintergrundmusik (BGM) aus Textbeschreibungen mit lokaler KI auf Apple Silicon Macs. Angetrieben von mlx-audiocraft – Metas MusicGen, portiert auf Apples MLX-Framework.

• 100% offline – keine Cloud, keine API-Schlüssel, kein Internet nach Modelldownload
• Privat – alle Generierung erfolgt auf dem Gerät
• Schnell – MLX-GPU-Beschleunigung auf M1/M2/M3/M4

Wann verwenden

Verwende diesen Skill, wenn der Benutzer Folgendes anfragt:

• Hintergrundmusik / BGM / Instrumentalmusik generieren
• Ambient-Musik, Lo-Fi-Beats, cineastischen Soundtrack erstellen
• Audio für Videos, Spiele, Podcasts oder Lern-/Fokussitzungen machen
• Jede Text-zu-Musik-Anfrage auf macOS Apple Silicon

NICHT verwenden für:

• Soundeffekte → verwende audiogen-mlx (in mlx-audiocraft enthalten)
• Gesang / Singen → MusicGen ist bei Gesang schwach
• Vollständige Produktionssongs → ziehe ACE-Step für längere, strukturierte Musik in Betracht

Voraussetzungen

• macOS mit Apple Silicon (M1, M2, M3, M4)
• Python 3.10+ (3.11 empfohlen)
• RAM: 8 GB Minimum für kleines Modell, 16 GB+ für große Modelle
• Speicher: 1,2 GB (klein) bis ~6,5 GB (Stereo-groß) pro Modell

Installation

# Einzeilige Installation
pip install mlx-audiocraft

# Überprüfen
musicgen-mlx --help

Oder verwende das beiliegende Setup-Skript:

bash setup.sh

Verwendung

Einfach

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

Vollständige CLI-Referenz

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

Argumente:
  prompt              Textbeschreibung der zu generierenden Musik

Optionen:
  -m, --model NAME    HuggingFace-Modell (Standard: facebook/musicgen-small)
  -o, --output FILE   Ausgabe-WAV-Datei (Standard: ./musicgen_output.wav)
  -d, --duration SEC  Dauer in Sekunden (Standard: 8)
  --no-open           Datei nach der Generierung nicht öffnen
  --top-k K           Top-k-Sampling (Standard: 250)
  --temperature T     Sampling-Temperatur (Standard: 1.0)
  --cfg-coef C        Classifier-Free-Guidance-Koeffizient (Standard: 3.0)

Modelle

Modell	Größe	Qualität	Geschwindigkeit (M4 Max)	Anwendungsfall
facebook/musicgen-small	300M / 1,2GB	Gut	1,3x Echtzeit	Standardwahl
facebook/musicgen-medium	1,5B / 3,4GB	Besser	~0,6x Echtzeit	Bessere Qualität
facebook/musicgen-large	3,3B / 5,5GB	Beste (Mono)	~0,4x Echtzeit	Hohe Qualität
facebook/musicgen-stereo-large	3,3B / 6,5GB	Beste (Stereo)	~0,3x Echtzeit	Endgültige Ausgabe

Generierungsparameter

Parameter	Bereich	Effekt
--temperature	0,5–1,5	Höher = kreativer/vielfältiger. Niedriger = vorhersehbarer
--top-k	100–500	Höher = vielfältigere Notenauswahl
--cfg-coef	1,0–7,0	Höher = strengere Prompt-Befolgung. Standard 3,0 ist ausgewogen

Verwendung des Wrapper-Skripts

Der Einfachheit halber verwende generate_bgm.sh:

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

Optionen: -m <Modell>, -d <Sekunden>, -t <Temperatur>, -o <Ausgabe>

Python-API

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

# Modell laden
mg = MusicGen.get_pretrained("facebook/musicgen-small")

# Parameter setzen
mg.set_generation_params(duration=30, temperature=1.0, top_k=250, cfg_coef=3.0)

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

# Speichern
wav = np.array(audio[0])  # [Kanäle, Samples]
sf.write("output.wav", wav.T, mg.sample_rate)

Prompt-Engineering

Siehe prompts.md für eine umfassende Anleitung mit Beispielen.

Kurztipps:

• Beginne mit Genre/Stil: "lo-fi hip hop", "cinematic orchestral", "ambient electronic"
• Füge Instrumente hinzu: "warm piano", "soft synth pads", "acoustic guitar"
• Beschreibe Stimmung/Atmosphäre: "relaxing", "uplifting", "mysterious", "energetic"
• Füge Produktionsmerkmale hinzu: "vinyl crackle", "reverb", "80 BPM", "sidechain compression"
• Schließe mit Zweck ab: "perfect for study", "background for podcast", "game menu music"

⚠️ MusicGen funktioniert am besten mit englischen Prompts und Instrumentalmusik.

Vorgehen (für KI-Agenten)

1. Installation prüfen: Führe musicgen-mlx --help aus. Falls nicht installiert, installiere mit pip install mlx-audiocraft.
2. Anforderungen erfragen: Frage den Benutzer nach Genre, Stimmung und Dauer. Bei vagen Angaben schlage beliebte BGM-Stile vor.
3. Modell auswählen: Standardmäßig facebook/musicgen-small (schnell, 300M). Verwende facebook/musicgen-medium für bessere Qualität oder facebook/musicgen-stereo-large für beste Ergebnisse.
4. Prompt erstellen: Erstelle eine 10–30 Wörter lange englische Beschreibung gemäß der Prompt-Anleitung in prompts.md.
5. Dauer festlegen: 15–30s für Loops, 30–60s für kurzes BGM, 60–120s für längere Stücke.
6. Generieren: Führe musicgen-mlx "<Prompt>" -m <Modell> -d <Sek> -o <Pfad>.wav aus.
7. Berichten: Teile dem Benutzer den Ausgabedateipfad mit. Biete an, mit angepassten Parametern erneut zu generieren, falls nötig.

Fallstricke

• ⚠️ Erster Lauf lädt Modelle herunter – 1,2–6,5 GB von HuggingFace. Den Benutzer warnen.
• ⚠️ Nur Apple Silicon – funktioniert NICHT auf Intel Macs.
• ⚠️ Standard 8s Dauer – immer -d für BGM angeben.
• ⚠️ Nur instrumental – schwach bei Gesang/Text.
• ⚠️ Nicht-kommerzielle Lizenz – CC-BY-NC 4.0. Nicht für kommerzielle Nutzung.
• ⚠️ RAM-intensiv – 8GB-Maschinen sollten nur kleine/mittlere Modelle verwenden.
• ⚠️ Langsam bei großen Modellen – Stereo-groß ist ~0,3x Echtzeit. Eine 60s-Generierung dauert ~3 Minuten.

Überprüfung

# 1. CLI prüfen
musicgen-mlx --help

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

# 3. Ausgabe prüfen
file /tmp/test_bgm.wav
# Erwartet: RIFF (little-endian) data, WAVE audio

# 4. Anhören
open /tmp/test_bgm.wav

Dateien

Datei	Zweck
SKILL.md	Diese Datei – Skill-Definition und Referenz
setup.sh	Ein-Kommando-Installationsskript
generate_bgm.sh	Wrapper für einfache agentenfreundliche Generierung
prompts.md	Prompt-Engineering-Anleitung mit Genre-Vorlagen