Communitygithub.com

puntorigen/skills

Lokale Agenten-Fähigkeiten für Cursor & andere KI-Coding-Agenten – 100% auf Ihrem Rechner, keine Cloud, keine API-Schlüssel. Optimiert für Apple Silicon (MLX/Metal): lokale Bildgenerierung, Sprachklon, Hintergrundmusik, Talking-Head-Video, Video→3D-Splat & druckbares STL, Web-Action-Aufzeichnung und Word-.docx-Bearbeitung.

Was ist skills?

Diese Skill-Sammlung bietet eine Reihe von rein lokalen KI-Fähigkeiten für Coding-Agenten wie Cursor & Codex, die vollständig auf Ihrem Rechner laufen – ohne Cloud-Abhängigkeit oder API-Keys. Der bereitgestellte Skill „Background Music“ ermöglicht die Generierung von lizenzfreier, instrumentaler Hintergrundmusik aus einer Textbeschreibung, basierend auf dem ACE-Step 1.5 Modell unter MLX/Metal. Der Workflow umfasst die Abstimmung des Briefings mit dem Benutzer (Genre, Stimmung, BPM, Dauer), die Generierung mehrerer Kandidaten, die Auswahl und optional das automatische Mischen mit einer Sprachaufnahme mittels Sidechain-Kompression. Die gesamte Einrichtung und Ausführung erfolgt in einem isolierten Umfeld (`~/.bg-music/`) und erfordert nur einmalig Internet für den Modell-Download. Die Skill-Sammlung ist besonders nützlich für Entwickler, die schnell professionelle Audio-Assets für Demos, Reels oder Präsentationen benötigen, ohne auf Cloud-Dienste angewiesen zu sein.

Funktioniert mit✓Claude Code~Codex CLI✓Cursor
npx skills add puntorigen/skills

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Hintergrundmusik

Generieren Sie originale, lizenzfreie Instrumentalmusik für Reels und Demovideos aus einer Textbeschreibung – komplett offline. Ein Wrapper treibt ACE-Step 1.5 (das Musikmodell) an; Sie (das Modell) formen die Beschreibung in einen guten Prompt, generieren ein paar Kandidaten, lassen den Benutzer wählen und mischen optional den Gewinner unter eine Erzählung.

Passt zusammen mit dem voice-clone-narration-Skill: Erzeugen Sie den Voiceover dort, die Musik hier, dann duckt mix_voiceover.sh die Musik unter die Erzählung für eine fertige Reel-Audiospur.

flowchart LR
  Brief["Brief: Genre, Stimmung, BPM, Dauer"] --> Gen["generate_music.py<br/>ACE-Step 1.5 (MLX), instrumental"]
  Gen --> Mp3["Kandidaten-MP3s"]
  Nar["narration.mp3 (optional)"] -.-> Mix["mix_voiceover.sh<br/>ffmpeg Sidechain-Ducking"]
  Mp3 -.-> Mix
  Mix -.-> Reel["reel-audio.mp3"]

Alles befindet sich außerhalb des Repos unter ~/.bg-music/ (der ACE-Step-Checkout, Modellgewichte und generierte Audiodateien).

Voraussetzungen

  • uv (Paketmanager) und git – das Modell ist eine uv sync-App, keine reine pip-Installation. Setup installiert es in eine isolierte Umgebung.
  • ffmpeg im PATH (MP3-Kodierung + Mischen). Fragen Sie den Benutzer und lassen Sie ihn brew install ffmpeg ausführen, falls fehlend.
  • ~10 GB freier Speicher für den Code + die Modellgewichte (einmalig von Hugging Face heruntergeladen, anonym – kein Token). Planen Sie mehr ein, wenn Sie größere Modellvarianten verwenden.
  • Apple Silicon Mac für den schnellen nativen Pfad (MLX). Auf CUDA/CPU fällt es auf PyTorch zurück (langsamer auf CPU). 16 GB Unified Memory sind ausreichend für die Standard- 2B-turbo + 0.6B-LM-Stufe.
  • Internet nur beim ersten Start (zum Abrufen von Code + Gewichten). Die Generierung ist offline.

Setup

Lösen Sie das Skill-Verzeichnis auf und führen Sie das Setup einmal aus (klont ACE-Step 1.5 und synchronisiert seine Umgebung – der erste Lauf lädt Abhängigkeiten herunter und kann mehrere Minuten dauern):

SKILL_DIR="<der Ordner, in dem diese SKILL.md liegt>"   # z.B. .cursor/skills/bg-music
bash "$SKILL_DIR/scripts/setup_env.sh"

Setzen Sie dann die von der Generierung verwendeten Handles (Setup gibt diese auch aus):

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

Arbeitsablauf

Kopieren Sie diese Checkliste und verfolgen Sie den Fortschritt:

- [ ] 1. Bestätigen Sie das Briefing: Genre, Stimmung, Tempo (BPM), Dauer, Schlüsselinstrumente
- [ ] 2. Setup: Führen Sie setup_env.sh aus (nur beim ersten Mal)
- [ ] 3. Schreiben Sie einen konkreten Prompt; generieren Sie 2 Kandidaten
- [ ] 4. Spielen/verlinken Sie die Kandidaten; lassen Sie den Benutzer wählen (ggf. neu generieren)
- [ ] 5. (optional) Mischen Sie den Gewinner unter eine Erzählungs-MP3 mit Ducking
- [ ] 6. Liefern Sie die MP3(s) aus

Schritt 1: Das Briefing festlegen

Die Musikqualität hängt von einem konkreten Prompt ab. Fragen Sie diese vom Benutzer ab (oder leiten Sie sie ab und nennen Sie Ihre Wahl):

  • Genre/Stil: Lo-Fi Hip Hop, cineastisches Orchester, Corporate Ambient, Synthwave, Akustik-Folk, fröhlicher Pop...
  • Stimmung: ruhig, erhebend, angespannt, verträumt, energiegeladen, melancholisch.
  • Tempo: langsam / mittel / schnell, oder ein expliziter BPM (z.B. 90).
  • Dauer: Sekunden (10-600; Reels sind normalerweise 30-120).
  • Schlüsselinstrumente (optional): Rhodes-Piano, warme Pads, weiche Drums, Nylon-Gitarre.

Schritt 3: Generieren

"$PY" "$SKILL_DIR/scripts/generate_music.py" \
  --prompt "warmer Lo-Fi Hip Hop, sanftes Rhodes-Piano, weiches Vinyl-Knistern, lässige Drums, loopbar, instrumental" \
  --bpm 80 --duration 60 --count 2 \
  --out "$BG_HOME/out/lofi.mp3"
  • Tracks sind standardmäßig instrumental (kein Gesang).
  • --count 2 erzeugt zwei Variationen zur Auswahl (lofi-1.mp3, lofi-2.mp3).
  • Schreibt MP3s und gibt deren Pfade + Dauern aus. Der erste Lauf lädt Modellgewichte herunter; nachfolgende Läufe sind viel schneller.

Gute Prompts sind spezifisch und kommagetrennt. Fügen Sie Genre + Stimmung + 2-3 Instrumente + ein Tempowort + „instrumental“/„loopbar“ hinzu. Beispiele:

  • "cineastisch inspirierendes Orchester, zarte Streicher, Klavier, subtile Percussion, die zu einer warmen Schwellung ansteigt, instrumental"
  • "sauberer Corporate Ambient, sanfte Synth-Pads, leichte Pizzicati, optimistisch, minimalistisch, instrumental"
  • "treibender Synthwave, analoger Bass, Retro-Arpeggien, kraftvolle Drums, Night-Drive-Energie, instrumental"

Schritt 5: Unter eine Erzählung mischen (optional)

Falls der Benutzer auch einen Voiceover hat (z.B. vom voice-clone-narration-Skill), ducken Sie die Musik automatisch darunter:

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

Die Musik senkt sich automatisch, wenn die Stimme spricht (Sidechain-Kompression), und kommt in den Pausen wieder hoch. Sie wird geloopt, um die Erzählung abzudecken, und ein-/ausgeblendet. Feinabstimmung mit --music-gain (Bettpegel, Standard -8 dB), --duck (Ducking-Stärke, Standard 8) und --fade.

Schritt 6: Ausliefern

Betten Sie die ausgewählte MP3 ein oder verlinken Sie sie. Generierte Dateien bleiben unter ~/.bg-music/out/.

Wichtige Optionen (generate_music.py)

OptionStandardZweck
--prompt(erforderlich)Musikbeschreibung: Genre, Stimmung, Instrumente, Atmosphäre.
--duration60Länge in Sekunden (10-600).
--bpmautoTempo in BPM (30-300); weglassen, um das Modell wählen zu lassen.
--count2Wie viele Variationen generiert werden sollen.
--outout/music-<ts>.mp3Ausgabepfad (oder Präfix bei --count > 1).
--seedzufälligFestlegen für Reproduzierbarkeit.
--keyscaleautoTonart, z.B. "a-moll".
--vocalsaus (instrumental)Gesang zulassen (selten für Hintergrundmusik gewünscht).
--steps8Diffusionsschritte (Turbo-Standard; mehr = langsamer, geringfügig besser).
--mp3-quality2ffmpeg libmp3lame -q:a (0=beste..9=kleinste).
--keep-wavausDie Zwischen-WAV behalten.

Wichtige Optionen (mix_voiceover.sh)

OptionStandardZweck
--voice(erforderlich)Erzählungs-MP3/WAV (bleibt auf vollem Pegel).
--music(erforderlich)Hintergrundmusik-MP3/WAV (wird geduckt + geloopt, um die Stimme abzudecken).
--out(erforderlich)Ausgabe der gemischten MP3.
--music-gain-8Basis-Musikpegel in dB (niedriger = leiseres Bett).
--duck8Ducking-Stärke (Kompressorverhältnis); höher = Musik sinkt stärker unter Sprache.
--fade2Musik-Ein-/Ausblendung in Sekunden.
--mp3-quality2ffmpeg libmp3lame -q:a.

Sicherheit

  • KI-generierte Musik offenlegen, wo die Plattform oder der Kontext es erfordert.
  • Kommerzielle Nutzung: ACE-Step 1.5 ist MIT-lizenziert und auf lizenzierten / lizenzfreien / synthetischen Daten trainiert, sodass generierte Titel weitgehend sicher verwendet werden können. Dennoch, gemäß dem eigenen Haftungsausschluss des Modells, vermeiden Sie Prompts, die die Identität eines bestimmten Künstlers oder Titels kopieren, und überprüfen Sie die Originalität vor der kommerziellen Veröffentlichung.
  • Laden Sie niemals Briefings, Prompts oder generierte Audiodateien in einen externen Dienst hoch. Alles bleibt lokal unter ~/.bg-music/.

Anti-Patterns

  • Vage Ein-Wort-Prompts („Musik“, „etwas Cooles“) – Sie erhalten generische Ausgaben. Geben Sie Genre + Stimmung + Instrumente + Tempo an.
  • Nach Gesang fragen, wenn Sie nur ein Bett benötigen – halten Sie es instrumental (Standard), damit es sauber unter einer Erzählung liegt.
  • Einen Take generieren und ausliefern – generieren Sie --count 2 und lassen Sie den Benutzer wählen.
  • Musik von Hand unter einen Voiceover legen – verwenden Sie mix_voiceover.sh, damit die Musik automatisch unter Sprache duckt.
  • Nach „einem Lied, das genau wie <Künstler/Titel> klingt“ fragen – Risiko für Originalität und Lizenzierung.
  • Irgendetwas aus ~/.bg-music/ in ein Repo committen.

Ressourcen

  • Modell-Zoo (warum 2B-turbo auf 16 GB), das vollständige Parameter-Spickzettel, Prompt-Muster nach Stimmung, Lizenzierungsgrundlage und Fehlerbehebung: REFERENCE.md
  • Die Erzählung generieren, um sie unter die Musik zu mischen: der voice-clone-narration-Skill.
  • Das endgültige Audio in einem Video überprüfen: der review-mp4-Skill.

Verwandte Skills