Quickstart

Generate professional drum tracks in minutes.

Installation

Install as a global CLI tool

The recommended approach — installs the midi-drums command system-wide using uv:

git clone https://github.com/fsecada01/midi-drums.git
cd midi-drums
uv tool install .

Now midi-drums is available anywhere in your terminal.

Or install as a development dependency

git clone https://github.com/fsecada01/midi-drums.git
cd midi-drums

# Core only
uv venv && source .venv/bin/activate
uv pip install -e "."

# With AI support
uv pip install -e ".[ai]"

# With dev tools (testing, linting)
uv pip install -e ".[dev,ai]"

Tip

The project requires Python 3.12+. Check with python --version.

AI setup (optional)

To use natural language generation, set your API provider and key:

export AI_PROVIDER="anthropic"       # anthropic | openai | groq | cohere
export ANTHROPIC_API_KEY="sk-ant-..."
export AI_MODEL="claude-sonnet-4-20250514"  # optional — smart defaults apply

Variable	Description	Default
AI_PROVIDER	Backend provider	anthropic
AI_MODEL	Model identifier	Provider default
AI_TEMPERATURE	Generation randomness (0–2)	0.7
AI_MAX_TOKENS	Max output tokens	4096

Your first drum track

Generate via Python API

from midi_drums.api.python_api import DrumGeneratorAPI

api = DrumGeneratorAPI()

# One function call → complete song
song = api.create_song("metal", "death", tempo=180)
api.save_as_midi(song, "death_metal.mid")

print("Generated:", song.total_bars, "bars")

This generates a multi-section death metal song (intro → verse → chorus → bridge → outro) and writes it to a standard MIDI file compatible with EZDrummer 3, Superior Drummer, and any DAW.

Try different genres

api = DrumGeneratorAPI()

# Jazz swing with complex ride pattern
jazz = api.create_song("jazz", "swing", tempo=120)
api.save_as_midi(jazz, "jazz_swing.mid")

# Funk groove with ghost notes
funk = api.create_song("funk", "shuffle", tempo=98)
api.save_as_midi(funk, "funk_shuffle.mid")

# Classic rock with custom complexity
rock = api.create_song("rock", "classic", tempo=140, complexity=0.6)
api.save_as_midi(rock, "rock_classic.mid")

CLI usage

The midi-drums command mirrors the Python API:

# Generate songs
midi-drums generate --genre metal --style death --tempo 180 --output death.mid
midi-drums generate --genre jazz --style swing --tempo 120 --output jazz.mid

# Single section pattern
midi-drums pattern --genre rock --section verse --style classic --output verse.mid

# List what's available
midi-drums list genres
midi-drums list styles --genre jazz
midi-drums list drummers
midi-drums info

Module mode

Without the CLI tool install, run as a module: python -m midi_drums.api.cli generate --genre metal ...

Applying drummer styles

Any pattern can have a legendary drummer's playing style applied to it:

api = DrumGeneratorAPI()

# Generate a base pattern
pattern = api.generate_pattern("rock", "verse", "classic")

# Apply Bonham's behind-the-beat feel and triplet vocabulary
bonham = api.apply_drummer_style(pattern, "bonham")
api.save_pattern_as_midi(bonham, "bonham_verse.mid", tempo=130)

# Or specify the drummer at song creation time
jazz_weckl = api.create_song("jazz", "fusion", tempo=135, drummer="weckl")
api.save_as_midi(jazz_weckl, "jazz_weckl.mid")

Name	Key Characteristic	Best With
bonham	Behind-beat, triplets, heavy accents	rock, blues
porcaro	Half-time shuffle, ghost notes, precision	rock, funk
weckl	Linear, fusion, sophisticated coordination	jazz, fusion
chambers	Deep pocket, funk mastery, chops	funk, jazz
roeder	Atmospheric sludge, minimal, crushing	metal (doom)
dee	Speed, precision, twisted accents	metal
hoglan	Mechanical precision, blast beats	metal (death)

Full songs with custom structure

from midi_drums import DrumGenerator

gen = DrumGenerator()
song = gen.create_song(
    genre="rock",
    style="classic",
    tempo=140,
    structure=[
        ("intro",  4),
        ("verse",  8),
        ("chorus", 8),
        ("verse",  8),
        ("chorus", 8),
        ("bridge", 4),
        ("chorus", 8),
        ("outro",  4),
    ],
    complexity=0.7,
    humanization=0.35,
)
gen.export_midi(song, "rock_song.mid")

AI prompt — natural language

With AI dependencies installed, generate drums from plain English using the prompt subcommand:

# Single pattern — AI picks genre, style, and complexity from your words
midi-drums prompt "funky groove with ghost notes and syncopation"
midi-drums prompt "aggressive metal breakdown with double bass" --tempo 180 -o breakdown.mid

# Full multi-section song composed by an AI agent
midi-drums prompt "Testament-inspired death metal, Hoglan blast beats, Lombardo breakdowns" \
    --song --tempo 185

# --save-metadata organises everything into output/<name>/
midi-drums prompt "brutal death metal with progressive solo section" \
    --song --save-metadata --tempo 185 --output my_song.mid

The --save-metadata flag creates an organised directory:

output/my_song/
  my_song.mid          ← full assembled song
  metadata.json        ← prompt, structure, agent composition notes
  parts/
    00_intro.mid       ← each section exported individually
    01_verse.mid
    02_chorus.mid
    03_breakdown.mid
    04_solo_slow.mid
    ...

Flag	Description
--song	Compose a full multi-section song via AI agent
--save-metadata	Write metadata.json + parts/ into output/<name>/
--output / -o	MIDI filename (auto-named from prompt if omitted)
--tempo	Tempo in BPM (default: 120)
--drummer	Apply a drummer style (bonham, hoglan, weckl, …)
--rpp	Also create a Reaper project with section markers

Tip

Use the parts files to individually import each drum section into your DAW — handy for rearranging song structure or A/B-testing different sections.

Reaper project export

Optionally export the drum track alongside a Reaper project with auto-placed section markers:

# CLI: one command creates both .rpp and .mid
midi-drums reaper export \
    --genre metal --style doom --tempo 120 \
    --output doom.rpp --midi

# Python API
from midi_drums.api.python_api import DrumGeneratorAPI
from midi_drums.exporters import ReaperExporter

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

exporter = ReaperExporter()
exporter.export_with_markers(song=song, output_rpp="doom.rpp")

See the Reaper Integration Tutorial for the full workflow.

Explore further

Recipes — complete worked examples for metal, jazz, and prog rock
Reaper Tutorial — full DAW integration workflow
API Reference — auto-generated from docstrings