API Reference

adafruit_midi_parser

CircuitPython helper for parsing MIDI files

This library provides classes for parsing and playing Standard MIDI Files (SMF) in CircuitPython. It supports Format 0 (single track) and Format 1 (multiple tracks) MIDI files, and provides a flexible playback system that can be extended for custom MIDI applications.

  • Author(s): Liz Clark

Implementation Notes

Software and Dependencies:

exception adafruit_midi_parser.MIDIParseError

Exception raised when there’s an error parsing a MIDI file.

class adafruit_midi_parser.MIDIParser

Class for parsing and playing Standard MIDI files. Supports Format 0 (single track) and Format 1 (multiple tracks) MIDI files.

Parameters:

filename (str) – Path to the MIDI file

Initialize the MIDI parser.

Parameters:

filename (str) – Path to the MIDI file

property bpm: float

Current tempo in beats per minute (BPM).

Returns:

The current BPM calculated from the tempo

Return type:

float

calculate_delay(event: Dict[str, Any]) → float

Calculate the delay in seconds until the next event.

Parameters:

event (dict) – The current event

Returns:

Delay in seconds until the next event

Return type:

float

clear() → None

Clear all parsed data and reset the parser state.

property current_event: Dict[str, Any] | None

The current event to be played, or None if at the end. Does not advance the event index.

Returns:

A dictionary containing event data or None if at the end of events

Return type:

Optional[Dict[str, Any]]

property current_event_index: int

Index of the next event to be played.

property events: List[Dict[str, Any]]

List of all MIDI events in the file, sorted by absolute time.

property filename: str

The filename of the MIDI file being parsed.

property format_type: int

MIDI file format type (0, 1, or 2). 0 = single track, 1 = multiple tracks, 2 = multiple songs

property more_events: bool

Whether there are more events to be played.

property next_event: Dict[str, Any] | None

The next event to be played, or None if at the end. Advances the event index.

Returns:

A dictionary containing event data or None if at the end of events

Return type:

Optional[Dict[str, Any]]

property note_count: int

Number of note-on events in the MIDI file.

Returns:

Count of note-on events

Return type:

int

property num_tracks: int

Number of tracks in the MIDI file.

parse(filename: str, debug: bool = False) → bool

Parse the MIDI file and extract events.

Parameters:

debug (bool) – Whether to print detailed parsing information

Returns:

True if parsing was successful

Return type:

bool

Raises:

MIDIParseError – If the file doesn’t exist or is not a valid MIDI file

property parsed: bool

Whether the MIDI file has been successfully parsed.

reset() → None

Reset playback to the beginning of the file.

This resets the current event index and absolute time tracking.

property tempo: int

Current tempo in microseconds per quarter note. Default is 500,000 (120 BPM).

property ticks_per_beat: int

Number of ticks per quarter note (time division) from the MIDI file.

class adafruit_midi_parser.MIDIPlayer(midi_parser: MIDIParser)

Class for playing MIDI files with timing control. Subclass this and override the event handler methods to customize behavior.

Parameters:

midi_parser (MIDIParser) – A MIDIParser instance with a parsed MIDI file

Initialize the MIDI player.

Parameters:

midi_parser (MIDIParser) – A MIDIParser instance

Raises:

MIDIParseError – If the provided parser hasn’t parsed a file yet

property finished: bool

Whether playback has completed (and not set to loop).

property loop_playback: bool

Whether playback should automatically loop when finished.

on_controller(controller: int, value: int, channel: int) → None

Called when a controller event is processed.

Override this method in a subclass to handle controller events.

Parameters:

  • controller (int) – Controller number

  • value (int) – Controller value

  • channel (int) – MIDI channel (0-15)

on_end_of_track(track: int) → None

Called when an end-of-track event is processed.

Override this method in a subclass to handle end-of-track events.

Parameters:

track (int) – Track number, or -1 for end of all tracks

on_note_off(note: int, velocity: int, channel: int) → None

Called when a note-off event is processed.

Override this method in a subclass to handle note-off events.

Parameters:

  • note (int) – MIDI note number (0-127)

  • velocity (int) – Note velocity (0-127)

  • channel (int) – MIDI channel (0-15)

on_note_on(note: int, velocity: int, channel: int) → None

Called when a note-on event is processed.

Override this method in a subclass to handle note-on events.

Parameters:

  • note (int) – MIDI note number (0-127)

  • velocity (int) – Note velocity (0-127)

  • channel (int) – MIDI channel (0-15)

on_playback_complete() → None

Called when playback reaches the end of the file.

Override this method in a subclass to handle playback completion. If loop_playback is True, playback will restart automatically after this method returns.

on_program_change(program: int, channel: int) → None

Called when a program change event is processed.

Override this method in a subclass to handle program change events.

Parameters:

  • program (int) – Program number

  • channel (int) – MIDI channel (0-15)

on_tempo_change(tempo: int) → None

Called when a tempo change event is processed.

Override this method in a subclass to handle tempo changes.

Parameters:

tempo (int) – New tempo in microseconds per quarter note

property parser: MIDIParser

The MIDIParser instance used by this player.

pause() → None

Pause playback.

Temporarily stops playback, which can be resumed from the current position.

play(loop: bool | None = None) → bool

Play the MIDI file. If already playing, process the next event.

Call this method in your main loop to continuously play the MIDI file.

Parameters:

loop (Optional[bool]) – Set to True to enable looping, False to disable, or None

Returns:

True if an event was processed, False otherwise

Return type:

bool

property playing: bool

Whether the player is currently playing.

property restart_delay: float

Delay in seconds before restarting playback when looping. Default is 3.0 seconds.

resume() → None

Resume playback from current position.

If playback has finished, call reset() on the parser first to restart from the beginning.

stop() → None

Stop playback.

This halts playback completely. Use reset() on the parser to return to the beginning of the file.