Skip to content

Developer Preview 2

Pre-release
Pre-release
Compare
Choose a tag to compare
@Psychlist1972 Psychlist1972 released this 18 Dec 02:06
· 369 commits to main since this release
dev-preview-2
ae3b826
This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
GPG key ID: 4AEE18F83AFDEB23
Expired
Learn about vigilant mode.

NOTE: There's an update to this release which may be found here. You'll still need the driver, projections, etc. from this release, but there's a new installer.

https://github.com/microsoft/MIDI/releases/tag/dev-preview-2.1

===

We're excited to release the latest snapshot of Windows MIDI Services, including the new Windows Service, the API and projections, the console app, and the USB MIDI 2.0 driver.

This is a developer preview intended for application and device developers. This is not a customer / end-user / musician-ready release. It is not intended to be used on a production workstation or a PC you rely on. There is no end-user support for this release. Any bugs must be filed in Github for us to track.

Please do not host or distribute these files to others. Always refer them to this release page to read the instructions and download the files

We want to know about your experiences with this release. Please report (or add detail to) bugs on Github, and ask questions or have discussions on our Discord server.

Developer Preview Release Highlights

  • A mostly complete UMP-based MIDI 2.0 API with features based on your feedback and discussions on Discord, at MIDI meetings, and at readiness events
    • Multi-client by default
    • Supports outbound message scheduling by default
    • Provides much more information about connected devices
  • A Windows Service with support for pluggable transports and pluggable message processing plugins*
    • Much faster than the older MIDI infrastructure in Windows, using circular buffers in shared memory for communication between the service and API, and the service and the Windows Kernel-mode drivers.
    • Provides a centralized location for translation, enumeration, message processing and more
    • Doesn't require drivers for each type of transport. Most can be implemented as user-mode service plugins.
  • A console app useful for testing, debugging, and general inspection of the system

* the message processing dynamic loading is not yet in place, but it is in place for transports. The plugins are loaded from entries in the registry.

Key Notes

Please report any bugs, no matter how small. There are many we know about, but they are not all documented just yet. We're moving to a phase of more formal bug reporting now.

Installer

If you are running any earlier previews, please uninstall them from Settings->Apps->Installed Apps. Patch/upgrade installs are not supported.

If you are running any OS dism patches from the on-campus plug-fest and readiness event, please also remove those. The latest Windows Insider Canary build contains the OS components required.

The Windows MIDI Services Installer is not a full-featured installer. It's used only during these developer previews. Before installing a new version, you must always uninstall any previous versions through the Windows Settings app.

In addition, the installer temporarily takes over ownership of the registry location for WinRT activation entries, which is normally owned by Trusted Installer. This is not a supported scenario, but is needed for external releases from Github vs requiring your app keep the API local and include a large manifest file with activation entries. If this installer fails for some reason, it could leave you with a broken WinRT system requiring a repair or reinstall of Windows (we have not yet run into that in our testing, but it could happen). In addition, these entries get wiped out each time you upgrade from one Windows Insider Canary build to the next. We do not recommend you adopt this approach in any products you ship.

USB MIDI 2.0 Driver pre-release

The USB MIDI 2.0 driver needs to go through a lot more internal testing before we can qualify and production sign it. But we know we need solid USB device support for this API to succeed. In support of this, we also want to see it tested with as many different devices as possible. We'll do quite a bit of this ourselves and with partners, but this is where you can help. If you are a developer of a device and want to ensure your device works with the new MIDI stack and driver, please test and report any bugs here, or start discussions on Discord.

If you do not need to test USB devices under the new API, do not install this driver. There is no end-user support for this driver and it's quite likely you will have a crash or two.

We're providing the driver primarily to those actively implementing the API in their apps, or testing their own devices. If you do not need to work directly with USB MIDI devices, you can use the built-in loopback devices with the API.

  • We have an attestation-signed pre-release USB MIDI 2.0 driver developed by AmeNote. This is a build of what will be the new MIDI class driver shipped in Windows. Because it has been attestation signed, you do not need to turn on test signing, disable secure boot, or any of the other things which make self-built versions more of a challenge.
  • To use the driver, you must manually assign it to the device using "have disk". Unzip the driver files to a known location, right-click the hardware device (not the software device) in Device Manager and choose a driver from those on your PC.
  • If you unplug the device and replug it, you may need to manually pick the driver again.
  • The driver will green screen your system if you pick an incompatible device, such as the audio device from a combined audio/midi device, or a serial management endpoint of same.
  • The driver requires the latest Insider Canary build of Windows 11 for our USB stack updates which have not yet been serviced to mainstream supported Windows 11 and Windows 10 releases. Only the Canary releases will work here. For more information on the Windows Insider program, check the documentation here.
  • The driver currently supports only a single device at a time. #166
  • The driver (and service plumbing) do not currently support the classic MIDI APIs on Windows.
  • Please report any new bugs with as much detail as possible. If you are trying a MIDI device and found any failures or bugs, it would be helpful if you could also provide a copy of all the device header information using a tool like the Thesycon descriptor dumper or USB Device Tree Viewer. The latter has issues reporting all string properties, however, often saying the device is in a low power state.
  • The password for the USB MIDI zip file is preview-2. The password is there to help ensure everyone installing it has read this section. :)

image

image

image

image

Upgrading your Windows Version

  • If you upgrade to a new version of Windows (including to a new Canary build) you'll need to uninstall and then reinstall Windows MIDI Services and the USB driver.

Features and Other Notes

Service-based Message Scheduling

  • Outgoing MIDI messages can now be scheduled through the service.
  • Use a timestamp of 0 to bypass scheduling completely. You can also use a timestamp of MidiClock::Now() to effectively bypass scheduling. 0 is the better choice, however as it short-circuits the rest of the scheduler, and is also consistent with other operating systems.
  • Fix: Originally, messages with the same timestamp > now had indeterminate send order. That has been fixed so the order is retained.
  • Don't queue thousands of messages. Performance degrades based on outgoing scheduler queue size. This is unlikely to change.

image

Enumeration

  • It can be a challenge to get all the custom properties using our standard enumeration objects
    • Also a lot of work just to find the parent device. We've handled that.
    • These classes wrap the standard enumeration types
  • New support for the MidiEndpointDeviceInformation class and metadata. See sample.
  • New support for the MidiEndpointDeviceWatcher class for add/update/remove notification. See sample. This is the preferred way for you to enumerate endpoints, because it will notify you when they are added or removed, and when properties (like function blocks) change.

image

Group Terminal Blocks

  • The new USB driver now supplies Group Terminal Blocks from MIDI 2.0 devices. These are surfaced through the MidiEndpointDeviceInformation class and also through the console app as well using midi endpoint properties
  • The new USB driver also creates group terminal blocks for USB MIDI 1.0 devices. The returned information should contain the correct names if you provide Pin names in your USB headers

image

A classic byte-stream MIDI 1.0 device. The names of the two virtual Group Terminal Blocks come from the iJack descriptors.

image

Listeners

Client API Endpoint Listeners now in place

  • MidiChannelEndpointListener : Receive messages only for a group and channel
  • MidiGroupEndpointListener : Receive messages only for a group
  • MidiMessageTypeEndpointListener : Receive messages only for certain message types

Virtual Devices

  • MidiVirtualDevice Not yet implemented but coming soon.
  • This will be the function block / CI / endpoint information responder for your app to use when using app to app MIDI as a "device"

Message Translation

  • The USB driver translates to/from MIDI 1.0 byte stream for those devices.
  • MidiMessageTranslator functions in the API are not yet fully implemented

Protocol Negotiation

  • Being moved to service. Not in place in this release. As a result, the protocol information in the MidiEndpointDeviceInformation object is not complete.

Function Block and Endpoint information Capture

  • This is being moved to service and is not in place in this release.
  • The function block and endpoint information will be surfaced through the MidiEndpointDeviceInformation object just like the Group Terminal Block info. No need for you to parse those Type F messages yourself, although you can if you want. But today, that information is not in place.

Configuration File

  • Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows MIDI Services CurrentConfig is the name of the file, located in \ProgramData\Microsoft\MIDI, which contains the runtime configuration. This is where device renaming is done, persistent virtual devices are set up, etc. The MIDI Settings application will write / update this file on your behalf. The installer sets the appropriate permissions for this folder.
  • We'll provide more information on customizing this in the future. Some initial information here

API Projections

This release includes projections for:

  • C++ : Either use the generated header file, or use the cppwinrt command-line tool to process the winmd and generate the header
  • C# : We have a dedicated projection in the NuGet package. We use the same NuGet package for the Console and Settings apps.
  • Electron: This is experimental, but we have a projection built using a customized version of NodeRT. If you are using this projection, please do let us know on Discord.

Note that Rust projections and documentation are not yet available. If you are building an actual MIDI application using Rust, please do let me know on Discord and can prioritize the work.

Tools

MIDI Settings App

  • This release does not include the settings app. It has been removed for now. Once we have the infrastructure to support changes to the MIDI graph at runtime, we'll implement that in the settings app. If you compile the settings app yourself, please note that it will reference old projections and libs, so will not compile or work immediately.

MIDI Console App

  • The console app has had significant updates and is one of the primary tools used by developers to test devices.
  • More documentation here

image

Documentation and Samples

  • Samples and documentation may be found in the get-started folder at the root of this repo. Currently, the C++ samples show more of the features than the other languages.

Please try it out

Please do try out this release, and build your applications against it. We're preparing to go in-box in 2024, and once that happens, it becomes quite difficult for us to make any breaking changes to the API, Service, or Driver. We need your feedback now!

Remember to file bugs here on Github, and to join us on the Discord server if you have questions or want to further discuss anything related to this project.

Build Assets

  • cpp-bare.zip: this is for developers who want to reference the .winmd using the cppwinrt tool (or another tool), or who wish to use the pre-generated projection header file.
  • electron-nodejs.zip: Experimental Electron/node.js projection
  • USBMIDI2_10.0.1.3.zip: Pre-release USB MIDI 2.0 and 1.0 driver
  • *.nupkg: Nuget package for C++/WinRT and C#/WinRT projects, typically using Visual Studio.
  • *.exe: Service, API, tools installer.

Thank you for joining us on this journey this year. Whatever holiday or holidays you celebrate, we hope you have a great one! 🎅❄️🎄🕎🎆

Assets 7