Usage Guide

Command-Line Interface

MIDIDiff provides several commands and options for working with MIDI files.

Diff Command

The main functionality - compare two MIDI files:

midi-diff diff fileA.mid fileB.mid output.mid

Or with backward compatibility (the diff subcommand is optional):

midi-diff fileA.mid fileB.mid output.mid

Debug Info Command

Display diagnostic and environment information:

midi-diff debug-info

This shows:

Python version
MIDIDiff version
Installation path
Dependencies and their versions
System information

Check Updates Command

Check for available updates from PyPI:

midi-diff check-updates

Upgrade Command

Upgrade midi-diff to the latest version:

midi-diff upgrade

To include pre-release versions:

midi-diff upgrade --pre

Completion Command

Generate shell completion scripts for popular shells:

midi-diff completion bash        # Bash
midi-diff completion zsh         # Zsh
midi-diff completion fish        # Fish
midi-diff completion powershell  # PowerShell
midi-diff completion cmd         # Command Prompt (prints doskey helper)

For detailed installation instructions for each shell, see the Shell Completions guide.

Version Information

Display version and environment info:

midi-diff --version
# or
midi-diff -V

To include an update check, set the environment variable:

MIDIFF_CHECK_UPDATES=1 midi-diff --version

Architecture

CLI Sub-package (v1.0.0+)

Starting with version 1.0.0, the CLI has been separated into its own sub-package (midi_diff.cli) to improve separation of concerns and allow the core library to be used without CLI dependencies.

Core library (midi_diff): Contains note extraction, diff logic, and data models. Has minimal dependencies (mido only).
CLI sub-package (midi_diff.cli): Contains argument parsing, version reporting, debug info, and environment checks. Requires rich for enhanced output.

Migration note: If you were importing from midi_diff.cli in your code, this continues to work through a backward compatibility shim that will be maintained through the 1.x release series.

API Stability

Starting with version 1.0.0, the following API surface is considered stable and will follow semantic versioning:

Core functions: midi_diff.core.main()
Data models: midi_diff.midi_utils.NoteEvent
Utility functions: midi_diff.midi_utils.extract_notes(), midi_diff.midi_utils.notes_to_midi()
CLI entry point: midi-diff command and midi_diff.cli.cli() function

Breaking changes to these APIs will result in a major version bump (2.0.0, etc.).