Dev Preview 8
Pre-release
Welcome to DP8!
The purpose of this preview release is to enable developers to code against the new centralized SDK. We'll be demonstrating some of these apps at the NAMM Show in January, as well as a preview of Network MIDI 2.0.
This is not an end-user-ready release.
Installation Notes
Always completely uninstall any previous Developer Preview releases before upgrading to a new release, and also before upgrading Windows to a new Canary Insider build.
Windows MIDI Services Dev Previews require Windows 11 Insider Developer channel or Windows 11 Insider Canary channel releases. Canary releases will be the first to receive the in-box builds. You can learn more about Windows Insider releases here
https://www.microsoft.com/windowsinsider/
You can enable Windows Insider releases on your non-production PC via Settings > Windows Update > Windows Insider Program
If you are running a recent Windows Insider Canary build, that build already ships with an older version of Windows MIDI Services pre-installed. Because it is an in-box release, the registry keys which it uses are protected and so our install this time around is a little more complex.
⚠️ IMPORTANT PRE-INSTALLATION STEPS ⚠️
To install a developer preview, we must unprotect those registry keys. If you do not do this, registering the service components will either fail with errors in the installation (most common outcome), or will fail silently.
- There's a new script which helps developers install the DP in a system which has Windows MIDI Services in-box installed. Run this before running the installer. The zip file below has the ones from the time of this build. You can always get the latest from:
https://github.com/microsoft/MIDI/tree/main/src/dev-tools/reg-helpers
Run list-reg.cmd to see the current state of the system. If it returns back components with locations in your System32 folder, then you will need to run the dev-prep.cmd to take ownership of those registry entries before installing DP8. For example, this shows System32 (pre-installed) Insider components.
This shows the successful output from the dev-prep cmd file, which means you can then run the installers.
After running the installers, this output of list-reg shows the DP8 components installed and registered. Note that the file locations have changed from System32 to Program Files. Also note that the lack of entry for Network MIDI 2.0 is normal at the moment.
Notes:
- The scripts require Windows PowerShell 7.0 or higher, available here: https://learn.microsoft.com/powershell/scripting/install/installing-powershell-on-windows
- You must run the scripts from an Administrator (elevated) command prompt
- You must have script execution enabled (Settings > System > For Developers > PowerShell). Optionally, this can be done from an elevated PowerShell console using the
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachinecommand as described here https://learn.microsoft.com/powershell/module/microsoft.powershell.security/set-executionpolicy .
When using dev builds with the Windows Insider Canary builds at this stage, there are several things to be aware of:
- You may see duplicate entries due to both
MidiSrvandAudioEndpointBuilderenumerating endpoints - It's a bit of a lottery as to which
WinMMports go throughMidiSrvvs the older stack. This can result in problems with WinMM multi-client and more. - The existing bug with the older MIDI 1.0 class driver and power management is still there. When you assign a device to use the new MIDI 2 UMP class driver, and the device was previously assigned the generic MIDI 1.0 class driver, you need to unplug and replug the device quickly to avoid a potential green screen (BSOD) due to a power management bug in the old driver.
Those issues are all fixed, and we've provided a small number of partners with internal tools to enable the fixes, but we cannot distribute those broadly at this time. Instead, we're working to accelerate getting to a point where we can turn Windows MIDI Services on by default, along with these fixes and the new class driver, in Canary builds around the time of the NAMM show so that everyone may benefit and so customers can test as well.
Installer Versions
During installation, you may notice different versions between the two installers. That is fine. It's just a mismatch between file name and internal metadata when a file doesn't need to be rebuilt.
App SDK
Centralized Installation
In previous releases, apps had to ship the SDK implementation in the application's folder, and also had to include a manifest file which listed all the WinRT SDK types.
DP8 is the first version with the new centralized SDK. Desktop applications should no longer ship the Microsoft.Windows.Devices.Midi2.dll, the initialization DLL, or any MIDI activation manifest entries. Please verify that your own applications are following this new approach.
- The NuGet package no longer includes the WinRT implementation DLLs
- Under the Build folder of the NuGet package, the .hpp file for C++ apps replaces the previous Initialization binary. The C++ samples have been updated to use this. This is how you initialize the SDK.
- The aka.ms for downloading the latest installer is not yet active
- The installers are not yet signed
The SDK now includes a MidiEndpointDevicePropertyHelper class which is a convenience for identifying Windows MIDI Services properties. This is used in the console as described below.
Endpoint Connection Creation Hardening
In previous versions, you could pass any string to the session function to create a new connection, and it would happily return a connection object for you to later (fail to) open. This was brought up in issue #429.
The SDK code to create a new endpoint connection now pre-validates the supplied endpoint id by:
- Ensuring it represents a Windows MIDI Services MIDI device
- Checking to see if the MIDI streaming interface on the device has been activated.
If either check fails, the function returns nullptr. Of course, in between the time the connection is created and opened, the endpoint could go away. In that case, the call to Open will return false.
Additionally, the code to create a MidiEndpointDeviceInformation object by Id now does the same type of validation.
URLs
- Changed SDK Method
InitializeSdkRuntimetoInitializeDesktopAppSdkRuntimeto avoid any confusion when using the SDK from packaged apps in the future, where it does not use the initializer - Removed
GetLatestSettingsAppReleaseInstallerUriandGetLatestConsoleAppReleaseInstallerUri. Instead, everything that is not in-box will be provided through a single installer atGetLatestDesktopAppSdkRuntimeReleaseInstallerUri - Application developers are permitted to include the latest supported release version of the installer with their application. However, apps must not uninstall newer versions already installed on the PC. By default, the installer will not overwrite newer versions. When uninstalling your app, do not uninstall the SDK Runtime - mark it as permanent.
- To download the SDK runtime, please use the URLs returned by the Initialization methods, when they are activated (before 1.0 release)
Type Changes
- Fixed some static SDK types which had
[default_interface]incorrectly specified, and some which didn't have the static keyword applied to the runtimeclass in the IDL. This changed the clsid property for a handful of classes - Function blocks and most other locations which previously used a
uint8_tGroup Index now use theMidiGrouptype.
Known Limitations
- The activation code doesn't prevent calling it twice within the same process (for example, the host app and a plugin). This is being worked on.
- For this release, packaged / MSIX / Sandboxed applications are not supported. Only desktop apps are supported.
- To fully support packaged apps, we need to get the runtime installed as a shared library/framework package in the store. Packaged apps will also continue to require the manifest.
Experimental SDK features
- SDK components for preview service plugins, like Network MIDI, are marked with the "experimental" attribute and may change in future releases. If you use them, you'll see warning
CS8305with MSBuild.
- Network MIDI 2.0 is under development, and not yet available in this release - Experimental features are not guaranteed to be backwards compatible from release to release
DLL Versions
- SDK DLL properties now include proper product version resources
C# Projection
- .NET support has been moved to version 8 and above, as the SDK is using some COM features supported only in .NET 8 and higher. .NET 8 is the long-term-servicing version of .NET so this would have been required soon anyway.
WinMM Compatibility
Although we still have some bugs to sort out, the WinMM compatibility code is in place and is feature complete. However, do see the notes below about usage.
- For MIDI 2.0 devices, we use Function Block information, if available, and Group Terminal Block info if not, to decide which groups are active and should be exposed as MIDI 1.0 ports.
- For MIDI 1.0 devices, we try to name the ports in a way that makes sense given the information available. This starts with Pin (iJack) information from the device. Please let us know if the device names are not what you would expect from the device. When doing so, please include the output of the
midiusbinfo.exeutility output covering that device.
Other WinMM notes
- The service installer does NOT install the
wdmaud2.drvdriver anymore. Without this driver, there is no WinMM backwards-compatibility support. The file is included in a zip with this release, but requires disabling Windows File Protection to install it. Note that it is only required for WinMM backwards compatibility.- We don't support disabling Windows File Protection, so if you choose to do so, you do it at your own risk. If you are not in a hurry to try out the WinMM compatibility, the Canary Insider release which will be available around the NAMM timeframe (possibly shortly after NAMM) will include the updated wdmaud2.drv, as well as everything required to make the WinMM compatibility code work together nicely.
- Apps which use 32 bit APIs, like MIDI-OX, are not supported in DP8. The ones we've tested do work with the upcoming circa-NAMM Canary release which includes the 32 bit Windows-on-Windows versions of the interfaces.
Protocol Negotiation and Endpoint Properties
- Fixed #440 so the service responds to stream negotiation messages now, even when the request matches current configuration
- Added additional integrity checks for function blocks to adhere more closely to spec. Without disconnecting and reconnecting the device:
- Cannot increase the number of blocks after initial discovery
- Cannot change any function block properties if static
- Cannot change the value of the "static function blocks" flag
- Added new property to the Endpoint Device Watcher Updated event args. This property is set to true if the serial number or product instance id change.
- SDK Endpoint device watcher now includes the timestamps in the category checks. This way, if an update is made to the data but the value didn't actually change, but the timestamp did, the correct category still fires. For performance and race condition reasons (you can't lock device properties) we update properties when valid updates are provided to the service. We do not compare the old and new values.
Command-line Tools
MIDI Diagnostics Tool
Mididiag is the tool provided for reporting on the state of Windows MIDI Services and was developed by request of hardware and DAW developers very early on. The typical use-case is a menu option in DAW or other app, or instructions on a support site, to dump the data for support use. It is intentionally machine-parsing friendly.
- The
mididiag.exetool has been updated to contain more information, including reporting on the COM registration of MIDI components.
MIDI USB Info Tool
This is a tool primarily for hardware developers so they can see how their USB MIDI 1.0 devices are being seen by the Windows Kernel Streaming code.
- The
midiusbinfo.exetool has been updated to be easier to understand when dumping connected USB device information - The tool reports only on MIDI 1.0 devices. MIDI 2.0 devices are listed, but do not contain additional information as it isn't needed
MIDI mDNS Info Tool
This tool has been developed for supporting Network MIDI 2.0. It will be used for displaying discovered advertised Network MIDI 2.0 devices
- The
midimdnsinfo.exetool ships with this release, but currently does not do anything useful. It is currently in development along with Network MIDI 2.0
MIDI Console Tool
The main MIDI Console tool is a primary tool for developers and advanced users to use to interface with Windows MIDI Services
- Added new midi console command which enables playing MIDI 1.0 and 2.0 note messages, with specified duration and rest in between, on an endpoint.
midi endpoint play-notes - Now displays version information at the top of the output
- Now displays SDK version and architecture information when no arguments are supplied
- The MIDI console includes a new command for listing Windows MIDI Services properties and their related IDs.
midi enum endpoint-property-keys
- Additionally, the
midi endpoint properties --include-rawcommand now uses the property key names from this lookup, as does the watcher.
midi watch-endpoints --verbose
Combined Filters in KS Aggregate Transport
Many MIDI 1.0 vendor drivers report their ports on separate Interfaces/KS filters. In our normal enumeration, these end up showing up as separate devices. The enumeration code now enumerates the actual devices first and then the KS filters under them. This is slightly slower than the older approach, but more correctly represents the devices.
The end result is that instead of seeing several entries for the same MIDI 1.0 device in the UMP endpoints, you will now see one.
The above screenshot shows a MOTU MIDI Express 128. This uses a custom driver and is not class-compliant. The driver reports each port number as a single filter interface, with two pins. The filter interface is named Express 128: Port n. The individual pins (iJack instances) are simply named MIDI. Normally, one would want to use the iJack name, but in this case, it results in 16 ports named MIDI, which is what we saw with the WinRT MIDI 1.0 API. We'll continue to work on the naming code here as there are several different ways that companies name devices, interfaces, and jacks when using their own drivers.
Main Configuration File
Bug: Currently, the Canary Insider builds protect the location of the configuration file, so it cannot be edited without clicking the MIDI folder in %allusersprofile%\Microsoft\MIDI and setting permissions to that folder and all contents to allow full control by all logged in users, and at least read by everyone.
Samples
If you want the samples to run with a minimum of NuGet fussing around, use the versions from the zip file below. Main will continue to move forward until we hit the 1.0 release, which means the NuGet references will be newer than what is available in the repo.
- There is a new simple app-to-app MIDI (Virtual Device App) sample in C++. This demonstrates creating the device and also updating properties. The more complete example is the C# one. This one focuses on the basics.
USB Driver
This release does not have a new USB MIDI Class driver. Please use the previous 10.0.1.7 release version and instructions from Developer Preview 7.
Please note: the USB MIDI 2.0 driver cannot yet be installed on Windows 10. We need to back-port the ACX and USB support before it will install and function there.