API Reference

This page provides detailed API documentation for the MIDIDiff package.

Core Module

Author:: Inspyre Softworks
Project:: MIDIDiff
File:: midi_diff/core.py
Description:: Core functionality for comparing two MIDI files and generating a diff MIDI file.

midi_diff.core.main(file_a, file_b, out_file)[source]

Main function to compute the diff between two MIDI files and save the result.

Parameters:

file_a (str | pathlib.Path) – Path to the first MIDI file.
file_b (str | pathlib.Path) – Path to the second MIDI file.
out_file (str | pathlib.Path) – Path to save the output diff MIDI file. Existing files will be avoided by incrementing the filename.

MIDI Utilities Module

Author:: Inspyre Softworks
Project:: MIDIDiff
File:: midi_diff/midi_utils.py
Description:: Utilities for parsing MIDI files into NoteEvent objects and constructing MIDI files from NoteEvent sequences.

class midi_diff.midi_utils.NoteEvent(pitch, start, duration, velocity, PITCH_MIN=0, PITCH_MAX=127, VELOCITY_MIN=0, VELOCITY_MAX=127)[source]

Bases: object

Immutable representation of a MIDI note event.

Stores pitch, start tick, duration (ticks), and velocity. Values are validated on construction to ensure they are within MIDI/logical bounds.

pitch: int

start: int

duration: int

velocity: int

PITCH_MIN: int

PITCH_MAX: int

VELOCITY_MIN: int

VELOCITY_MAX: int

__post_init__()[source]

Validates fields after dataclass initialization.

Raises:

TypeError – If any field is not an int.
ValueError – If any field is out of bounds.

identity_key()[source]

Returns the identity tuple used for diff-style comparisons.

By design, velocity is excluded so notes match by musical placement rather than loudness.

Returns:: (pitch, start, duration)
Return type:: tuple[int, int, int]

__init__(pitch, start, duration, velocity, PITCH_MIN=0, PITCH_MAX=127, VELOCITY_MIN=0, VELOCITY_MAX=127)

midi_diff.midi_utils.extract_notes(mid)[source]

Parse a MIDI file into NoteEvent objects.

Notes are collected across all tracks, then sorted by start tick for stable ordering.

Parameters:: mid (mido.MidiFile) – MIDI file to parse.
Returns:: Note events extracted from the MIDI file.
Return type:: list[NoteEvent]

midi_diff.midi_utils.notes_to_midi(notes, ticks_per_beat=480)[source]

Construct a minimal MIDI file containing the given notes.

Parameters:

notes (Iterable[NoteEvent]) – Notes to encode.
ticks_per_beat (int) – Resolution of the generated MIDI file.

Returns:

A MIDI file containing the specified notes on a single track.

Return type:

mido.MidiFile

CLI Module

Author:

Inspyre Softworks

Project:

MIDIDiff

File:

midi_diff/cli/__init__.py

Description:

CLI sub-package for MIDIDiff, providing command-line interface functionality.

This package contains the CLI entry point and related utilities, separated from the core library to allow the core to be used independently without CLI dependencies.

midi_diff.cli.cli()[source]

Main entry point for the midi-diff command-line tool.

This function is called when the midi-diff command is executed.

CLI Main Module

Author:: Inspyre Softworks
Project:: MIDIDiff
File:: midi_diff/cli/main.py
Description:: Main CLI logic and argument parsing for MIDIDiff.

midi_diff.cli.main.run_cli(argv=None)[source]

Main CLI entry point for MIDIDiff.

Parameters:: argv (Sequence[str] | None) – Command-line arguments to parse. If None, defaults to sys.argv[1:]. Accepts any sequence of strings (e.g., list, tuple) for testability.

Usage:: midi-diff fileA.mid fileB.mid output.mid (assumes ‘diff’ subcommand) midi-diff diff fileA.mid fileB.mid output.mid midi-diff debug-info midi-diff –version

midi_diff.cli.main.build_parser()[source]

Build and return the argument parser for MIDIDiff CLI.

Returns:: Configured ArgumentParser instance
Return type:: ArgumentParser

CLI Version Module

Author:: Inspyre Softworks
Project:: MIDIDiff
File:: midi_diff/cli/version.py
Description:: Version and debug information utilities for the MIDIDiff CLI.

midi_diff.cli.version.print_version_info()[source]

Print formatted version information to the console.

midi_diff.cli.version.print_debug_info()[source]

Print comprehensive debug information in Rich Markdown format.

midi_diff.cli.version.check_for_updates_command()[source]

Explicitly check for updates and display the result.

This is called by the ‘check-updates’ subcommand.

midi_diff.cli.version.upgrade_package(include_pre=False)[source]

Upgrade the midi-diff package using pip.

Parameters:: include_pre (bool) – Whether to include pre-release versions