MIDIpyToolkit 26.3.2

Enhanced MIDI manipulation library with immutable, chainable operations built on the classic MIDI.py module by Peter Billam

MIDIToolkit

Enhanced MIDI manipulation library with immutable, chainable operations built on the classic MIDI.py module by Peter Billam

---

MIDIToolkit provides a high‑level, Pythonic interface for reading, transforming, and writing MIDI files. It wraps the classic MIDI.py parser with a modern layer of immutable objects, event wrappers, track abstractions, tempo mapping utilities, and a plugin system designed for expressive, safe, and reusable MIDI processing workflows.

---

Key Features

• Immutable, chainable operations — Every transformation returns a new MIDIFile instance.
• Typed event wrappers — NoteEvent, TempoEvent, PatchChangeEvent, ControlChangeEvent, KeySignatureEvent, and more.
• Track abstraction — Filter, map, sort, copy, and inspect metadata such as duration, pitch range, and channels used.
• TempoMap utilities — Convert between ticks, milliseconds, and beats with full support for tempo changes.
• Plugin system — Extend functionality with custom plugins; includes a registry for discovery and invocation.
• Comprehensive transformations — Transpose, scale velocities, quantize, segment, time‑shift, merge, mix, concatenate, and grep channels.
• Analysis & reporting — Statistics, instrument lookup, key signature lookup, text events, validation, and human‑readable summaries.
• Flexible I/O — Load from file, bytes, opus list, or score list; save to disk or memory.
• Lazy loading — Delay file parsing until data is accessed.
• Playback — Cross‑platform MIDI playback using available system tools.

---

Installation

MIDIToolkit requires only Python 3. Download the two core files and place them in your project directory or Python path:

• MIDI.py — classic MIDI parser
• MIDIToolkit.py — enhanced toolkit

Or clone the repository:

git clone https://github.com/asigalov61/MIDIToolkit.git
cd MIDIToolkit

Import the toolkit:

from MIDIToolkit import MIDIFile

---

Quick Start

from MIDIToolkit import MIDIFile

# Load a MIDI file (lazy loading by default)
midi = MIDIFile("example.mid")

# Inspect basic properties
print(midi.ticks_per_quarter)   # e.g. 480
print(midi.num_tracks)          # number of tracks

# Get all notes
notes = midi.get_notes()
print(f"Total notes: {len(notes)}")

# Transpose all notes up by 2 semitones
transposed = midi.transpose(2)

# Save the result
transposed.save("transposed.mid")

---

Documentation & Examples

A complete reference with runnable examples is available in
EXAMPLES.md.

Topics include:

• Loading and inspecting MIDI files
• Event wrappers
• Track manipulation
• Tempo map conversions
• Note transformations
• Track‑level operations
• Merging, mixing, concatenation
• Segmentation and time shifting
• Analysis and metadata
• Plugin system
• Validation and reporting
• Playback and saving
• Working from memory
• Context manager and lazy loading

---

Project Structure

MIDIToolkit/
├── MIDI.py           # Classic low-level MIDI parser
├── MIDIToolkit.py    # Enhanced toolkit (main library)
├── EXAMPLES.md       # Comprehensive usage examples
└── README.md         # This file

---

Attribution and acknowledgements

• MIDIToolkit class was passinatelly vibe-coded together with Microsoft Copilot and DeepSeek AI
• README.md and EXAMPLES.md were co-written using Microsoft Copilot and DeepSeek AI
• Artwork was created with Microsoft Copilot
• Original MIDI.py module is a courtesy of Peter Billam

---

License

This project is open source. The original MIDI.py module is by Peter Billam and contributors; enhancements are provided under the same spirit of free use. See source files for individual notices.

---

Project Los Angeles

Tegridy Code 2026