Developer Preview 5

Hi Everyone. We're continuing our march to production with Developer Preview 5!

(Updated Windows.Devices.Midi2 zip below with missing header files)
Updated driver because the initial release went out with an old driver version.

In preparation for our next API review and for moving into production, we've looked at every aspect of the API and evaluated it for completeness, usability, and necessity and also rolled in a lot of the feedback we've had over the past 6 months.

As a result, there are a number of changes in this release. In our testing, all applications built against previous versions of the API will need to be recompiled against the new metadata, and may require some minor code changes. Note that changes in class signatures does result in changes to the generated interface Ids.

Please do file bugs! But please also check the current outstanding issues before doing so. Feel free to add more data or comments to existing issues if you find you've run across the same problem.

Documentation

In prep for production and for our internal API review, I've started fleshing out the documentation. Work-in-progress docs are currently using GitHub pages and are now published at https://aka.ms/midi . When we have an official MS Learn section for Windows.Devices.Midi2, we'll repoint the aka.ms to that.

NOTE: Some of the docs, especially those about the configuration file format, need to be updated and are no longer valid. We're catching up with these as soon as possible.

Important Method Signature Changes

Our internal API validation required that any out or in/out parameters be the last items in a parameter list in any function. For that reason, all the MidiMessageReceivedEventArgs methods which would fill an array, buffer, or struct, had to be modified so the array/buffer/struct was the last item in the parameter list. To keep things consistent, all the Send message methods were changed to operate the same way.

Additionally, any method which took an IVector or IVectorView as a parameter has been changed to take an IIterable to be consistent with our API guidelines and automated validation.

Finally, for the same reasons, several of the "Flags" enums were renamed to be plural and remove the word "Flags" from the enum.

API and Service Highlights

App-to-app and Loopback MIDI

• App to app MIDI devices can now be created 100% through the API, from an application. See the app-to-app MIDI C# example for details. This version of app-to-app MIDI enables your application to appear as a full MIDI device, with endpoint information, function blocks, and more.
  • https://microsoft.github.io/MIDI/endpoints/virtual-device-app.html
• Simple loopback MIDI now available through the configuration file and through the API
  • https://microsoft.github.io/MIDI/endpoints/virtual-loopback.html

Active Sessions

• The service now tracks active sessions and displays the name your apps are providing when creating a new session. The console midi enum sessions command has been added to report on that information.

Installed Transports

• The service now reports on installed transport plugins. The console midi enum transports (with optional --verbose) lists all the transports currently enabled in the service.

Example with --verbose

This information is also reported by the mididmp utility.

MIDI Service Control

• The console midi service command has been updated to now have sub-commands to start/stop/restart the service. These must be run from a command prompt running as administrator midi service start, midi service stop, and midi service restart are the new commands.

MUID

• The MidiUniqueId class now has methods for generating a new random MUID, parsing the MUID from bytes or a single 32 bit integer, and more. This class is useful when you are working with MIDI CI.

Connection Updates including Multi-message sending

• Refactored the endpoint connection settings, resulting in different signatures to the MidiSession methods to create a new connection.
• MidiEndpointConnection no longer implements IClosable / IDisposable and no longer has a Close or Dispose method. Always close the connection through the related session. This avoids having dead connections in the session collection. The MidiSession class still implements these interfaces.
• Added to MidiEndpointConnection the SendMultipleMessagesWordList and SendMultipleMessagesWordArray to send a vector/collection/list/array of words. Currently, the code behind this will pick this apart into multiple discrete messages, and send all with the same specified timestamp. This is the only method which will accept multiple UMPs and send them all. We're including it for ease of use and for potential future optimization for sending more than one message at a time.
• At the same time, the methods which send only a single message have been renamed to new names in the form SendSingleXXXX.

Here are some informal speed tests. The code that generated this output is in the samples section. This is going to vary a bit from time to time as we adjust timings and optimize code.

Full thread: https://discord.com/channels/980245825202552942/1208186499993178192

Message Scheduling

Now that we have other message sending bugs resolved, I've re-enabled message scheduling.

Message Scheduling is still due for an update to ensure that there's only one instance per device, so you may run into scheduling strangeness like before if you have multiple connections open to the same device, each sending scheduled messages.

Please file bugs here if you see problems.

Message updates

• The MidiStreamMessageBuilder API functions now take and return IMidiUniversalPacket instead of MidiMessage128. This makes them more usable from other functions
• The IMidiUniversalPacket type now has functions to return all the words either as a new vector, or insert them into an existing vector
• Removed the MidiMessageTranslator which was not yet implemented. Other libraries already do a good job of upscaling/downscaling MIDI 1 <> MIDI 2 messages.

MIDI Clock Update

• The MidiClock class now includes a TimestampConstantSendImmediately property. You can still just use 0 in place of the timestamp when sending messages if you want to bypass the scheduler, but this property makes that value more obvious. It's a property because WinRT doesn't support shipping defines or constants any other way.
• MidiClock also has a few more conversion methods to make it easier to handle the time calculations from any language

Enumeration Updates

• Added additional sort order options to MidiEndpointDeviceInformationSortOrder so if you want to sort by the transport (for example, all network MIDI devices followed by all virtual devices) you can do that.
• Added various "LastUpdateTime" properties to the device information object for the in-protocol discovered properties like function blocks, endpoint information, etc.
• Renamed some of the enumerated device properties so they better represent their source
• The MidiEndpointDeviceWatcher events have all been normalized to send XXXXEventArgs types as the second parameter. This was the result of automated API review.
• There's a bug in the driver right now so we don't yet pull the iSerialNumber property. Next release for that.

Apps and Tools

Console

• The console has generally kept pace with the API changes and so surfaces new features like session reporting, transport enumeration, and more. There's quite a bit of new functionality in there.

MIDI Dump Utility

• The install now includes the mididmp.exe utility. This will be ship in Windows with the API. It's a lightweight bare-bones command-line program which outputs the devices, the midi clock information, and the results of a service ping test. Intention here is for this to be available for use by technical support personnel and for desktop applications as per original AMEI request. Output is plain text with machine-readable tokens because most apps will redirect output to a file or otherwise capture the output. Here's a screen shot from an early revision of the app:

This is a C++/WinRT console app which uses the API. Source here:
mididmp.exe source

The utility is in the app path, so to use it from your own applications, just ShellExecute or your other favorite way to launch other processes, and capture the output.

Work-in-Progress MIDI Settings App

A very early build of the MIDI Settings app is also included with this release. There's a lot in here which is not yet wired up, but you can view endpoint devices, sessions, transports, etc. Expect random errors and more.

The settings app was built using .NET 8, WinUI 3, and the Windows App SDK. The installer package installs all of those components on the target PC. Note that .NET 8 is also used for the MIDI Console app.

Installed Transports

Enumerated Endpoints

Endpoint Details

Note that you cannot yet change endpoint properties through the app. That will be coming in a future update.

The configuration file which created the custom properties for those MIDI 2.0 devices includes this section. Note that the "match" approach here is likely to change for the next release, so please don't get too attached to the file syntax :)

    "endpointTransportPluginSettings":
    {
        "{26FA740D-469C-4D33-BEB1-3885DE7D6DF1}":
        {
            "_comment": "KS MIDI (USB etc.)",
            "update":
            [
                {
                    "match":
                    {
                        "SWD": "\\\\?\\swd#midisrv#midiu_ks_bidi_6051189816177518400_outpin.0_inpin.2#{e7cce071-3c03-423f-88d3-f1045d02552b}"
                    },
                    "_comment" : "Roland A88 mk2",
                    "userSuppliedName" : "Pete's A88",
                    "userSuppliedDescription" : "The A88 is the giant MIDI 2.0 piano-action keyboard here in my studio."
                },
                {
                    "match":
                    {
                        "SWD": "\\\\?\\swd#midisrv#midiu_ks_bidi_14963949922281886459_outpin.0_inpin.2#{e7cce071-3c03-423f-88d3-f1045d02552b}"
                    },
                    "_comment" : "Waldorf Iridium",
                    "userSuppliedName" : "The Amazing Iridium"
                }
            ]
        }

This is a very rough and incomplete version, released just to get people thinking. I'm happy to track feature requests on this in GitHub, so please file those. I won't stop anyone from filing bugs, but those will mostly be noise right now as the app isn't really in a state for actual testing. That said, if you found a bug you think is very important and likely to be missed, please feel free file it here on GitHub.

For this app in-particular, given that it is an early preview, I ask that you enter the bugs and feature requests into GitHub. We won't be logging things that are discussed on Discord.

Important Changes and Breaking Changes

The API has been developed iteratively with partners. In preparation for final API review and release, we've been removing prototypes and idea code which will not get implemented in v1 of the API. For example, some connection options only made sense when endpoint discovery and protocol negotiation was happening on the client instead of in the service. This also resulted in cleaning up other method signatures to keep features in line.

In addition, we've been cleaning up the API to fix inconsistencies in naming, and anything which would fail our automated API checker (rtcop) or the human API review.

• The MessageProcessingPlugins vector in the MidiEndpointConnection class is now a read-only view. To add or remove plugins, use the new AddMessageProcessingPlugin and RemoveMessageProcessingPlugin methods. This ensures plugins added after the endpoint has been opened are properly initialized and connected.
• In most cases where a function took an IVector as a parameter, they have been changed to take IIterable instead.
• In functions where we take an array or buffer parameter, that is now the last parameter in the formal list. That's an API requirement from our review team. To keep things consistent, all functions with the similar pattern have been changed to match this, even though it was only required in a few cases.
• Various other types have had methods and properties added or removed as part of cleanup.

Others

Removed most debug output. To trace and diagnose errors, please use the trace logging ETL process. There's quite a bit more tracelogging code in place to help us debug issues.

Combined USB MIDI 1.0 and USB MIDI 2.0 Driver

We have a new attestation-signed version of the MIDI 2 USB driver! As this is shipped out of band for development purposes, you still need to manually assign it to the correct devices.

**Assigning the driver to an incorrect device in device manager (for example, the USB Audio 2.0 endpoint of a multi-function device) will green screen/bugcheck your PC. We don't recommend doing this :) **

Let us know if you run into any bugchecks (and please be specific) or other driver issues. We really want to test this with as many different PC configurations, apps, and devices as possible before we put it in-box.

Driver Highlights

• Now supports connecting multiple devices at a time!
• Fixed issue with returning corrupted group terminal blocks for some devices
• Fixed issue where power management events would green screen
• Supports both MIDI 1.0 (byte stream) and MIDI 2.0 (UMP) devices

There are still some known limitations with the driver. Refer to the issues list in this repo.

How to install the development driver

The driver is attestation-signed, but it is not yet a class driver because it's not distributed with Windows. Because of that, you need to manually assign the driver to the USB device. As in the past, if you assign it to a non-compatible device, you will bugcheck your PC.

REMINDER: This is a development driver, not for non-developer customer use. Anyone who wants to try it is welcome to, but there's no compatibility with older APIs with this driver. That means none of your existing DAWs or other MIDI-using apps will work with this.

In device manager, right-click the correct device (see notes above about what happens when you choose an incompatible device)

In the end, you should see USBMidi2-ACX as the assigned driver for the device.

Note: It appears that Windows Insider Canary is no longer required for the driver. It is working on the recent Windows Insider Developer channel builds for Windows 11.

Files

All files are x64 architecture. No Arm64 yet from this build system.

Please completely uninstall (through Settings->Apps->Installed apps) any previous versions before installing this

• USBMIDI2_10.0.1.4.zip: This is the attestation-signed USB MIDI 2.0 driver. Copy this to an easily-found location on your PC so you can reference it when you assign the driver to devices
• Windows.MIDI.Services.Developer.Preview.5.x64.1.0.24066.2126.exe: Required install package for Windows MIDI Services.
• Windows.Devices.Midi2.zip: Bare metadata and headers for C++ developers or anyone who is generating their own projection.
• Windows.Devices.Midi2.1.0.0-preview.5-0185.nupkg: NuGet package projection for C++ and C# developers. Copy to a local location on your PC and tell NuGet package manager that is a local source.
• electron-projection-dp5.zip: As in the past, the electron projection is "best effort" because we don't really do any electron work here. If you plan to use it and run into any problems, please contact me on Discord or email.

Please try out this build with your products and continue with your implementations. We're eager to have applications supporting Windows MIDI Services upon its public release later this year, and we know our shared customers are as well!