September Developer Preview (Dev Preview 1.1)

Windows MIDI Services September Developer Preview

This is the official Developer Preview 1 of Windows MIDI Services. (Updated to fix access violation in previous release)

Release Notes

As we get closer to a 1.0 release of Windows MIDI Services, we're working to have everything set up in a way that better represents how this will function when distributed with Windows. In all the interim previews to date, we've distributed everything through a NuGet package plus a small installer just for the Windows service.

Expect bugs. Please report them as issues on Github so we can track them

IMPORTANT NOTE: the installer requires that you are a local administrator on your PC. It does some hacky stuff to enable WinRT Type activation of an out-of-band library. This approach is neither supported by nor recommended by Microsoft, but we're doing it here to get you a dev preview, as open source, which behaves much like it will when in-box, without having to wait until the bits are in an Insider build. Specifically, the installer calls to a C# addin which takes ownership of the protected HKLM\SOFTWARE\Microsoft\WindowsRuntime\ActivatableClassIds, adds the new class Ids, and then returns ownership back to Trusted Installer. The implication here, if that gets interrupted or otherwise fails, is that the rights on that key could be compromised and either allow anything to be registered, or nothing. It has been tested on fresh VMs and developer PCs here. It uses registraton entries built as part of the cake build. You can see the source code in \src\oob-setup\RegistryCustomActions and specifically the CustomAction.cs file.

For this reason, this is a developer-only release and is not for installation on end-user or customer machines.

Do not distribute the installer to others. Please instead provide the link to this release.

Major near-term items not yet present

Transports

• USB MIDI 2.0 class driver (so no USB devices or group terminal blocks yet)
• Virtual MIDI (including virtual CI devices)

Other Features

• Function blocks and endpoint information, including automatic discovery. This is coming soon, after I have built good tests for it.
• System-wide caching of function block / endpoint, and other information. Cache implementation is local for this preview.
• User-configurable setups
• SDK. Most of the required SDK functionality has now been incorporated into the API, so for simplicity, we're leaving the SDK out until we start adding in virtual/network/etc. transport configuration objects (which will be SDK items). Because this is not an end-user release, and this feature may be unnecessary over time, we also do not include the SDK code for checking if Windows MIDI Services is installed.

Apps

• GUI Settings app
• Recording MIDI messages to a file in the console app (this is coming soon, but didn't make the cut here)
• Additional developer features in the console app (endpoint/function block simulation, etc.)

Type Registration / Activation

• COM clsids are not registered. For COM activation during development, you may need to copy the Windows.Devices.Midi2.dll local to your project and use it as in the previous releases.

Architecture

• No Arm64 support yet. The project is Intel x64. A reminder that there will not be any x86 builds or support for 32 bit processors.

Known errors

• Although far fewer than the past, there are still a number of functions that throw E_NOTIMPL HRESULT. Here are the ones we're expecting hresults from for this release. Please report any other hresults or problems you find
  • MidiMessageReceivedEventArgs::FillBuffer
  • MidiEndpointInformationConfigurator::*
  • MidiFunctionBlockEndpointListener::*
  • MidiStreamConfigurationEndpointListener::*
  • MidiTransportInformation::*
  • MidiVirtualDeviceManager::*
  • MidiMessageBuilder::BuildSysEx7MessageFromArray
  • MidiMessageBuilder::BuildSysEx7MessageFromBuffer
  • MidiMessageBuilder::BuildSysEx8MessageFromArray
  • MidiMessageBuilder::BuildSysEx8MessageFromBuffer
  • MidiMessageBuilder::BuildMixedDataSetChunkHeaderMessage
  • MidiMessageBuilder::BuildMixedDataSetChunkDataMessage
  • MidiMessageBuilder::BuildMixedDataSetChunkDataMessageFromArray
  • MidiMessageBuilder::BuildMixedDataSetChunkDataMessageFromBuffer
  • MidiVirtualDeviceResponder::*

Other Known Issues

• The service eventually becomes unresponsive after a few hundred messages. During the runup to that, message transmit/receive times start to go up. You can see this by using the midi console and typing midi service ping --verbose --count 50 and running that repeatedly. When the service becomes unresponsive, you can restart it in the Services snap-in or through SCM. We're looking into it.

Features

Now let's get to what is here, as there is quite a bit. In general, what you're seeing is much closer to the production version that will eventually ship in-box. There's a lot of service infrastructure in there, plenty of bug fixes and hardening, cleanup of type and parameter names and more. There's more to do, but if you're not already developing with the previews, this is a great one to start with.

API

• Quite a bit in the API and service, including all the infrastructure to send and receive messages For more information, see the API documentation

Service

• Diagnostics transport which includes cross-wired BiDirectional UMP endpoints, an input and output endpoint, and a ping endpoint. These are all for developer and testing/support use as described in the API docs.
• Bug fixes for the initial issues around flooding messages without consuming any of them. Hammer this as hard as you want and let us know what you find.

Documentation

• API overview documentation in \get-started\midi-developers\app-developers\docs

NuGet Package

• C# projection is fully functional
• NuGet package with the WinMD and C# projections and works for both C# and C++.
• Package no longer contains the API implementation DLL
• Package no longer contains any SDK components

Installer

• Installs the MidiSrv Windows service, the console app, and the API
• Installs the .NET 8 Release Candidate desktop runtime (required by the apps)
• Installs the retail Visual C++ Runtime (required by the API and service)
• Registers the WinRT types for activation (this is a hack for developer purposes only. See note above)
• Tested on Windows 10 22H2 bare VMs, and on developer machines

Service

• UMP Bidirectional loopback endpoints. Sending to A->out comes back on B->in. Sending on A->in comes back on B->out
• Unidirectional loopback endpoints. Sending on the out loopback comes back on the in loopback
• Ping transport. For internal use. The console application uses this, and the MidiService API type has a static method to perform the ping in case you need to do any sort of diagnostics from within your apps.

Console app

• Combined with the loopback UMP Endpoints, useful for testing MIDI 2.0 implementations. See this thread in Discord
• Service status and ping to check that the service is installed and running
• Message sending from the command line
• Send a file of messages for automated testing
• Monitor incoming messages on a UMP endpoint
• Enumerate all UMP Endpoints
• Enumerate all bytestream (MIDI 1.0 endpoints as they appear to WinMM and older WinRT APIs.

Build process

The entire package is built using the build.cake build script in the repo.

Verifying the install

A successful install looks like this:

• Root folder %programfiles%\Windows MIDI Services
• API subfolder with Windows.Devices.Midi.dll and Windows.Devices.Midi.pri
• Service subfolder with MidiSrv.exe and the different abstraction DLLs. The abstraction DLLs are COM self-registered on install
• Tools subfolder with Console and Settings folders.
• Console folder with midi.exe and all dependencies
• Settings folder is empty but will contain the Settings GUI app in a future release.
• %PATH% updated to include the location of the MIDI Console app midi.exe
• Microsoft MIDI Service installed in Services and running (it will make a device connection sound when it starts up on Windows 11. - Investigating to see if there's anything we can do about that)
• Opening up a new console and typing midi service ping --verbose returns a positive result

Testing without any MIDI 2.0 devices

The console app provides easy ways to send and receive UMP messages. You can load up a file with valid (or valid enough) UMPs and use that to test receive functions in your app.

Here's one of the files I used for testing the feature:

# This is a test file for sending UMPs through Windows MIDI Services
# It uses auto for the field delimiter so we can have different 
# delimiters on each line

# The line above was empty. The next data line is a UMP32

0x22345678

# The messages aren't valid beyond their message type matching the number of words

0xF1345678 0x12345678 0x03263827 0x86753099
0xF2345678,0x12345678,0x86754321, 0x86753099
0xF3345678|0x12345678|       0x86754321|0x86753099

0x21345678
0x42345678 0x12341234
0x43345677 0x12341235
0x44345676 0x12341236
0x45345675 0x12341237
0x26989898

# The next two lines have different hex formatting

41345678h 12341234h
22989898h
F3345678h 12345678h 86754321h 86753099h


# The next lines have no hex formatting

41345678 12341234
22989898

# The next lines have inconsistent hex formatting

41345678 12341234
0xF2345678 12345678h 86754321 0x86753099




# bunch of empty lines above. And the file ends with a comment

We'll add additional testing support to the console app in the future. Currently under investigation are things like interactive virtual responders and message generators for Function Block requests, endpoint info requests, and more.

What Next?

We're working towards our October/November update(s) and ultimately the 1.0 release. USB is top on the list, but Network MIDI and Virtual MIDI aren't far behind. Of course, as this gets closer to moving out to non-developers, we'll invest more time in the Settings app as well.

Please develop and test with this release, report bugs, issues, and feature requests here on GitHub, and join the discussion on Discord. Thanks!