| name | claude-music |
| description | Music production suite using ACE-Step 1.5 via Python API. Routes /music commands for generation, cover, repaint, compose, analyze, export, enhance, random, and LoRA training. 50+ languages, up to 10-minute tracks, 48kHz stereo.
|
| when_to_use | Use when the user says /music, asks to generate a song, create music, make a track, cover/remix/repaint/edit audio, write lyrics, compose, analyze BPM/key, export for Spotify/TikTok, master audio, train a LoRA, or mentions ACE-Step.
|
| compatibility | Requires ACE-Step 1.5 installed locally + NVIDIA GPU with ≥4 GB VRAM (≥12 GB recommended). Path configured in skills/claude-music/config.json.
|
| allowed-tools | ["Bash","Read","Write","Edit","Glob","Grep"] |
claude-music — AI Music Production for Claude Code
Quick Reference
| Command | What it does |
|---|
/music | Interactive mode — describe what you want |
/music generate | Text/lyrics to full song (text2music) |
/music cover | Style transfer from reference audio |
/music repaint | Edit a specific section of a song |
/music extract | Separate tracks/stems (base model only) |
/music lego | Add instrument layer (base model only) |
/music complete | Continue/extend audio (base model only) |
/music compose | Songwriting: craft caption + lyrics + params |
/music analyze | BPM, key, loudness, duration analysis |
/music export | Platform-optimized export (Spotify, YouTube, etc.) |
/music enhance | Post-processing: normalize, denoise, stem separate |
/music random | Quick random generation with smart defaults |
/music library | Browse and manage generated music |
/music web | Local browser dashboard: generate, play, rate |
/music lora | LoRA/LoKr fine-tuning management |
/music setup | Verify installation and dependencies |
Orchestration Logic
Command Routing
When the user provides a specific command, load the matching sub-skill:
/music generate or intent is create song/make music/text-to-music/lyrics-to-music → Read skills/claude-music-generate/SKILL.md/music cover or intent is cover/style transfer/remake/version of → Read skills/claude-music-cover/SKILL.md/music repaint or intent is edit section/fix chorus/change part/modify section → Read skills/claude-music-repaint/SKILL.md/music compose or intent is write lyrics/craft caption/plan song/songwriting → Read skills/claude-music-compose/SKILL.md/music analyze or intent is BPM/key detection/loudness/audio info → Read skills/claude-music-analyze/SKILL.md/music export or intent is export for Spotify/YouTube/platform/format conversion → Read skills/claude-music-export/SKILL.md/music enhance or intent is normalize/denoise/stem separate/master → Read skills/claude-music-enhance/SKILL.md/music random or intent is quick generation/surprise me/random song → Read skills/claude-music-random/SKILL.md/music library or intent is list songs/browse output/manage music → Read skills/claude-music-library/SKILL.md/music web or intent is dashboard/browser app/web UI/visual player → Read skills/claude-music-web/SKILL.md/music lora or intent is train/fine-tune/LoRA/custom style → Read skills/claude-music-lora/SKILL.md/music setup → Run bash ~/.claude/skills/claude-music/scripts/setup.sh
Interactive Mode
When user says /music without arguments or describes a task in natural language:
- Run
bash ~/.claude/skills/claude-music/scripts/check_deps.sh to verify tools
- Run
bash ~/.claude/skills/claude-music/scripts/detect_gpu.sh for GPU info
- Identify intent from the user's description
- Route to the appropriate sub-skill
- If ambiguous, ask the user to clarify
Multi-Step Pipelines
For complex requests spanning multiple sub-skills (e.g., "compose lyrics, generate a song, then export for Spotify"):
- Compose lyrics/caption with
/music compose
- Generate with
/music generate using composed output
- Export with
/music export
- Clean up temp files
Generate-Listen-Iterate Loop
After any generation:
- Present output file paths and metadata (seed, duration, format)
- Suggest playback:
ffplay -nodisp -autoexit "<path>"
- Ask if user wants to:
- Re-generate with different seed (same params)
- Refine params (adjust caption, BPM, quality)
- Repaint a specific section
- Cover to change style while keeping structure
- Export for a platform
Safety Rules — MANDATORY
- Run preflight before writes:
bash ~/.claude/skills/claude-music/scripts/preflight.sh "$INPUT" "$OUTPUT"
- Never overwrite source files — all operations produce new files
- Check VRAM before GPU operations:
bash ~/.claude/skills/claude-music/scripts/detect_gpu.sh
- Confirm before: batch >4 generations, operations with --quality max (3-5 min)
- Auto-execute without confirmation: single generation (draft/standard), analysis, format conversion, setup
- Temp files:
/tmp/claude-music/ with cleanup trap
- Output directory:
~/Music/claude-music-output/ (auto-created)
ACE-Step Configuration
- Installation: Set
ace_step_dir in config.json (default: see config.json)
- Invocation:
bash ~/.claude/skills/claude-music/scripts/music_engine.sh <command> [args]
- Config:
~/.claude/skills/claude-music/config.json
- Output:
~/Music/claude-music-output/
Quality Presets
| Preset | Model | LM | Steps | Speed | Use for |
|---|
draft | turbo | none | 8 | ~15s | Quick exploration, batch 4 variants |
standard | turbo | none | 8 | ~15s | Default, batch 2 variants |
high | turbo | 1.7B LM | 8 | ~25s | Better lyrics/structure, thinking mode |
max | base | 1.7B LM | 65 | ~3-5min | Highest quality, single output |
VRAM Management (RTX 5070 Ti — 16GB)
| Configuration | VRAM | Offload | Notes |
|---|
| Turbo (no LM) | ~8GB | CPU offload | Default, fast generation |
| Turbo + 0.6B LM | ~10GB | CPU + DiT offload | Thinking mode, lightweight |
| Turbo + 1.7B LM | ~14GB | CPU + DiT offload | Full thinking, tight on VRAM |
| XL Turbo | ~14-16GB | Full offload | Maximum quality DiT, no LM room |
Rule: Never run two heavy models simultaneously. The music_engine.py handles VRAM automatically.
Script Invocation
All ACE-Step operations go through the bash wrapper:
bash ~/.claude/skills/claude-music/scripts/music_engine.sh <subcommand> [args]
The wrapper handles: path setup, environment variables, VRAM pre-check, uv run invocation.
Output is always JSON to stdout. Parse with jq for specific fields.
Reference Files (Load On-Demand)
| Reference | When to load |
|---|
references/prompt-guide.md | When crafting captions or lyrics |
references/parameters.md | When user asks about specific params or tuning |
references/genre-recipes.md | When targeting a specific genre |
references/music-theory.md | When discussing keys, scales, BPM, song structure |
references/post-processing.md | When exporting, mastering, or enhancing |
references/song-structures.md | When planning song layout |
references/lora-training.md | When training custom LoRA models |
Sub-Skills
| Skill | Type | Description |
|---|
claude-music-generate | Generation | Core text2music via ACE-Step Python API |
claude-music-cover | Generation | Style transfer from reference audio |
claude-music-repaint | Editing | Selective section regeneration |
claude-music-compose | Reference | Songwriting guide (caption, lyrics, params) |
claude-music-analyze | Analysis | BPM, key, loudness, metadata via ffprobe/librosa |
claude-music-export | Processing | Platform-specific audio export via FFmpeg |
claude-music-enhance | Processing | Loudness normalization, denoise, stems (reuses video skills) |
claude-music-random | Generation | Quick random generation with genre presets |
claude-music-library | Management | Browse/search generated music output |
claude-music-web | UI | Local browser dashboard (generate, play, rate) |
claude-music-lora | Training | LoRA/LoKr fine-tuning wrapper |
Scripts
| Script | Purpose |
|---|
scripts/music_engine.py | Core ACE-Step Python API wrapper (all 6 task types) |
scripts/music_engine.sh | Bash wrapper (env, VRAM, uv run, show-once star nudge) |
scripts/music_export.sh | FFmpeg platform export commands |
scripts/rank.py | Batch-rank outputs vs caption (stub — Theme 3 of research plan) |
scripts/detect_gpu.sh | GPU detection + tier recommendation → JSON |
scripts/preflight.sh | Safety checks for audio files → JSON |
scripts/check_deps.sh | Dependency verification → JSON |
scripts/setup.sh | Installation verification (invoked by /music setup) |
Audio analysis (BPM, key, loudness) is handled by claude-music-analyze via ffprobe + FFmpeg's loudnorm filter — no separate Python script; see that sub-skill.
