pi-midi-zone/README.md

# MIDI Util Examples

Working examples created from the [MIDIUtil](https://github.com/MarkCWirt/MIDIUtil) source repo patterns.
All examples use MIDIUtil with beats-based (not ticks-based) time, the cleanest API for MIDI composition.

## Setup

```bash
pip3 install --break-system-packages MIDIUtil
sudo apt-get install -y fluidsynth fluid-soundfont-gm
```

## Examples

| # | File | Description |
|---|------|------|
| 01 | basic-chord.py | Chord progressions in C major |
| 02 | 90s-dance-track.py | Full multi-track 90s dance composition (arpeggio, bass, pads, drums, piano) |
| 03 | arpeggiator.py | Automated arpeggiator with ascending/descending patterns |
| 04 | single-note.py | Minimal single-note example |

## Quick Start

```bash
cd examples/
python3 04-single-note.py
python3 01-basic-chord.py
python3 03-arpeggiator.py
python3 02-90s-dance-track.py

# Play back with fluidsynth
fluidsynth -a alsa /usr/share/sounds/sf2/FluidR3_GM.sf2 90s-dance-track.mid
```

## API Reference

All time values are **in beats** (quarter notes):

| Method | Signature |
|--------|-----------|
| `addNote` | `(track, channel, pitch, time, duration, volume)` |
| `addTempo` | `(track, time, bpm)` |
| `addTrackName` | `(track, time, name)` |
| `addProgramChange` | `(track, channel, time, program)` |
| `addControllerEvent` | `(track, channel, time, controller, value)` |
| `writeFile` | `(fileHandle)` |