acestep

Files (1)

• SKILL.md

SKILL.md (first lines)

# ACE-Step 1.5 Music Generation

Open-source music generation via `python3 -m video_toolkit.music_gen`.

**Cloud providers:**
- **acemusic** (default) — Official ACE-Step cloud API with XL Turbo (4B) model + 5Hz LM thinking mode. Free API key from [acemusic.ai/api-key](https://acemusic.ai/api-key). No GPU required.
- **modal** — Self-hosted ACE-Step 2B Turbo on Modal. Requires `MODAL_MUSIC_GEN_ENDPOINT_URL`.
- **runpod** — Self-hosted ACE-Step 2B Turbo on RunPod. Requires `RUNPOD_ACESTEP_ENDPOINT_ID`.

## Setup

```bash
# acemusic (recommended — free, best quality, no GPU)
echo "ACEMUSIC_API_KEY=your_key" >> .env
# Get key at https://acemusic.ai/api-key

# Self-hosted (optional fallback)
python3 -m video_toolkit.music_gen --setup             # RunPod
modal deploy docker/modal-music-gen/app.py    # Modal
```

## Quick Reference

```bash
# Basic generation (uses acemusic XL Turbo by default)
python3 -m video_toolkit.music_gen --prompt "Upbeat tech corporate" --duration 60 --output bg.mp3

# Generate 4 variations, pick the best
python3 -m video_toolkit.music_gen --prompt "Calm ambient piano" --duration 30 --variations 4 --output ambient.mp3

# Fast mode (disable thinking)
python3 -m video_toolkit.music_gen --no-thinking --prompt "Quick draft" --duration 30 --output draft.mp3

# With musical control
python3 -m video_toolkit.music_gen --prompt "Calm ambient piano" --duration 30 --bpm 72 --key "D Major" --output ambient.mp3

# Scene presets (video production)
python3 -m video_toolkit.music_gen --preset corporate-bg --duration 60 --output bg.mp3
python3 -m video_toolkit.music_gen --preset tension --duration 20 --output problem.mp3
python3 -m video_toolkit.music_gen --preset cta --brand my-brand --duration 15 --output cta.mp3

# Vocals with lyrics
python3 -m video_toolkit.music_gen --prompt "Indie pop jingle" --lyrics "[verse]\nBuild it better\nShip it faster" --duration 30 --output jingle.mp3

# Cover / style transfer
python3 -m video_toolkit.music_gen --cover --reference theme.mp3 --prompt "Jazz piano version" --duration 60 --output jazz_cover.mp3

# Repaint a weak section
python3 -m video_toolkit.music_gen --repaint --input track.mp3 --repaint-start 15 --repaint-end 25 --prompt "Guitar solo" --output fixed.mp3

# Continue from existing audio
python3 -m video_toolkit.music_gen --continuation --input track.mp3 --prompt "Continue with jazz piano" --output extended.mp3

# Stem extraction
python3 -m video_toolkit.music_gen --extract vocals --input mixed.mp3 --output vocals.mp3

# Fall back to self-hosted
python3 -m video_toolkit.music_gen --cloud modal --prompt "Background music" --duration 60 --output bg.mp3
```

## Fixing "Samey" Output

If generated music sounds repetitive or lacks variety, try these in order:

1. **Use acemusic cloud** (default) — the XL Turbo 4B model is significantly more capable than the 2B model on Modal/RunPod
2. **Keep thinking mode on** (default for acemusic) — the 5Hz LM enriches sparse prompts into detailed musical descriptions
3. **Generate variations** — `--variations 4` generates 4 takes, pick the best
4. **Use stochastic inference** — `--infer-method sde` adds randomness (same seed gives different results)
5. **Vary BPM and key across scenes** — don't use the same preset for every scene
6. **Write sparser prompts** — "Upbeat indie rock" gives the model more creative freedom than a hyper-detailed description
7. **Vary seeds** — omit `--seed` to let each generation be unique

## Creating a Song (Step by Step)

### 1. Instrumental background track (simplest)
```bash
python3 -m video_toolkit.music_gen --prompt "Upbeat indie rock, driving drums, jangly guitar" --duration 60 --bpm 120 --key "G Major" --output track.mp3
```

### 2. Song with vocals and lyrics
Write lyrics in a temp file or pass inline. Use structure tags to control song sections.

```bash
# Write lyrics to a file first (recommended for longer songs)
cat > /tmp/lyrics.txt << 'LYRICS'
[Verse 1]
Walking through the morning light
Coffee in my hand feels right
Another day to build and dream
Nothing's ever what it seems

[Chorus - anthemic]
WE KEEP MOVING FORWARD
Through the noise and doubt
We keep moving forward
That's what it's about

[Verse 2]
Screens are glowing late at night
Shipping code until it's right
The deadline's close but so are we
Almost there, just wait and see

[Chorus - bigger]
WE KEEP MOVING FORWARD
Through the noise and doubt
We keep moving forward
That's what it's about

[Outro - fade]
(Moving forward...)
LYRICS

# Generate the song
python3 -m video_toolkit.music_gen \
  --prompt "Upbeat indie rock anthem, male vocal, driving drums, electric guitar, studio polish" \
  --lyrics "$(cat /tmp/lyrics.txt)" \
  --duration 60 \
  --bpm 128 \

From xaralis/video-toolkit, MIT.

More from xaralis/video-toolkit