In-Box Dev Preview 5

In-Box Dev Preview 5

This version of the WinRT API has the same limitations on use as all previous releases. This is not for end-user use, nor is it to be deployed with an app, outside of limited testing, for any sort of production use. Doing so will compromise the user experience once these go in-box.

The in-boxing date is currently targeted for the last week of November (11D).

The apps included with this release all ship with a local duplicated copy of the WinRT API. Although this works, it is not permissible for your own apps unless you have explicit permission from Microsoft via email. Shipping this runtime now, without cleaning it up after the November release for every single customer may result in problems for your apps that are challenging for you to diagnose and result in a poor experience for customers.

That is also why this release is not for end-user customers who rely on their PC for making music, but is intended only for developers (and their testers) and highly technical users who know to uninstall this before the November in-box release.

Breaking Changes

• IMPORTANT. If you have ever used Network MIDI 2 previews before, you will need to manually remove your host entry from the config file. The new format requires a GUID for the host id / entry identifier, not a random string and any host where the id is not a valid GUID will fail. The current MIDI Settings app is not compatible with this Network MIDI 2.0 implementation for that reason. You must use the new app to handle Network MIDI 2.0

In addition, the connectionPolicyIpv4 key is no longer used. It will be ignored if specified.

If you prefer, you can just delete your current config file and then regenerate it using the MIDI Settings app. It's stored in %allusersprofile%\Microsoft\MIDI

Symptoms:

• The new Network MIDI Setup application doesn't open

• Your Network MIDI host isn't advertised on the network

• The MidiEndpointDeviceWatcher now passes the entire MidiEndpointDeviceInformation object in all events, just like the Legacy Device Watcher does. This was a needed breaking change because without it, there was no way to get the other information, like TransportId (thanks for finding this hole, Thomas!) because the object was already removed from the watcher's collection. Plus, this brings the two watchers in-line so they work the same way. So for each of those event args, the Id was replaced by the full object

Example:

Before:

runtimeclass MidiEndpointDeviceInformationUpdatedEventArgs
{
    [noexcept] String EndpointDeviceId {get; };
        
    [noexcept] Windows.Devices.Enumeration.DeviceInformationUpdate DeviceInformationUpdate{ get; };

    [noexcept] Boolean IsNameUpdated{ get; };
    ...

}

After:

runtimeclass MidiEndpointDeviceInformationUpdatedEventArgs
{
    [noexcept] MidiEndpointDeviceInformation RemovedDevice{ get; };

    [noexcept] Windows.Devices.Enumeration.DeviceInformationUpdate DeviceInformationUpdate{ get; };

    [noexcept] Boolean IsNameUpdated{ get; };
    ...

}

• MidiEndpointDeviceInformation and MidiLegacyPortDeviceInformation CreateFromId methods now actually validate that the correct type of Id was passed in. If you interchange them, you will get a nullptr back when you try to create the device information object. Previously, due to all the exception handling, you would receive a seemingly valid object but only filled with the properties that are in common with both.
• MidiServiceSessionConnectionInfo changed EndpointDeviceId to EndpointOrPortDeviceId because it can contain either.
• MidiReporting functions added for getting active sessions that include specific port or endpoint ids.
• MidiReporting function return types changed from IVector to IVectorView to be consistent with other read-only collections returned by other functions
• MidiEndpointDeviceIdHelper changed to MidiEndpointDeviceHelper and now includes additional validation functions for ump endpoint name, product instance id, etc.
• Basic Loopback Association Id and Loopback Association Id are now read-only on the creation config. It gets generated inside the class. This is consistent with the new network
• By default, loopback and basic loopback generate their unique identifer from the Association Id if empty
• MidiLoopbackEndpointDefinition constructors have changed due to the above. NOTE THE CHANGE IN PARAMETER ORDER.
• Same change in constructors made to MidiBasicLoopbackEndpointDefinition to keep them parallel

Other Changes

• Added IsMutedStateChanged to the MidiEndpointDeviceInformationUpdatedEventArgs type
• Added QueryAllCapabilities to the MidiServiceTransportPluginConfigManager type
• Added FindAllSessionsWithOpenEndpoint to MidiReporting so you can quickly find sessions with a UMP endpoint, or one of its associated MIDI 1.0 ports, open
• Endpoint name and Function Block name utf-8 length validation and utf-8-aware truncation in Virtual Device, Loopback, Basic Loopback, and Network MIDI API/SDK functions. In general, just better utf-8-aware string handling everywhere that pops up in the MIDI 2.0 protocol.
• The Virtual Device now has a new event and a new property so you know if there are any client apps connected to the device.

What's New

Bug fixes and test coverage

There are a number of bugs fixed as part of this work. You won't see those in the service until it releases in Windows at the end of November. However, the tests cases are all in the repo, and similar bug fixes, when appropriate, were applied to the WinRT API. Until the service components are available, you may still see some discrepancies, especially with utf-8 handling.

Significantly updated Network MIDI 2.0

Aside from there being no support for Network MIDI 2.0 Authentication modes yet (a post-1.0 release update), this is a code-complete version of Network MIDI 2.0. It passes all the protocol spec tests.

Note: there were a number of other race conditions, deadlocks, and related in the service which were discovered when completing the Network MIDI 2.0 and testing under load. Those all resulted in various types of service hangs or lockups which required killing the midisrv process to recover from. For that reason, I do not recommend this plugin be used by the general public. Like the other components here, this is a developer release for people developing products, apps, libraries, etc. There's no end-user support for this plugin.

The current MIDI Settings app is not fully compatible with the Network MIDI 2.0 implementation. Specifically, it creates entries with non-GUID identifiers.

Apps

I'm in the process of breaking the MIDI Settings up app into multiple separate apps, so that when we create an in-box Settings UI for MIDI, it can still call out to useful apps without them having to be built into the Windows Settings app. Third-party apps can also launch these apps if that is convenient to the user.

Each GUI app has the same UI customization options (Dark/Light theme, Acrylic/Mica/Solid backdrop, and an optional background color)

The equivalent functionality has been removed from the monolithic MIDI Settings app.

These are preview apps. Final names and icons TBD.

Windows MIDI Monitor

Until now, the only MIDI Monitor available with Windows MIDI Services was the console monitor. We now have a GUI monitor with a few additional features including saving the data to a file, selecting all the SysEx etc.

Full documentation and screenshots here

Windows MIDI Scratchpad

An earlier version of this was built into the last MIDI Settings release. This now provides support for both MIDI 1.0 byte format and UMP format messages.

Full documentation and screenshots here

Windows SysEx Utility

Send and receive SysEx. This is similar to the tool I have in the Store that uses the old WinRT MIDI 1.0 API, but this handles both sending and receiving, and can save your incoming files to a SysEx Library folder.

Full documentation and screenshots here

Windows Network MIDI Setup

Do not use the MIDI Settings app for Network MIDI 2.0. This new stand-alone app is compatible with the version of Network MIDI 2.0 that will be in Windows in November, and is available in preview with this release.

When you have a pending invite which needs a decision, it will show at the top of the page with the appropriate options.

Full documentation and screenshots here

Windows MIDI Loopback Setup

Like Network MIDI, loopback setup is now its own app. The app handles both styles of loopbacks if you have the transports installed and active.

Do not use the older MIDI Settings app for loopback device management. This new stand-alone app is compatible with the version of the Basic Loopback that will be in Windows in November, and is available in preview with this release. Additionally, there are features added to the MIDI 2.0-style loopbacks which will release via CFR starting in November.

Full documentation and screenshots here

Other Applications

The midi.exe console monitor has had a few options removed, specifically those related to service management. It has been ported to this new version of the API.

The MIDI Settings app is, as mentioned above, in the process of being broken up into discrete applications. It has also been ported to the new version of the API.

Installation

In case you skipped to this section, please re-read the top. These releases are for developers.

• Uninstall any other preview service plugins.
• Uninstall any previous SDK and Tools
• Install the appropriate packages for your architecture