midi2-tools

Small, focused command-line tools for MIDI 2.0 — for reading, converting, and inspecting Universal MIDI Packet (UMP) streams and the MIDI Clip File format (.midi2 / SMF2CLIP). Each tool does one thing well and works purely on bytes: no audio, no drivers, no hardware required.

Status: early days. The format support is intentionally focused (see Scope); the file/wire output is verified byte-for-byte against the midi2 reference crate.

Crates

Crate	Kind	What it does
midi2-core	lib	SMF2CLIP read/write + UMP framing and the spec's min-center-max scaling.
midi2-inspector	bin	Pretty-print a .midi2 Clip File's UMP stream, decoding high-res (16/32-bit) values.
midi2-convert	bin	Convert .mid ↔ .midi2, upscaling 7-bit → 16/32-bit and back.

Typed UMP message decode/encode is provided by the midi2 crate (the midi2-dev project); midly handles the SMF 1.0 layer in midi2-convert. midi2-core owns only what midi2 does not: the SMF2CLIP file container, UMP stream framing, and the 7↔16/32-bit resolution scaling.

Install

# Build the binaries (target/release/midi2-inspector, midi2-convert)
cargo build --release

# …or install them onto your PATH
cargo install --path crates/midi2-inspector
cargo install --path crates/midi2-convert

Usage

# .mid -> .midi2 (upscale 7-bit values to 16/32-bit)
midi2-convert from-smf song.mid song.midi2

# Inspect the result (human view, or CSV for scripting)
midi2-inspector dump song.midi2
midi2-inspector dump --csv song.midi2

# .midi2 -> .mid (downscale back to 7-bit for MIDI 1.0 fallback)
midi2-convert to-smf song.midi2 song.back.mid

(During development, swap the binary for cargo run -p midi2-convert --, etc.)

from-smf | to-smf round-trips 7-bit values exactly: the upscale lands the original value in the high bits and the downscale is its exact inverse.

Example inspector output:

SMF2CLIP  (MIDI Clip File)  10 packets
  t=0         Start of Clip
  t=0         DCTPQ            ticks_per_quarter=480
  t=0         grp=0 ch=0  Program Change   program=42
  t=0         grp=0 ch=0  Control Change   cc=74 val=0xFFFFFFFF (32-bit)
  t=0         grp=0 ch=0  Note On          note=60 vel=0xC924 (16-bit) attr=none
  t=480       grp=0 ch=0  Note Off         note=60 vel=0x0000 (16-bit) attr=none
  t=480       End of Clip

Scope

midi2-convert currently maps the MIDI 1.0 channel-voice messages (note on/off, poly/channel pressure, control change, program change, pitch bend) and tempo (via Flex Data Set Tempo). Messages with no equivalent in the target format are reported and skipped rather than guessed at. midi2-inspector decodes the full range of UMP message types via the midi2 crate.

Development

CI runs formatting, clippy (as -D warnings), tests, and a docs build. To match it locally:

cargo fmt --all --check
cargo clippy --workspace --all-targets
cargo test --workspace

See CONTRIBUTING.md.

References

• MIDI Clip File spec: M2-116-U v1.0
• UMP & MIDI 2.0 Protocol spec — defines the scaling rules
• Cross-check implementation: ktmidi

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option. Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.