Diving into MIDI file editing without first checking the file’s structure can cause headaches. Hidden tracks or stray note events often disrupt editing, so a quick inspection step helps you avoid these issues and lets you focus on the parts you want to change.
Why MIDI Inspection Matters
MIDI files store musical events—note starts, durations, and velocities—rather than audio recordings. The MIDI protocol, introduced in 1983, was built for transmitting musical-performance instructions. As the MIDI Association puts it, "a MIDI file has no sound of its own"; it holds event data like notes, velocity, controller movements, and other instructions. Each file may include multiple tracks and channels, and sometimes you’ll find unexpected notes or incomplete events. MIDI messages use a 7-bit data structure, so note and velocity values run from 0 to 127, and channels are usually numbered from 1 to 16. Before moving notes in a piano roll, map out the file’s structure and content. The same pitch can show up on different channels, and what you hear depends on the synthesizer or software interpreting the events.
Setting Up the Python MIDI Reader
To analyze a MIDI file, you’ll need Python 3 and the mido package. Install mido in your working environment using:
python -m pip install mido
Save your MIDI file locally. The script here reads the file’s structure without playing audio or changing the file. Mido is a Python library for working with MIDI messages, ports, and files. It gives you access to every message in the file, including meta messages like tempo, time signature, and markers. This lets you inspect both musical and non-musical events in each track.
Running the Inspection Script
Use the following Python script to summarize each track’s event count, note count, pitch and velocity ranges, and unmatched note events. Save it as inspect_midi.py and replace phrase.mid with your MIDI file’s path:
from collections import defaultdict, deque
from pathlib import Path
import sys
import mido
path = Path(sys.argv[1] if len(sys.argv) > 1 else "phrase.mid")
midi = mido.MidiFile(path)
print(f"file: {path.name}")
print(f"format: {midi.type}; ticks per beat: {midi.ticks_per_beat}")
for number, track in enumerate(midi.tracks, start=1):
tick = 0
notes = 0
pitches = []
velocities = []
active = defaultdict(deque)
unmatched_off = 0
for message in track:
tick += message.time
if message.type == "note_on" and message.velocity > 0:
key = (getattr(message, "channel", 0), message.note)
active[key].append(tick)
pitches.append(message.note)
velocities.append(message.velocity)
notes += 1
elif message.type == "note_off" or (message.type == "note_on" and message.velocity == 0):
key = (getattr(message, "channel", 0), message.note)
if active[key]:
active[key].popleft()
else:
unmatched_off += 1
unmatched_on = sum(len(starts) for starts in active.values())
pitch_range = f"{min(pitches)}–{max(pitches)}" if pitches else "none"
velocity_range = f"{min(velocities)}–{max(velocities)}" if velocities else "none"
print(
f"track {number}: events={len(track)}, notes={notes}, "
f"pitch={pitch_range}, velocity={velocity_range}, "
f"unmatched_on={unmatched_on}, unmatched_off={unmatched_off}"
)Run the script with:
python inspect_midi.py phrase.mid
The output lists each track’s statistics. Note numbers appear instead of note names, so compare pitch ranges by number or check your editor’s convention before translating to named octaves. If you see a wider pitch range than expected, review the tracks and channels before editing. MIDI note and velocity values always fall between 0 and 127, reflecting the protocol’s 7-bit data structure. Velocity in MIDI is a performance parameter, not a direct measure of audio amplitude, and the destination instrument interprets it.
Interpreting the Results
This inspection reports the number of events and notes per track, the pitch and velocity ranges, and any unmatched note starts or ends. It does not identify instrument sounds or judge musical phrasing. If a track contains no notes, it may only hold tempo or marker events, since MIDI files can include meta and non-note events. Unmatched note events point to missing pairs—review those tracks and channels carefully. In MIDI, a note release can be encoded as a Note Off message or as a Note On message with velocity zero. The script’s logic follows the standard convention by treating only Note On messages with velocity greater than zero as note starts, and recognizing Note On messages with velocity zero as equivalent to Note Off commands. This distinction matters for accurate event matching, especially since the same pitch can occur on different channels at the same time.
Checklist for Editing MIDI Files
After inspection, open the file in a piano roll editor and compare the notes to your intended part. Focus on:
- Pitch: Do the notes match your melody or chord line?
- Start time: Are any notes offset from the expected pulse?
- Duration: Do notes overlap or end unexpectedly?
- Velocity: Are note velocities consistent with your intended dynamics?
Work through these categories one at a time. Always keep a backup of the original MIDI file so you can compare changes. When editing, remember that event timing in MIDI is represented as a sequence of messages with delta times, and absolute positions are determined by accumulating these values. Event counts, pitch and velocity ranges, and unmatched note summaries come from the message sequence, not from single note objects. For educators and learners working with digital music, knowing these details supports more effective use of MIDI in music technology courses and digital composition projects. For further technical details, the Mido project documentation provides comprehensive guidance on message handling and file operations.
Further Learning and Related Guides
For more on MIDI velocity and musical dynamics, see the public guides referenced in the MIDI Editor documentation. If you want to understand how Python scripts can help organize files in other contexts, the file sorting guide offers a practical example.
