---
name: midi-playlist-repo
description: Compose retro game MIDI in /root/midi-playlist via JSON specs. Use when writing, fixing, or rendering chiptune/DOS/N64-style tunes.
version: 1.0.0
---

# midi-playlist: retro MIDI from JSON specs

Repo: `/root/midi-playlist` (stdlib-only Python; `lib/midikit.py`, `lib/songkit.py`).

## The workflow

1. Copy `tunes/specs/04_tea_break_at_the_terminal.json`, change `name`,
   `style`, `bpm`, `key`, `chords`, `melody`, `loop`.
2. `python3 tools/make_tune.py tunes/specs/<name>.json --render`
3. Never declare success without a passing run: the command re-parses the
   MIDI, renders WAV via timidity, and checks clipping / dead air / duration.
4. Whole-repo check: `python3 tests/smoke_test.py` then `./tools/build_all.sh`.

## Conventions an agent must not guess

- Bars are **0-based**; `loop.end_bar` is **EXCLUSIVE**.
- `melody_start_bar + number of '|' bars <= len(chords)`.
- If the melody uses `|`, every bar (including the last) must total 4/4 —
  the linter names the offending bar.
- Styles: `dos_adventure` (OPL-ish, supports `counter` + `fills_at`),
  `n64_ambient` (pads/flute, no drums), `chiptune_racing` (stabs, no `counter`).
- Validation reports every spec problem at once; style-incompatible fields
  warn on stderr instead of being dropped silently.

Full details, score grammar and rendering options: `AGENTS.md` in the repo.