I/O

MIDI import utilities.

import_midi(midi_file)[source]

Import a MIDI file and return a dictionary with melody data.

Parameters:: midi_file (str) – Path to the MIDI file
Returns:: Dictionary containing: - ID: Filename of the MIDI file - MIDI Sequence: String representation of the melody - pitches: List of MIDI pitch values - starts: List of note start times - ends: List of note end times Returns None if the file cannot be imported
Return type:: dict or None

load_midi(midi_file)[source]

Load a single MIDI file as a Melody.

Parameters:: midi_file (str or os.PathLike) – Path to the MIDI file
Returns:: Loaded melody, or None if import failed
Return type:: Melody or None

list_midi_files(directory, *, recursive=False)[source]

Return sorted paths to .mid / .midi files in a directory.

Parameters:

directory (str or os.PathLike) – Folder to scan for MIDI files
recursive (bool, optional) – If True, search subdirectories as well (default False)

Returns:

Naturally sorted absolute paths to MIDI files

Return type:

list[str]

Raises:

FileNotFoundError – If directory does not exist or contains no MIDI files

import_midi_from_directory(directory, *, recursive=False)[source]

Load all MIDI files in a directory as Melody objects.

Parameters:

directory (str or os.PathLike) – Folder containing MIDI files
recursive (bool, optional) – If True, include MIDI files in subdirectories (default False)

Returns:

Successfully loaded melodies, in natural sort order. Files that fail to import are skipped (warnings are logged per file).

Return type:

list[Melody]

extract_time_signatures_from_midi(midi_data, starts=None, ends=None, pitches=None)[source]

Extract time signature information from MIDI data with meter estimation fallback.

Parameters:

midi_data (pretty_midi.PrettyMIDI) – The MIDI data object
starts (list[float], optional) – Note start times for meter estimation fallback
ends (list[float], optional) – Note end times for meter estimation fallback
pitches (list[int], optional) – MIDI pitch values for optimal meter estimation

Returns:

Dictionary containing: - ‘first_time_signature’: tuple of (numerator, denominator) for first time sig - ‘all_time_signatures’: list of (time, numerator, denominator) for all time sigs - ‘metric_stability’: proportion (0.0-1.0) that first time sig comprises of total - ‘is_estimated’: bool indicating if meter was estimated vs read from file

Return type:

dict

extract_tempo_from_midi(midi_data)[source]

Extract tempo information from a MIDI file.

Parameters:: midi_data (pretty_midi.PrettyMIDI) – Parsed MIDI data object
Returns:: Tempo in beats per minute (BPM). Returns 100.0 as fallback if no tempo found.
Return type:: float

extract_tempo_changes_from_midi(midi_data)[source]

Extract all tempo changes from a MIDI file.

Parameters:: midi_data (pretty_midi.PrettyMIDI) – Parsed MIDI data object
Returns:: List of (time_in_seconds, tempo_in_bpm) tuples representing tempo changes
Return type:: list[tuple[float, float]]

extract_key_signatures_from_midi(midi_path)[source]

Extract key signature information from MIDI file using mido.

Parameters:

midi_path (str) – Path to the MIDI file

Returns:

Dictionary with these keys:

first_key_signature: tuple of (key_name, mode) for the first key signature, where mode is 'major' or 'minor'
all_key_signatures: list of (key_name, mode) for all key signatures
has_key_signature: bool indicating if any key signature was found
fifths: int representing position on circle of fifths (-7 to 7)
mode: int (1 for major, -1 for minor)

Return type:

dict

Notes

Uses mido library to read key signature meta messages.