Skip to content

Developer Preview 6

Pre-release
Pre-release
Compare
Choose a tag to compare
@Psychlist1972 Psychlist1972 released this 14 Jul 01:55
· 310 commits to main since this release
dev-preview-6
5ce7a5b
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Learn about vigilant mode.

Windows MIDI Services Developer Preview 6

We're pleased to announce Windows MIDI Services Developer Preview 6!

This preview includes many changes and bug fixes from partner testing, as well as our various internal reviews and tests. There are some important changes in this release which move us much closer to the final form before the official consumer release.

Update 2024-07-22

The C++ samples have been updated to the correct NuGet package references, and included in a separate zip file below.

Also, please note that there have been some issues with folks not having the latest VC runtime. The installer has been fixed for the next release, but if you run into service crashes, please see this issue:

#368

Delivery Approach Change

When discussing the delivery approaches with the API review team, we jointly concluded that the WinRT MIDI2 Application API itself should be  shipped out of band from Windows rather than as part of the Windows SDK. The primary reason for this is the release and update schedules for the Windows SDK are too sparse for this product, we'd have challenges trying to make the API available to down-level Windows 10, and we'd also have to have Day 1 support for platforms that we don't tend to initially support (x86-32, Xbox, Hololens, etc.).

So here's the current (mostly complete) plan:

  • WinRT API Metadata and Initialization DLL: Ship through NuGet and Github.
  • WinRT API Implementation: We plan to ship this separately so we can centrally service it, at least for desktop apps.
  • Windows Service, WinMM/WinRT MIDI 1.0 API support, and USB MIDI 2.0 driver: delivered through Windows servicing.
  • Console and settings app: May be through the store, or through the central API servicing approach.

IMPORTANT NOTE: For this preview release, the code for resolving the SDK types without a manifest, and centrally installed, is not yet fully in place. That means that any application using this preview release needs to ship the SDK dll files locally (in the same folder as the exe loading them), and also include an appname.exe.manifest with all the activation entries. The SDK solution includes the contents of the manifest which can be used in your own project. That's also why the NuGet package includes all of the implementation DLLs, and not just the Initialization DLL. This is the normal approach for WinRT out of box SDKs, but we're working on a solution that doesn't require the main exe to declare every possible type in a manifest, and also ship the implementations. That solution isn't ready for this preview. If you try to use the SDK WinRT types without the manifest, Windows will not know how to resolve the types.

Installers

There are now separate installers for the SDK runtime (not used in this preview, but it does include the mididiag.exe utility) the in-box components (service and plugins), console app, and settings app.

To install this preview release

  • Fully uninstall all previous preview release components except the USB driver (Do this through Settings->Apps->Installed Apps)
  • Install the Service / In-Box components
  • Optionally Install the SDK Runtime installer. For this preview, this is only needed if you want to run the mididiag.exe utility app. It installs the runtime files and the mididiag.exe utility under %Program Files%\Windows MIDI Services, and adds the utility location to the path.
  • Install the MIDI Console. The installer will add midi.exe to the path for any console windows opened after the installer completes. We recommend you use Windows Terminal, which has full emoji support and GPU accelerated text output.

There is no settings app build for this preview. It will be in the next preview.

There is no updated USB driver for this preview, but it is coming soon.

Namespace and API signature changes

Because of the delivery approach change, the WinRT API namespace had to be changed from Windows::Devices::Midi2 to Microsoft::Windows::Devices::Midi2. This is a Windows standard for APIs/SDKs.

Additional breaking changes

  • The MidiService class was refactored into MidiDiagnostics, MidiReporting, and also the MidiServiceConfig classes across different winmd namespaces.
  • There are a number of naming and other changes, as well as type changes across the board, all to comply with the new delivery format. Many are just naming changes.
  • Additionally, the MidiEndpointDeviceInformation class properties were refactored into a number of simple structs which are both easier to work with, and also more obvious in terms of data source.

Additional startup check

  • The MIDI Service is now set to demand-start (triggered), as required by Microsoft for any Windows Services not required for startup.
  • To support the new model, applications should now use MidiInitializer::EnsureServiceAvailable() as the first step when starting up. This will start the service if it is present but not already running, and also tell you if Windows MIDI Services is installed and running. You only need to do this check once, at app startup. If Windows MIDI Services is not installed, apps may then decide to fall back to an older MIDI API, or inform the user that they are on an unsupported version of Windows. This code flow works well, but may have a couple minor changes before final release, mostly to ensure apps understand the exact nature of any problem.
  • The settings app will likely include an easy way for a user to change the service to always run, should they want to.

New or updated Features

Full translation for MIDI 1.0 devices connected to UMP USB MIDI driver

  • Previously, Message Type 4 (MIDI 2.0 Channel Voice messages) were dropped when sent to a MIDI 1.0 device connected to the MIDI UMP driver. Now they are downscaled to their MIDI 1.0 equivalents. This will never be perfect because of the extended uses of the MIDI 2.0 note on/off/etc messages, but consensus from partners was that getting a bad note is better than no note (example: when exact pitch is used and the note number is actually an index)

Automatic endpoint reconnection through API

  • When creating a new connection to an endpoint, the application may optionally enable auto-reconnection via a boolean parameter. This spins up a device watcher behind the scenes, at the session level, to watch that specific endpoint. When the device is reconnected, if the Id has not changed, the connection will be re-established and will be usable.
  • This is optional because the device watcher does add a small amount of overall overhead. Individual message send/receive is not impacted, however.

Dirty-disconnect cleanup

  • If you control-C the midi console, or you crash out without closing your session in your own app, the service now detects this and cleans up the open connections using a context handle at the session level, and a server context run-down routine.

Aggregated MIDI 1.0 endpoints

  • Previously, when using older or vendor drivers, only MIDI 1.0 endpoints with exactly one input and one output would be enumerated as UMP endpoints. Now, all MIDI 1.0 byte format endpoints on a KS filter (shows up as a "device" to us) are aggregated into a single UMP endpoint
  • Internally, the service creates group terminal blocks to represent the different pins, and makes group numbers to those pins. This is consistent with the behavior of the same devices connected to the MIDI 2.0 UMP driver

NOTE: We're looking into the possibility of combining filters for a device so single physical devices do not show up as multiple logical UMP endpoints. This is not yet in place.

iJack names now used for MIDI 1.0 endpoints

  • When provided, the value from iJack is now used as the name of a MIDI 1.0 endpoint. For aggregated UMP endpoints, this becomes the name of the generated group terminal blocks.

Arm64 support!

  • Everything is built for both Arm64 and x64 starting with this release. Arm64 builds are supported only on the latest Windows 11 releases, not on Windows 10.

Settings app

  • Service restarting is now built into the troubleshooting page. You must run as administrator to use it.

NOTE: The Settings app is not included in this preview. It should be in the next preview.

Console app

  • Settings app midi enum endpoints now shows the function blocks or group terminal blocks for the endpoint when --verbose is specified

Additional Notes

Projections

  • This preview ships with the .NET projection as well as direct support for C++/WinRT, and header support for other C++ developers
  • This preview will include an Electron projection, but not until end of next week. Please let us know on Discord if you are active using it, as this may be the last one we create.
  • You can generate all the headers needed automatically if you use the cppwinrt tool in C++/WinRT (tool is also available in the C++/WinRT official NuGet package). However, the Windows MIDI Services NuGet package includes all the headers for this SDK in the build/native/include/midi2 folder. If your tooling doesn't support NuGet packages, just rename the package to .zip and until to a location of your choice.

Dependency Versions

  • All .NET projections, references, and targets are now set to .NET 6 with a minimum Windows SDK version of 10.0.20348. .NET 8 is the most recent long-term support version of .NET and is recommended. .NET 6 is minimum. The NuGet package declares support for .NET 6, 7, 8, and 9.
  • All projects updated to latest versions of C++/WinRT, and (where appropriate) latest Windows App SDK/WinUI 3

Documentation

Most of the documentation at https://aka.ms/midi is up to date with the SDK refactor. We're working on the rest of it. Feel free to log bugs if you find documentation issues.

Assets 10
Loading