mdmi-cli 1.0.1

CLI tool for working with the Mega Drive MIDI Interface (MDMI)

Mega Drive MIDI Interface CLI

CLI for controlling the Mega Drive MIDI Interface (MDMI). Helps you load presets from instrument files, clear presets, list WOPN instruments, and test connectivity.

Features

• Load presets from instrument files:
  • DefleMask preset versions 8, 9 and 11
  • WOPN versions 1 and 2, as used by libOPNMIDI
  • TFI
• Dump presets from MDMI to files (DMP or TFI format)
• Dump FM channel parameters from MDMI to files (DMP or TFI format)
• Clear presets. Individual user presets or all presets at once
• List WOPN instruments
• Connectivity testing: Ping/pong functionality to test MDMI connectivity
• Performance testing: Continuous latency measurement with statistics and histogram generation

Installation

Latest version from PyPI:

pip install mdmi-cli

Usage

Load a preset

# Load TFI preset to program 0
mdmi load-preset example.tfi --program 0

# Load DMP preset to program 5
mdmi load-preset example.dmp --program 5

# Load specific WOPN instrument to program 10
mdmi load-preset soundbank.wopn --program 10 --bank 0 --instrument 5 --bank-type melody

Dump presets

# Dump preset from program 5 to DMP file
mdmi dump-preset --program 5 --format dmp --filename my_preset.dmp

# Dump preset with auto-generated filename (preset_5.dmp)
mdmi dump-preset --program 5

# Dump preset to TFI file
mdmi dump-preset --program 10 --format tfi --filename my_preset.tfi

Dump FM channel parameters

# Dump FM channel parameters from MIDI channel 5 to DMP file
mdmi dump-channel --channel 5 --format dmp --filename channel_5.dmp

# Dump with auto-generated filename (channel_05.dmp)
mdmi dump-channel --channel 5

# Dump to TFI file
mdmi dump-channel --channel 3 --format tfi --filename channel_3.tfi

WOPN file management

# List contents of a WOPN file (first 10 instruments per bank)
mdmi list-wopn soundbank.wopn

# List all instruments in WOPN file
mdmi list-wopn soundbank.wopn --full

# Load percussion instrument from WOPN
mdmi load-preset soundbank.wopn --program 20 --bank 0 --instrument 3 --bank-type percussion

Clear presets

# Clear preset at program 5
mdmi clear-preset --program 5

# Clear all presets (with confirmation)
mdmi clear-all-presets

# Clear all presets (skip confirmation)
mdmi clear-all-presets --confirm

Test connectivity

# Continuously ping MDMI (stop with Ctrl+C)
mdmi ping

# Send exactly 5 pings
mdmi ping -n 5

# Add 16 bytes of extra packet data
mdmi ping --size 16

# Use a custom timeout
mdmi ping --timeout 10.0

ping now behaves like a standard network ping: it runs continuously by default, supports -n/--count to stop after a fixed number of packets, and supports --size to append additional packet data after the ping ID.

Performance testing

# Run continuous ping/pong latency test (stop with Ctrl+C)
mdmi perf-test

# Run test for specific duration with custom interval
mdmi perf-test --duration 30 --interval 0.05

# Customize histogram filename
mdmi perf-test --hist-filename my_latency_test.png

# Test with custom timeout for individual pings
mdmi perf-test --timeout 1.0 --duration 60

List available MIDI ports

# List all available MIDI input and output ports
mdmi list-ports

Common Options

All commands support these common options:

MIDI Port Selection

# Use specific MIDI ports instead of environment variables
mdmi load-preset example.tfi --program 0 --midi-out "IAC Driver Bus 1"

# Commands with bidirectional communication support input ports
mdmi ping --midi-out "IAC Driver Bus 1" --midi-in "IAC Driver Bus 2"
mdmi dump-preset --program 5 --midi-out "Port 1" --midi-in "Port 2"

Dry Run

# Test with fake interface (no real MIDI hardware required)
mdmi load-preset example.tfi --program 0 --dry-run
mdmi perf-test --dry-run --duration 5
mdmi ping --dry-run

Timeout

# Custom timeouts for bidirectional commands
mdmi ping --timeout 10.0
mdmi dump-preset --program 3 --timeout 5.0

Configuration

Environment Variables

• MDMI_MIDI_OUT: Default MIDI output port name
• MDMI_MIDI_IN: Default MIDI input port name
• MDMI_MIDI_PORT: Legacy fallback for MIDI output port

Command-line Options

• --midi-out TEXT: MIDI output port name (overrides environment variables)
• --midi-in TEXT: MIDI input port name for bidirectional commands (overrides MDMI_MIDI_IN)
• --dry-run: Use fake MIDI interface for testing
• --timeout FLOAT: Timeout for bidirectional commands (default varies by command)

Development

Build

# Install cli (from source)
make install

# Run tests
make test

Release

1. Bump the version in mdmi/__init__.py
2. Add a version tag: git tag v...
3. Push the tags: git push --tags