Skip to content
Back to search

claude-music

MarketplaceWorks with Claude CodeGitHub

AI music production skill for Claude Code, powered by ACE-Step 1.5. Generate full songs from a prompt, in your terminal or a local web dashboard.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/agricidaniel--claude-music/badge.svg)](/listings/agricidaniel--claude-music)

HTML

<a href="/listings/agricidaniel--claude-music"><img src="/api/listings/agricidaniel--claude-music/badge.svg" alt="findsafeskills safety rating" /></a>

Install

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 15 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "claude-music",
  3. "owner": {
  4. "name": "AgriciDaniel",
  5. "url": "https://github.com/AgriciDaniel"
  6. },
  7. "plugins": [
  8. {
  9. "name": "claude-music",
  10. "description": "AI music production suite using ACE-Step 1.5 — generate, cover, repaint, compose, analyze, export, enhance, LoRA-train. Direct Python API, no REST server required.",
  11. "version": "0.4.0",
  12. "source": "./"
  13. }
  14. ]
  15. }
README.md · README · 289 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="assets/Claude-Music-cover.png" alt="claude-music, AI music production for Claude Code" width="720">
  3. </p>
  4. # claude-music
  5. Make full songs on your own computer by describing them in plain words.
  6. claude-music turns [Claude Code](https://claude.ai/code) into a music studio,
  7. powered by [ACE-Step 1.5](https://github.com/ace-step/ACE-Step-1.5). Type
  8. "make me a chill lo-fi beat" and get a finished track in about 15 seconds.
  9. No cloud, no subscription, no per-song fees. Your GPU does the work.
  10. <p align="center">
  11. <img src="assets/screens/dashboard.png" alt="The claude-music dashboard: describe a song, pick styles, and watch it generate, with a real waveform player and a library of your tracks" width="820">
  12. </p>
  13. ## Hear It
  14. Four unedited songs it made, exactly as they came out. All four are about
  15. the same subject (an SEO tool), with full sung lyrics written by Claude
  16. and vocals in three languages:
  17. | Track | Style and voice |
  18. |-------|-----------------|
  19. | [Crawl Season](examples/crawl-season.mp3) | Hip-hop, English rap: "Ran one little audit, now the crawlers all obsessed" |
  20. | [SEO Caliente](examples/seo-caliente.mp3) | Latin pop / reggaeton, Spanish vocals |
  21. | [Tokyo Page One](examples/tokyo-page-one.mp3) | Japanese lo-fi / city pop, Japanese vocals |
  22. | [First Page Swing](examples/first-page-swing.mp3) | Jazz crooner with a piano trio |
  23. ## Get Started (5 minutes)
  24. One command installs everything:
  25. ```bash
  26. git clone https://github.com/AgriciDaniel/claude-music.git
  27. cd claude-music
  28. bash install.sh
  29. ```
  30. Windows (PowerShell): `powershell -ExecutionPolicy Bypass -File .\install.ps1`
  31. The installer checks your system, sets up ACE-Step and the models (~5GB,
  32. asks first), and links everything to Claude Code. Then open Claude Code and
  33. say:
  34. > "Generate a chill lo-fi beat, 60 seconds"
  35. Or open the dashboard in your browser:
  36. ```
  37. /music web
  38. ```
  39. ## What You Can Do
  40. | Say this... | What happens |
  41. |-------------|--------------|
  42. | "Make me a song about..." | A full song with vocals |
  43. | "Create an instrumental jazz piece" | Instrumental track |
  44. | "Make a rock cover of this song" | Your song, remade in a new style |
  45. | "Fix the chorus, make it more energetic" | Edits just that section |
  46. | "Export for Spotify" | Loudness-ready file for the platform |
  47. | "Surprise me" | Random genre, instant song |
  48. ## The Dashboard
  49. Everything in one page, running privately on your machine:
  50. - Describe a song, pick styles, press Generate, watch the live progress
  51. - A real waveform player: click anywhere to jump, bars move with the beat
  52. - Your library with album art, titles you can rename, and star ratings
  53. - Drag and drop your own songs to check their loudness, fix them for
  54. streaming, or generate similar tracks from them
  55. <p align="center">
  56. <img src="assets/screens/player.png" alt="Player mid-playback: the played part fills in orange, click anywhere to jump" width="700">
  57. </p>
  58. <p align="center">
  59. <img src="assets/screens/audit.png" alt="One click audits a song: loudness, peaks, and format, with plain-language fixes" width="700">
  60. </p>
  61. ## What You Need
  62. - [Claude Code](https://claude.ai/code) (free CLI, desktop app, or VS Code)
  63. - An NVIDIA GPU with 4GB+ VRAM (8GB+ recommended; CPU works but is slow)
  64. - ~10GB of disk space
  65. The installer handles the rest (Python, FFmpeg, uv, ACE-Step).
  66. ## Quality Presets
  67. | Preset | Speed | Best for |
  68. |--------|-------|----------|
  69. | `draft` | ~15s | Quick ideas (4 variants) |
  70. | `standard` | ~15s | Everyday use (2 variants) |
  71. | `high` | ~25s | Better lyrics and structure |
  72. | `max` | ~3-5min | Highest quality possible |
  73. <details>
  74. <summary><b>Changing defaults, file naming, and settings precedence</b></summary>
  75. <p align="center">
  76. <img src="assets/quality-ladder.dark.svg" alt="Four quality presets: draft, standard, high, max, trading off speed for quality" width="720">
  77. </p>
  78. `standard` skips the 1.7B LM thinking pass that plans BPM, key and structure
  79. before diffusion, which is why it can produce thinner melodies than `high`.
  80. Settings resolve in this order: **CLI flag > `config.json` > quality preset.**
  81. To stop passing `--quality high` on every run, set it once in
  82. `skills/claude-music/config.json`:
  83. ```json
  84. {
  85. "defaults": {
  86. "quality": "high",
  87. "format": "flac"
  88. }
  89. }
  90. ```
  91. `quality`, `format`, `language` and the memory settings
  92. (`offload_to_cpu`, `offload_dit_to_cpu`, `use_flash_attention`) are read from
  93. there, as is the top-level `output_dir` (also changeable from the dashboard's
  94. Settings gear).
  95. `model`, `lm_model`, `batch_size` and `thinking` are owned by the quality
  96. preset and are deliberately absent from the shipped config. Adding one pins it
  97. across *every* preset, e.g. a `batch_size` of 2 would silently defeat
  98. `draft`'s 4.
  99. **Output file naming**: files are renamed from raw UUIDs to something
  100. readable:
  101. ```
  102. lo-fi-afro-latin-percussion-nylon_20260812-1548_01_s3128607774.flac
  103. ```
  104. The seed at the end lets you regenerate or vary a track you liked
  105. (`--seed 3128607774`). Renaming never overwrites; collisions get a `-2`
  106. suffix. Set `"naming": "uuid"` to keep the original names.
  107. </details>
  108. ## All Commands
  109. ```
  110. /music generate - Create music from text + lyrics
  111. /music cover - Remake a song in a different style
  112. /music repaint - Edit a section of a song
  113. /music compose - Songwriting help (lyrics, caption, BPM)
  114. /music export - Export for Spotify/YouTube/TikTok/etc
  115. /music analyze - Check BPM, key, loudness
  116. /music enhance - Normalize, denoise, separate stems
  117. /music random - Random generation (surprise me!)
  118. /music library - Browse your generated music
  119. /music lora - Train custom styles
  120. /music setup - Check if everything works
  121. /music web - Local browser dashboard
  122. ```
  123. <details>
  124. <summary><b>How it works, GPU tiers, and architecture</b></summary>
  125. <p align="center">
  126. <img src="assets/hero.dark.svg" alt="From a text prompt to a full 48 kHz stereo waveform, locally on your GPU" width="960">
  127. </p>
  128. 1. You describe what you want (or use `/music generate`)
  129. 2. Claude crafts the right caption, lyrics, and parameters
  130. 3. ACE-Step 1.5 generates the audio locally on your GPU
  131. 4. You listen, iterate, and export
  132. <p align="center">
  133. <img src="assets/pipeline.dark.svg" alt="Four-stage flow: describe, plan, generate, listen, then iterate" width="960">
  134. </p>
  135. | Setup | VRAM | Speed |
  136. |-------|------|-------|
  137. | Turbo (default) | ~8GB | ~15 seconds |
  138. | Turbo + Thinking | ~14GB | ~25 seconds |
  139. | XL (best quality) | ~16GB | ~30 seconds |
  140. <p align="center">
  141. <img src="assets/vram-tiers.dark.svg" alt="VRAM tiers: Turbo needs 8 GB (default), Turbo + thinking 14 GB, XL Turbo 16 GB" width="720">
  142. </p>
  143. The skill talks to ACE-Step's Python API directly (no REST server), routed
  144. through an orchestrator and 11 sub-skills:
  145. <p align="center">
  146. <img src="assets/architecture.dark.svg" alt="Orchestrator at the centre, sub-skills around it, music-composer subagent branching off compose" width="960">
  147. </p>
  148. <p align="center">
  149. <img src="assets/task-icons.dark.svg" alt="Sub-commands of claude-music: generate, cover, repaint, compose, analyze, export, enhance, random, library, lora" width="960">
  150. </p>
  151. See [ARCHITECTURE.md](ARCHITECTURE.md) for the design decisions.
  152. </details>
  153. <details>
  154. <summary><b>Troubleshooting</b></summary>
  155. | Symptom | Fix |
  156. |---------|-----|
  157. | `CUDA out of memory` | Other apps are holding VRAM. Close GPU-heavy programs, or use `draft` quality, shorter durations, and smaller batches. The dashboard warns when free VRAM is under 4 GB and names the apps holding it. |
  158. | No NVIDIA GPU detected | ACE-Step needs CUDA for reasonable speed. CPU-only generation works but is very slow. On AMD/Intel or macOS, check ACE-Step's own docs for ROCm/XPU/MPS scripts. |
  159. | `uv: command not found` | Install uv: `curl -LsSf https://astral.sh/uv/install.sh \| sh`, then re-run `install.sh`. |
  160. | Dashboard says "setup required" | `config.json` still has the `CHANGE_ME` placeholder. Run `bash install.sh`. |
  161. | Dashboard port busy | The server auto-increments 8765-8775. Or pick one: `bash music_web.sh 9000`. |
  162. | First generation is slow | Model checkpoints load into VRAM on first run (~10-30 s extra). Later runs are faster. |
  163. | Generation timed out (15 min) | Usually a first-run model download or a `max`-quality run on a slow GPU. Try again or drop to `high`. |
  164. | FLAC will not play in the dashboard | Chrome and Firefox play FLAC natively; some Safari versions do not. Set `"format": "mp3"` in `config.json` defaults, or use the Download button. |
  165. | Uploaded file rejected | The dashboard accepts flac, wav, mp3, opus, aac, m4a and ogg up to 200 MB, and verifies the file decodes. Convert exotic formats first: `ffmpeg -i input.xyz output.flac`. |
  166. </details>
  167. ## Uninstall
  168. ```bash
  169. cd claude-music
  170. bash uninstall.sh
  171. ```
  172. Removes skill links only. Your generated music and ACE-Step are untouched.
  173. ## For Contributors
  174. ```bash
  175. pip install -e ".[dev]"
  176. pytest tests/ # 54 contract tests, <1s, no GPU required
  177. ruff check skills/ tests/
  178. ```
  179. See [CONTRIBUTING.md](CONTRIBUTING.md) for the workflow and
  180. [SECURITY.md](SECURITY.md) for the threat model.
  181. <details>
  182. <summary><b>Release notes (v0.2 to v0.4)</b></summary>
  183. ### v0.4
  184. The dashboard release. Full notes on the
  185. [releases page](https://github.com/AgriciDaniel/claude-music/releases/tag/v0.4.0).
  186. - Web dashboard (`/music web`): chat-style composer with a 28-genre style
  187. dropdown, live progress, a real-waveform player, generative album art,
  188. renameable titles, ratings, drag-and-drop uploads with audit / optimize /
  189. similar, quick actions, an output-folder setting, and confetti
  190. - Reliability: VRAM fail-fast, automatic retries on out-of-memory and
  191. launcher hiccups, noise-tolerant result parsing, dash-proof prompts,
  192. sticky error notices with plain-language fixes
  193. - Engine: settings precedence CLI > config > preset, readable output
  194. filenames, `--progress` events for wrappers
  195. - `config.json` is per-machine and untracked; installers seed it from
  196. `config.example.json`
  197. - Tests: 41 to 54
  198. ### v0.3
  199. - Config defaults honoured with explicit precedence
  200. - Descriptive output naming (`slug_date_index_seed.ext`)
  201. - First version of the web dashboard
  202. ### v0.2
  203. - Plugin manifest for the Agent Skills open standard
  204. - GPU-free test suite and CI (ruff + shellcheck + pytest)
  205. - Windows installer, ARCHITECTURE.md, community files
  206. - `--help` works even before ACE-Step is configured
  207. </details>
  208. ## License
  209. MIT, see [LICENSE](LICENSE).
  210. This project wraps and invokes ACE-Step 1.5 (Apache 2.0) without
  211. redistributing it; the installer sets it up separately. Generated audio
  212. inherits no licensing obligations from this skill; consult ACE-Step's
  213. license for model output licensing.
  214. ## Credits
  215. Built on [ACE-Step 1.5](https://github.com/ace-step/ACE-Step-1.5) by the
  216. ACE Studio team. Skill by [Daniel Agrici](https://github.com/AgriciDaniel).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.