Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Browser & automation

claude-music-generate

Generates music from text descriptions and lyrics using ACE-Step 1.5's Python API. Creates full songs with vocals, instrumentals, or both. Supports 50+ languages, 10-600 second duration, quality presets (draft/standard/high/max), and batch generation.

AgriciDaniel · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add AgriciDaniel/claude-music --skill claude-music-generate

About this skill


name: claude-music-generate description: > Generates music from text descriptions and lyrics using ACE-Step 1.5's Python API. Creates full songs with vocals, instrumentals, or both. Supports 50+ languages, 10-600 second duration, quality presets (draft/standard/high/max), and batch generation. when_to_use: > Use when the user asks to generate music, make a song, create a track, do text-to-music, or produce new music from scratch. allowed-tools:

  • Bash
  • Read
  • Write

claude-music-generate — Text-to-Music Generation

Worked example (input → command → output)

User: "Generate a 30-second upbeat pop instrumental I can loop"

Command:

bash ~/.claude/skills/claude-music/scripts/music_engine.sh \
  --quality standard \
  generate \
  --caption "upbeat pop, catchy, synth hooks, female vocal" \
  --instrumental --duration 30 --language en

Expected JSON on stdout:

{
  "success": true,
  "task_type": "text2music",
  "model": "acestep-v15-turbo",
  "outputs": [
    {"path": "/home/$USER/Music/claude-music-output/text2music_20260416_120512_01.flac",
     "seed": 137294, "size_mb": 1.83, "index": 1},
    {"path": "/home/$USER/Music/claude-music-output/text2music_20260416_120512_02.flac",
     "seed": 837412, "size_mb": 1.80, "index": 2}
  ],
  "timing": {"generation_sec": 18.3},
  "count": 2,
  "playback_hint": "ffplay -nodisp -autoexit \"/home/$USER/Music/claude-music-output/text2music_20260416_120512_01.flac\""
}

Global flags (--quality, --format, --seed, etc.) go BEFORE the subcommand (generate). Subcommand flags (--caption, --duration, etc.) go AFTER.

Pre-Flight

  1. Run bash ~/.claude/skills/claude-music/scripts/preflight.sh "" "$OUTPUT" if output specified
  2. Run bash ~/.claude/skills/claude-music/scripts/detect_gpu.sh to determine quality tier

Basic Generation

# Simple instrumental
bash ~/.claude/skills/claude-music/scripts/music_engine.sh generate \
  --caption "upbeat electronic dance music, energetic synths, driving beat" \
  --instrumental --duration 60

# Song with lyrics
bash ~/.claude/skills/claude-music/scripts/music_engine.sh generate \
  --caption "pop ballad, female vocal, piano, emotional" \
  --lyrics "[Verse 1]
Under city lights we found our way
Every word you said still haunts my day
[Chorus]
Hold me close don't let me fall
You're the only one who hears my call" \
  --duration 120 --language en

# High quality with thinking mode
bash ~/.claude/skills/claude-music/scripts/music_engine.sh generate \
  --caption "jazz fusion, saxophone, complex harmony" \
  --quality high --duration 180 --bpm 110 --key "Bb major"

# Quick draft — 4 variants to pick from
bash ~/.claude/skills/claude-music/scripts/music_engine.sh generate \
  --caption "lo-fi hip-hop, chill, atmospheric, vinyl crackle" \
  --quality draft --instrumental --duration 60

Parameters

ParameterFlagDefaultRangeDescription
Caption--caption / -crequired<512 charsStyle/genre/instrument description
Lyrics--lyrics / -l""<4096 charsSong lyrics with structure tags
Instrumental--instrumentalfalseflagNo vocals
Language--languageenISO 639-1Vocal language (en, zh, ja, es, fr, etc.)
Duration--duration6010-600 secTarget length
BPM--bpmauto30-300Tempo (auto = model decides)
Key--keyautoe.g. "C major"Musical key
Time Sig--time-sigauto2/3/4/6Time signature
Quality--qualitystandarddraft/standard/high/maxPreset
Batch--batch21-8Number of variants
Format--formatflacflac/wav/mp3/opus/aacOutput format
Seed--seed-1intReproducibility (-1 = random)
Model--modelautoturbo/base/sft/xl-*Override DiT model

Quality Presets

  • draft: turbo, steps=8, no LM, batch=4. Fastest. Use for exploring ideas.
  • standard: turbo, steps=8, no LM, batch=2. Default. Good balance.
  • high: turbo + 1.7B LM, thinking=True, batch=2. Better structure/lyrics adherence.
  • max: base model, steps=65, LM thinking, batch=1. Best quality, ~3-5 min.

Output

JSON to stdout with paths, seeds, timing:

{
  "success": true,
  "task_type": "text2music",
  "outputs": [{"path": "/home/.../generate_20260416_120000_01.flac", "seed": 42}],
  "playback_hint": "ffplay -nodisp -autoexit \"/path/to/file.flac\""
}

Workflow Tips

  1. Start with draft quality — generate 4 variants, pick the best direction
  2. Lock the seed — once you find a good variant, use --seed <value> to reproduce it
  3. Iterate on caption — add/remove descriptors to steer the sound
  4. Use compose first — for vocal songs, use /music compose to craft proper lyrics before generating
  5. Repaint bad sections — don't regenerate the whole song; use /music repaint to fix specific parts

Caption Crafting Quick Guide

Formula: Genre + mood + instruments + vocal style + production quality

Good: "upbeat pop, female vocal, catchy, piano, modern production, 2020s sound" Bad: "a good song" (too vague) Bad: "ambient metal classical hip-hop" (conflicting genres)

For detailed guidance: load references/prompt-guide.md

Lyrics Quick Guide

  • Use structure tags: [Verse], [Chorus], [Bridge], [Intro], [Outro]
  • Keep lines 4-8 words for best vocal clarity
  • ~2-3 words per second (60s song ~ 120-180 words)
  • Avoid tongue twisters and complex vocabulary

For detailed guidance: load references/prompt-guide.md