Hermes Agent
95480abdab
Replaces the April wreckage (fifteen 70-byte 'working' MIDIs, archived) with a proper pipeline: - lib/midikit.py: stdlib-only SMF format-1 writer + reader/verifier - lib/songkit.py: composition helpers (bar-grid score DSL with a 4/4 bar linter, OPL arps, driving bass, vibrato, drum patterns) - tunes/: three original tunes - DOS adventure theme (Dm/132), N64 ambient (G/72), chiptune racing (Em/152) - all with LOOP_START/ LOOP_END markers for game engines - tools/build_all.sh + tools/check_wav.py: generate, verify, render via timidity+FluidR3, fail on clipping/dead air - tests/smoke_test.py: round-trip verified against mido All three tunes render clean: no clipping, no dead air, durations match, chromaticism audited against the chord chart.
MIDI Playlist — retro game music, built from code
Kevin Hermes' toolkit for composing early-90s flavoured MIDI: DOS Sound Blaster/OPL themes, N64-era ambient, chiptune. Built for retro game development (loop markers, multi-track GM arrangements) and podcast audio beds.
Everything is code-first: tunes are Python scripts that generate
verified .mid files. No DAW, no pip dependencies in the library, no
hand-edited hex. If a tune is wrong, you fix a bar of text and rebuild.
The tunes
| # | Tune | Style | Key/BPM | Length |
|---|---|---|---|---|
| 01 | Service Station at 2 AM | DOS adventure main theme (LucasArts-meets-OPL) | Dm / 132 | ~58s |
| 02 | Kestrel Over The Fens | N64 ambient exploration theme | G / 72 | ~82s |
| 03 | The U's Late Equaliser | chiptune sports/racing theme | Em / 152 | ~44s |
All files are Standard MIDI File format 1, 480 tpq, General MIDI
instruments, with LOOP_START / LOOP_END markers so a game engine can
skip the intro and loop the gameplay section.
Quick start
./tools/build_all.sh # regenerate, verify, render WAVs, audio checks
python3 tests/smoke_test.py # library self-test
Rendering needs timidity + a GM soundfont (FluidR3_GM.sf2). Note:
Debian's timidity build has no -O2 mode — use -Ow -s 44.
Layout
lib/midikit.py SMF writer + reader/verifier (stdlib only)
lib/songkit.py composition helpers: bar grids, OPL arps, vibrato, drums
tunes/*.py one script per tune; each self-verifies on run
tools/build_all.sh full pipeline: generate -> verify -> render -> check
tools/check_wav.py WAV sanity: clipping, loudness, dead air
tests/smoke_test.py library round-trip test (cross-checked with mido)
midi/ generated .mid files
archive/ the April 2026 wreckage (70-byte "working" MIDIs, rest in peace)
Composing a new tune
Copy a tune script. Melodies are written as bar grids:
MELODY = """
D4-8 F4-8 A4-4 A4-8 Bb4-8 A4-4 | F4-8 A4-8 Bb4-4 A4-8 F4-8 D4-4
"""
Tokens are PITCH-dur-vel (D4-8, F5-16-80, rests r8); | separates
bars and every bar must total 4/4 — the parser lints you. Accompaniment
comes from the helpers: arp() (OPL-style 16ths), bass_drive() (driving
8ths with chromatic approaches), drums() (named patterns), vibrato()
(pitch-bend, the difference between a beep and an OPL voice).
Mix levels: set CC7 (volume) and CC10 (pan) per track at tick 0, and
check the render for clipping — tools/check_wav.py fails the build
on a peak of 32767.
Gotchas learned the hard way
- Format 1 with a dedicated Conductor track for tempo/key/time sigs.
- Sort events by absolute tick at write time; compose in any order.
- Note-off must match note-on channel+pitch exactly; no running status in generated files (simpler, universally safe).
- Pitch bends count toward file duration — a vibrato tail past the last note extends the song.
- Velocity-0 note-ons are legal note-offs, but 0x80 is clearer.
- GM2 instruments (ocarina!) are unreliable on GM1 synths — use pan flute (76) for ocarina-ish leads.
- timidity's "Last N MIDI events are ignored" warning is harmless (trailing bends/resets), but "Notes lost totally" is not.
- A bar-length linter in the score parser catches more composition bugs than any amount of staring at note lists.