Use Cases

Realistic, end-to-end scenarios that combine multiple features — not just single API calls.

Scoring a demo with one full-song call

You have a song idea and want a complete, multi-section drum track without hand-assembling verse/chorus/bridge structure yourself. create_song does this in a single call, using each genre's default section layout:

midi-drums generate --genre metal --style death --tempo 180 --drummer hoglan --output demo.mid
from midi_drums.api.python_api import DrumGeneratorAPI

api = DrumGeneratorAPI()

song = api.create_song(
    "metal", "death",
    tempo=180,
    drummer="hoglan",
    complexity=0.8,
    humanization=0.3,
)
api.save_as_midi(song, "demo.mid")

print(song.total_bars, "bars across", len(song.sections), "sections")

The result is a single MIDI file with an intro, verse, chorus, bridge, and outro already arranged and humanized — ready to drop into a DAW as a scratch drum track.

Sample-pack-style batch export

You want a folder of reference tracks spanning several genres, styles, and drummer personalities — e.g. to A/B different pockets for the same tempo, or to build a demo pack. batch_generate takes a list of specs and writes them all in one pass:

from midi_drums.api.python_api import DrumGeneratorAPI

api = DrumGeneratorAPI()

specs = [
    {"genre": "metal", "style": "death", "tempo": 180, "drummer": "hoglan"},
    {"genre": "rock", "style": "classic", "tempo": 140, "drummer": "bonham"},
    {"genre": "jazz", "style": "swing", "tempo": 120, "drummer": "weckl"},
    {"genre": "funk", "style": "shuffle", "tempo": 98, "drummer": "chambers"},
    {"genre": "electronic", "style": "techno", "tempo": 128},
]

files = api.batch_generate(specs, "output/sample_pack/")
print(f"Wrote {len(files)} tracks to output/sample_pack/")
Tip

Each spec accepts any keyword create_song does (complexity, humanization, structure, …), so a batch can mix simple defaults with fully custom song structures.

The Reaper sidecar round-trip

reaper/create_song_sections.lua bridges REAPER and midi-drums bi-directionally through a midi_drums_sections.json sidecar file, so either side can drive the song structure. There are three modes, all triggered from the same REAPER action:

Mode 1 — REAPER drives the structure

Lay out regions on the REAPER timeline first (names + bar counts), run the Lua script, answer YES on the first dialog. The script writes the sidecar from your regions and calls midi-drums to generate matching drums:

# What the Lua script runs under the hood
midi-drums generate --genre metal --style doom --sidecar midi_drums_sections.json --output drums.mid

Mode 2 — Python drives the structure

Generate a song in Python first, export a sidecar alongside it, then let the Lua script (answer NO, then YES) build matching REAPER regions from that sidecar:

from midi_drums.api.python_api import DrumGeneratorAPI

api = DrumGeneratorAPI()
song = api.create_song("metal", "doom", tempo=70)

# Writes drums.mid and drums.json (the sidecar) in one call
api.save_as_midi_with_sidecar(song, "drums.mid")

Drop drums.json next to your REAPER project as midi_drums_sections.json (or point SIDECAR_PATH at it in the Lua script's config block), then run the script.

Mode 3 — An AI agent drives the structure

Skip both dialogs (NO, then NO) and let an AI agent choose the section structure from a natural-language prompt, writing the sidecar for REAPER to consume:

midi-drums prompt "Testament-inspired death metal, Hoglan blast beats, Lombardo breakdowns" \
    --song --tempo 185 --write-sidecar midi_drums_sections.json --output drums.mid
Blocking call

AI mode takes roughly 20–45 seconds since it's a full agent composition pass — the Lua script warns before blocking REAPER's UI while it waits.

See the Reaper Integration Tutorial for marker-based (non-sidecar) export, and reaper/README.md in the repo for installing the Lua script itself.

Iterating with AI, then locking in a drummer

A common workflow: describe the groove you want in plain English, iterate on the description until the AI's interpretation feels right, then apply a specific legendary drummer's style on top of the winning pattern.

1

Iterate on the description

midi-drums prompt "funky groove with ghost notes and syncopation" -o try1.mid
midi-drums prompt "funky groove, heavier ghost notes, pushed 16ths, tighter pocket" -o try2.mid

Each call is fast (single pattern, not a full song) — cheap enough to iterate on wording until the groove matches what you're hearing.

2

Lock in a drummer once you're happy

# Apply a drummer directly on the next AI generation
midi-drums prompt "funky groove, heavier ghost notes, pushed 16ths, tighter pocket" \
    --drummer chambers -o final.mid
# Or pass the drummer straight into the AI call itself
from midi_drums.ai.ai_api import DrumGeneratorAI
from midi_drums.api.python_api import DrumGeneratorAPI

ai = DrumGeneratorAI()
pattern, info = ai.generate_pattern_from_text_sync(
    "funky groove, heavier ghost notes, pushed 16ths, tighter pocket",
    tempo=100,
    drummer_style="chambers",
)

api = DrumGeneratorAPI()
api.save_pattern_as_midi(pattern, "final.mid", tempo=100)

Because drummer styles are composable modifications applied after generation (see Applying drummer styles), the AI-chosen pattern and the drummer's signature feel stay decoupled — swap either independently.

Explore further