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.
1---2name: claude-music3description: 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.4---56# claude-music — AI Music Production for Claude Code78## Quick Reference910| Command | What it does |11|---------|-------------|12| `/music` | Interactive mode — describe what you want |13| `/music generate` | Text/lyrics to full song (text2music) |14| `/music cover` | Style transfer from reference audio |15| `/music repaint` | Edit a specific section of a song |16| `/music extract` | Separate tracks/stems (base model only) |17| `/music lego` | Add instrument layer (base model only) |18| `/music complete` | Continue/extend audio (base model only) |19| `/music compose` | Songwriting: craft caption + lyrics + params |20| `/music analyze` | BPM, key, loudness, duration analysis |21| `/music export` | Platform-optimized export (Spotify, YouTube, etc.) |22| `/music enhance` | Post-processing: normalize, denoise, stem separate |23| `/music random` | Quick random generation with smart defaults |24| `/music library` | Browse and manage generated music |25| `/music web` | Local browser dashboard: generate, play, rate |26| `/music lora` | LoRA/LoKr fine-tuning management |27| `/music setup` | Verify installation and dependencies |2829## Orchestration Logic3031### Command Routing3233When the user provides a specific command, load the matching sub-skill:3435- `/music generate` or intent is create song/make music/text-to-music/lyrics-to-music → Read `skills/claude-music-generate/SKILL.md`36- `/music cover` or intent is cover/style transfer/remake/version of → Read `skills/claude-music-cover/SKILL.md`37- `/music repaint` or intent is edit section/fix chorus/change part/modify section → Read `skills/claude-music-repaint/SKILL.md`38- `/music compose` or intent is write lyrics/craft caption/plan song/songwriting → Read `skills/claude-music-compose/SKILL.md`39- `/music analyze` or intent is BPM/key detection/loudness/audio info → Read `skills/claude-music-analyze/SKILL.md`40- `/music export` or intent is export for Spotify/YouTube/platform/format conversion → Read `skills/claude-music-export/SKILL.md`41- `/music enhance` or intent is normalize/denoise/stem separate/master → Read `skills/claude-music-enhance/SKILL.md`42- `/music random` or intent is quick generation/surprise me/random song → Read `skills/claude-music-random/SKILL.md`43- `/music library` or intent is list songs/browse output/manage music → Read `skills/claude-music-library/SKILL.md`44- `/music web` or intent is dashboard/browser app/web UI/visual player → Read `skills/claude-music-web/SKILL.md`45- `/music lora` or intent is train/fine-tune/LoRA/custom style → Read `skills/claude-music-lora/SKILL.md`46- `/music setup` → Run `bash ~/.claude/skills/claude-music/scripts/setup.sh`4748### Interactive Mode4950When user says `/music` without arguments or describes a task in natural language:511. Run `bash ~/.claude/skills/claude-music/scripts/check_deps.sh` to verify tools522. Run `bash ~/.claude/skills/claude-music/scripts/detect_gpu.sh` for GPU info533. Identify intent from the user's description544. Route to the appropriate sub-skill555. If ambiguous, ask the user to clarify5657### Multi-Step Pipelines5859For complex requests spanning multiple sub-skills (e.g., "compose lyrics, generate a song, then export for Spotify"):601. Compose lyrics/caption with `/music compose`612. Generate with `/music generate` using composed output623. Export with `/music export`634. Clean up temp files6465### Generate-Listen-Iterate Loop6667After any generation:681. Present output file paths and metadata (seed, duration, format)692. Suggest playback: `ffplay -nodisp -autoexit "<path>"`703. Ask if user wants to:71 - **Re-generate** with different seed (same params)72 - **Refine** params (adjust caption, BPM, quality)73 - **Repaint** a specific section74 - **Cover** to change style while keeping structure75 - **Export** for a platform7677## Safety Rules — MANDATORY78791. **Run preflight before writes**: `bash ~/.claude/skills/claude-music/scripts/preflight.sh "$INPUT" "$OUTPUT"`802. **Never overwrite source files** — all operations produce new files813. **Check VRAM before GPU operations**: `bash ~/.claude/skills/claude-music/scripts/detect_gpu.sh`824. **Confirm before**: batch >4 generations, operations with --quality max (3-5 min)835. **Auto-execute without confirmation**: single generation (draft/standard), analysis, format conversion, setup846. **Temp files**: `/tmp/claude-music/` with cleanup trap857. **Output directory**: `~/Music/claude-music-output/` (auto-created)8687## ACE-Step Configuration8889- **Installation**: Set `ace_step_dir` in `config.json` (default: see config.json)90- **Invocation**: `bash ~/.claude/skills/claude-music/scripts/music_engine.sh <command> [args]`91- **Config**: `~/.claude/skills/claude-music/config.json`92- **Output**: `~/Music/claude-music-output/`9394## Quality Presets9596| Preset | Model | LM | Steps | Speed | Use for |97|--------|-------|----|-------|-------|---------|98| `draft` | turbo | none | 8 | ~15s | Quick exploration, batch 4 variants |99| `standard` | turbo | none | 8 | ~15s | Default, batch 2 variants |100| `high` | turbo | 1.7B LM | 8 | ~25s | Better lyrics/structure, thinking mode |101| `max` | base | 1.7B LM | 65 | ~3-5min | Highest quality, single output |102103## VRAM Management (RTX 5070 Ti — 16GB)104105| Configuration | VRAM | Offload | Notes |106|---------------|------|---------|-------|107| Turbo (no LM) | ~8GB | CPU offload | Default, fast generation |108| Turbo + 0.6B LM | ~10GB | CPU + DiT offload | Thinking mode, lightweight |109| Turbo + 1.7B LM | ~14GB | CPU + DiT offload | Full thinking, tight on VRAM |110| XL Turbo | ~14-16GB | Full offload | Maximum quality DiT, no LM room |111112**Rule**: Never run two heavy models simultaneously. The music_engine.py handles VRAM automatically.113114## Script Invocation115116All ACE-Step operations go through the bash wrapper:117```bash118bash ~/.claude/skills/claude-music/scripts/music_engine.sh <subcommand> [args]119```120121The wrapper handles: path setup, environment variables, VRAM pre-check, `uv run` invocation.122123**Output is always JSON to stdout.** Parse with `jq` for specific fields.124125## Reference Files (Load On-Demand)126127| Reference | When to load |128|-----------|-------------|129| `references/prompt-guide.md` | When crafting captions or lyrics |130| `references/parameters.md` | When user asks about specific params or tuning |131| `references/genre-recipes.md` | When targeting a specific genre |132| `references/music-theory.md` | When discussing keys, scales, BPM, song structure |133| `references/post-processing.md` | When exporting, mastering, or enhancing |134| `references/song-structures.md` | When planning song layout |135| `references/lora-training.md` | When training custom LoRA models |136137## Sub-Skills138139| Skill | Type | Description |140|-------|------|-------------|141| `claude-music-generate` | Generation | Core text2music via ACE-Step Python API |142| `claude-music-cover` | Generation | Style transfer from reference audio |143| `claude-music-repaint` | Editing | Selective section regeneration |144| `claude-music-compose` | Reference | Songwriting guide (caption, lyrics, params) |145| `claude-music-analyze` | Analysis | BPM, key, loudness, metadata via ffprobe/librosa |146| `claude-music-export` | Processing | Platform-specific audio export via FFmpeg |147| `claude-music-enhance` | Processing | Loudness normalization, denoise, stems (reuses video skills) |148| `claude-music-random` | Generation | Quick random generation with genre presets |149| `claude-music-library` | Management | Browse/search generated music output |150| `claude-music-web` | UI | Local browser dashboard (generate, play, rate) |151| `claude-music-lora` | Training | LoRA/LoKr fine-tuning wrapper |152153## Scripts154155| Script | Purpose |156|--------|---------|157| `scripts/music_engine.py` | Core ACE-Step Python API wrapper (all 6 task types) |158| `scripts/music_engine.sh` | Bash wrapper (env, VRAM, `uv run`, show-once star nudge) |159| `scripts/music_export.sh` | FFmpeg platform export commands |160| `scripts/rank.py` | Batch-rank outputs vs caption (stub — Theme 3 of research plan) |161| `scripts/detect_gpu.sh` | GPU detection + tier recommendation → JSON |162| `scripts/preflight.sh` | Safety checks for audio files → JSON |163| `scripts/check_deps.sh` | Dependency verification → JSON |164| `scripts/setup.sh` | Installation verification (invoked by `/music setup`) |165166Audio analysis (BPM, key, loudness) is handled by `claude-music-analyze` via `ffprobe` + FFmpeg's `loudnorm` filter — no separate Python script; see that sub-skill.
Agrici Daniel