Question: Is there a unified MIDI 1.0 + MIDI 2.0 message interface?

[shemeshg]

Hi, I’m a bit new to libremidi, so apologies if I’m misunderstanding something.

I’ve noticed that libremidi allows listening either to libremidi::message (MIDI 1.0) or to UMP (MIDI 2.0). For MIDI 1.0 messages, I can check things like:

if (message.get_message_type() == libremidi::message_type::NOTE_ON) {
    ...
}

However, I’m running into two issues:

1. There doesn’t seem to be a seamless translation from MIDI 1.0 to MIDI 2.0, exposed through a common interface.
2. libremidi::message doesn’t provide helpers like get_data_1(), so I have to manually index the raw data bytes.

Because Microsoft’s new Windows MIDI 2.0 API exposes both MIDI 1.0 and MIDI 2.0 through a unified interface, I expected libremidi to have something similar — a single abstraction where I can treat both MIDI 1.0 and MIDI 2.0 messages the same way, without manually branching or accessing raw bytes.

On the other hand, I also understand that having a unified interface is not trivial. A common abstraction would require agreeing on things like value precision (e.g., pitch‑bend resolution) and normalizing multi‑byte MIDI 1.0 constructs such as 14‑bit CC or NRPN. In MIDI 2.0 these are already represented as single UMP packets with well‑defined 16‑bit or 32‑bit resolution, so the mapping is not always 1:1. Still, this is exactly why I expected a higher‑level API that hides these differences and exposes a consistent event model regardless of whether the source is MIDI 1.0 or MIDI 2.0.

My question:
Is there an existing unified message abstraction in libremidi that I missed, or is this something that is not currently supported?

Thanks!

reference: My test function for MIDI1 only

    void testMidi() override
    {
        std::cout << "\ninputs:\n";
        libremidi::observer obs;
        for (const libremidi::input_port &port : obs.get_input_ports())
        {
            std::cout << port.display_name << "\n";
        }
        std::cout << "\noutputs:\n";
        for (const libremidi::output_port &port : obs.get_output_ports())
        {
            std::cout << port.display_name << "\n";
        }
        auto my_callback = [](const libremidi::message &message)
        {
            std::cerr << message.bytes.size() << "\n";
            std::cerr << message.timestamp << "\n";

            if (message.get_message_type() == libremidi::message_type::NOTE_ON)
            {
                std::cerr << "Notes ON\n";
            }
            else if (message.get_message_type() == libremidi::message_type::NOTE_OFF)
            {
                std::cerr << "Notes OFF\n";
            }
            else if (message.get_message_type() == libremidi::message_type::CONTROL_CHANGE)
            {
                std::cerr << "Control change\n";
            }
        };

        libremidi::midi_in midi{
            libremidi::input_configuration{.on_message = my_callback}};
        midi.open_port(obs.get_input_ports()[1]);
        std::string userInput;
        std::getline(std::cin, userInput);
    }

[jcelerier]

hello!
The way libremidi works is, it lets you the choice of the "unified interface", which can be either MIDI 1 bytes or MIDI 2 UMPs. For new code there is no reason to not use MIDI 2 UMPs all the time as they entirely supersede MIDI 1. If you create a midi 2 configuration (e.g. set .on_ump instead of .on_message) then you will get MIDI 2 UMP even if the hardware is MIDI 1. Likewise, you can always send UMP to a midi_out object and it will be converted to MIDI 1 if it's a MIDI 1 device (or conversely).

In short: there is seamless translation, it just happens behind the scene - in libremidi's implementation if the backend does not support it, but otherwise it's the operating system API which is actually in charge of this automatic translation, all of CoreMIDI on macOS, Windows MIDI Services on Win32 and ALSA on Linux do it already.

[shemeshg]

Thanks for the suggestion — I tried switching to UMP as recommended.
Here’s the minimal test code I used:

void testMidi() override
{
    std::cout << "\ninputs:\n";
    libremidi::observer obs;
    for (const libremidi::input_port &port : obs.get_input_ports())
        std::cout << port.display_name << "\n";

    std::cout << "\noutputs:\n";
    for (const libremidi::output_port &port : obs.get_output_ports())
        std::cout << port.display_name << "\n";

    auto my_callback = [](const libremidi::ump &message)
    {
        std::cerr << message.size() << "\n";
        std::cerr << message.timestamp << "\n";
    };

    libremidi::midi_in midi{
        libremidi::ump_input_configuration{.on_message = my_callback}};

    midi.open_port(obs.get_input_ports()[1]);

    std::string userInput;
    std::getline(std::cin, userInput);
}

Issue 1 — No messages arrive

With this setup, unlike my original MIDI 1.0 callback, nothing is printed at all.
So either I’m missing a configuration step, or the port I’m opening is not producing the UMP of the MIDI1 packets.

Issue 2 — No way to check Note On / Note Off

In the UMP API I noticed that the old:

message.get_message_type()

is now just:

message.message_type()

But the enum only contains high‑level UMP group types:

enum class message_type {
    UTILITY,
    SYSTEM,
    MIDI_1_CHANNEL,
    SYSEX7,
    MIDI_2_CHANNEL,
    SYSEX8_MDS,
};

I couldn’t find an equivalent way to check whether a message is Note On, Note Off, CC, etc.
If I receive a MIDI_1_CHANNEL or MIDI_2_CHANNEL packet, I don’t see how to inspect the actual event type inside it.

Question about the state machine / collector

Based on the unit test here:
https://github.com/celtera/libremidi/blob/master/tests/unit/midi_stream_decoder.cpp
I’m wondering whether I’m also supposed to manually run something like:

midi1_collector c;
auto sm = c.make_state_machine();
sm.on_bytes(bytes, 0);

Is this required when using the UMP callback as well?
Or is the UMP path supposed to deliver already‑decoded packets without needing a separate state machine or collector?
Is this mandatory for MIDI1?

I’m also wondering whether libremidi automatically switch on the midi1_collector logic for things like NRPN, and what happens with 14‑bit CC messages and how do I defined that. Do I need to manually run a collector/state machine for these cases, or is this already taken care of internally especially when using the UMP callback path?

---

If there’s a recommended way to:

1. ensure UMP input actually fires callbacks, and
2. decode UMP channel messages (e.g., detect Note On/Off),

[jcelerier]

Your code is correct and should yield messages. Which platform / OS / midi device are you using? It's most likely a bug in the library somewhere.

midi1_collector c;
auto sm = c.make_state_machine();
sm.on_bytes(bytes, 0);

this is what the library already does internally, you don't need to worry about it. It's only been made available externally for the case where you want to reimplement your own slim midi parsing on say, Arduino

[jcelerier]

decode UMP channel messages (e.g., detect Note On/Off),

the recommendation is to use either cmidi2 (simple, one header, integrated in libremidi) or ni-midi2 (more complete but quite heavier dependency). Both have fairly complete MIDI 2 parsing and can directly interoperate with libremidi (see the examples)

[jcelerier]

for the conversion, maybe you can check in the debugger that on construction of the midi_in object you're indeed going through one of those:

https://github.com/celtera/libremidi/blob/master/include/libremidi/midi_in.cpp#L13-L60

[shemeshg]

system debug info

% system_profiler SPSoftwareDataType
Software:

    System Software Overview:

      System Version: macOS 26.5.1 (25F80)
      Kernel Version: Darwin 25.5.0
      Boot Volume: Macintosh HD
      Boot Mode: Normal
      Computer Name: std1013
      User Name: macos user (macos)
      Secure Virtual Memory: Enabled
      System Integrity Protection: Enabled
      Time since boot: 20 days, 22 hours, 2 minutes

% clang --version
Apple clang version 21.0.0 (clang-2100.1.1.101)
Target: arm64-apple-darwin25.5.0
Thread model: posix
InstalledDir: /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin
% xcrun --find clang
/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/clang
% cmake --version
cmake version 4.3.4

CMake suite maintained and supported by Kitware (kitware.com/cmake).
% xcode-select -p
/Applications/Xcode.app/Contents/Developer

Midi 1 run debug info

all working as expected

inputs:
Scarlett 2i4 USB
Launch Control XL
Launch Control XL HUI

outputs:
Scarlett 2i4 USB
Launch Control XL
Launch Control XL HUI

1806472667851416
Notes ON

1806473146847500
Notes OFF

CMake installed with

on main cmake

set(CMAKE_CXX_STANDARD 23)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF)

at the add_subdirectory cmake

include(FetchContent)
FetchContent_Declare(
    libremidi
    GIT_REPOSITORY https://github.com/celtera/libremidi
    GIT_TAG        master
)
FetchContent_MakeAvailable(libremidi)
target_link_libraries(MyLib PRIVATE libremidi)

midi2 run debug info

/Volumes/RAM_Disk_8G/FlightgearMidi/program-changer/build/program-changer

inputs:
Scarlett 2i4 USB
Launch Control XL
Launch Control XL HUI

outputs:
Scarlett 2i4 USB
Launch Control XL
Launch Control XL HUI
libc++abi: terminating due to uncaught exception of type stdx::thrown_dynamic_exception: std::exception
['I', 'n', 'v', 'a', 'l', 'i', 'd', ' ', 'a', 'r', 'g', 'u', 'm', 'e', 'n', 't']zsh: abort      /Volumes/RAM_Disk_8G/FlightgearMidi/program-changer/build/program-changer

for

    void testMidi() override
    {
        std::cout << "\ninputs:\n";
        libremidi::observer obs;
        for (const libremidi::input_port &port : obs.get_input_ports())
            std::cout << port.display_name << "\n";

        std::cout << "\noutputs:\n";
        for (const libremidi::output_port &port : obs.get_output_ports())
            std::cout << port.display_name << "\n";

        auto my_callback = [](const libremidi::ump &message)
        {
            std::cerr << message.size() << "\n";
            std::cerr << message.timestamp << "\n";
        };

        libremidi::midi_in midi{
            libremidi::ump_input_configuration{.on_message = my_callback}};

        auto err = midi.open_port(obs.get_input_ports()[1]);

        if (err == stdx::error{})
        {
            std::cout << "no error\n";
        }
        else
        {
            // Print the message from the error object
            std::print("{}",  err.message());
            err.throw_exception();
        }

        std::string userInput;
        std::getline(std::cin, userInput);
    }