claude-music

Make full songs on your own computer by describing them in plain words.

claude-music turns Claude Code into a music studio,
powered by ACE-Step 1.5. Type
"make me a chill lo-fi beat" and get a finished track in about 15 seconds.
No cloud, no subscription, no per-song fees. Your GPU does the work.

Hear It

Four unedited songs it made, exactly as they came out. All four are about
the same subject (an SEO tool), with full sung lyrics written by Claude
and vocals in three languages:

Get Started (5 minutes)

One command installs everything:

git clone https://github.com/AgriciDaniel/claude-music.git
cd claude-music
bash install.sh

Windows (PowerShell): powershell -ExecutionPolicy Bypass -File .\install.ps1

The installer checks your system, sets up ACE-Step and the models (~5GB,
asks first), and links everything to Claude Code. Then open Claude Code and
say:

"Generate a chill lo-fi beat, 60 seconds"

Or open the dashboard in your browser:

/music web

What You Can Do

The Dashboard

Everything in one page, running privately on your machine:

• Describe a song, pick styles, press Generate, watch the live progress
• A real waveform player: click anywhere to jump, bars move with the beat
• Your library with album art, titles you can rename, and star ratings
• Drag and drop your own songs to check their loudness, fix them for
  streaming, or generate similar tracks from them

What You Need

• Claude Code (free CLI, desktop app, or VS Code)
• An NVIDIA GPU with 4GB+ VRAM (8GB+ recommended; CPU works but is slow)
• ~10GB of disk space

The installer handles the rest (Python, FFmpeg, uv, ACE-Step).

Quality Presets

standard skips the 1.7B LM thinking pass that plans BPM, key and structure
before diffusion, which is why it can produce thinner melodies than high.

Settings resolve in this order: CLI flag > config.json > quality preset.
To stop passing --quality high on every run, set it once in
skills/claude-music/config.json:

{
  "defaults": {
    "quality": "high",
    "format": "flac"
  }
}

quality, format, language and the memory settings
(offload_to_cpu, offload_dit_to_cpu, use_flash_attention) are read from
there, as is the top-level output_dir (also changeable from the dashboard's
Settings gear).

model, lm_model, batch_size and thinking are owned by the quality
preset and are deliberately absent from the shipped config. Adding one pins it
across every preset, e.g. a batch_size of 2 would silently defeat
draft's 4.

Output file naming: files are renamed from raw UUIDs to something
readable:

lo-fi-afro-latin-percussion-nylon_20260812-1548_01_s3128607774.flac

The seed at the end lets you regenerate or vary a track you liked
(--seed 3128607774). Renaming never overwrites; collisions get a -2
suffix. Set "naming": "uuid" to keep the original names.

All Commands

/music generate   - Create music from text + lyrics
/music cover      - Remake a song in a different style
/music repaint    - Edit a section of a song
/music compose    - Songwriting help (lyrics, caption, BPM)
/music export     - Export for Spotify/YouTube/TikTok/etc
/music analyze    - Check BPM, key, loudness
/music enhance    - Normalize, denoise, separate stems
/music random     - Random generation (surprise me!)
/music library    - Browse your generated music
/music lora       - Train custom styles
/music setup      - Check if everything works
/music web        - Local browser dashboard

1. You describe what you want (or use /music generate)
2. Claude crafts the right caption, lyrics, and parameters
3. ACE-Step 1.5 generates the audio locally on your GPU
4. You listen, iterate, and export

The skill talks to ACE-Step's Python API directly (no REST server), routed
through an orchestrator and 11 sub-skills:

See ARCHITECTURE.md for the design decisions.

Uninstall

cd claude-music
bash uninstall.sh

Removes skill links only. Your generated music and ACE-Step are untouched.

For Contributors

pip install -e ".[dev]"
pytest tests/            # 54 contract tests, <1s, no GPU required
ruff check skills/ tests/

See CONTRIBUTING.md for the workflow and
SECURITY.md for the threat model.

v0.4

The dashboard release. Full notes on the
releases page.

• Web dashboard (/music web): chat-style composer with a 28-genre style
  dropdown, live progress, a real-waveform player, generative album art,
  renameable titles, ratings, drag-and-drop uploads with audit / optimize /
  similar, quick actions, an output-folder setting, and confetti
• Reliability: VRAM fail-fast, automatic retries on out-of-memory and
  launcher hiccups, noise-tolerant result parsing, dash-proof prompts,
  sticky error notices with plain-language fixes
• Engine: settings precedence CLI > config > preset, readable output
  filenames, --progress events for wrappers
• config.json is per-machine and untracked; installers seed it from
  config.example.json
• Tests: 41 to 54

v0.3

• Config defaults honoured with explicit precedence
• Descriptive output naming (slug_date_index_seed.ext)
• First version of the web dashboard

v0.2

• Plugin manifest for the Agent Skills open standard
• GPU-free test suite and CI (ruff + shellcheck + pytest)
• Windows installer, ARCHITECTURE.md, community files
• --help works even before ACE-Step is configured

License

MIT, see LICENSE. Generated audio inherits no licensing
obligations from this skill; consult ACE-Step's license.

Credits

Built on ACE-Step 1.5 by the
ACE Studio team. Skill by Daniel Agrici.