Skip to content

Commit a042e93

Browse files
Merge pull request #495 from microsoft/pete-dev
Tons of documentation updates to bring most docs back up to level
2 parents 1a75f9a + 757e4d7 commit a042e93

File tree

123 files changed

+1030
-487
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

123 files changed

+1030
-487
lines changed

build/staging/version/BundleInfo.wxi

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
<Include>
22
<?define SetupVersionName="Developer Preview 9 Arm64" ?>
3-
<?define SetupVersionNumber="1.0.2-preview-9.250118-2124" ?>
3+
<?define SetupVersionNumber="1.0.2-preview-9.250119-1653" ?>
44
</Include>

build/staging/version/WindowsMidiServicesVersion.cs

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,12 +6,12 @@ public static class MidiBuildInformation
66
{
77
public const string Source = "GitHub Preview";
88
public const string Name = "Developer Preview 9";
9-
public const string BuildFullVersion = "1.0.2-preview-9.250118-2124";
9+
public const string BuildFullVersion = "1.0.2-preview-9.250119-1653";
1010
public const string VersionMajor = "1";
1111
public const string VersionMinor = "0";
1212
public const string VersionRevision = "2";
13-
public const string VersionDateNumber = "250118";
14-
public const string VersionTimeNumber = "2124";
13+
public const string VersionDateNumber = "250119";
14+
public const string VersionTimeNumber = "1653";
1515
}
1616
}
1717

build/staging/version/WindowsMidiServicesVersion.h

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,12 @@
55

66
#define WINDOWS_MIDI_SERVICES_BUILD_SOURCE L"GitHub Preview"
77
#define WINDOWS_MIDI_SERVICES_BUILD_VERSION_NAME L"Developer Preview 9"
8-
#define WINDOWS_MIDI_SERVICES_BUILD_VERSION_FULL L"1.0.2-preview-9.250118-2124"
8+
#define WINDOWS_MIDI_SERVICES_BUILD_VERSION_FULL L"1.0.2-preview-9.250119-1653"
99
#define WINDOWS_MIDI_SERVICES_BUILD_VERSION_MAJOR L"1"
1010
#define WINDOWS_MIDI_SERVICES_BUILD_VERSION_MINOR L"0"
1111
#define WINDOWS_MIDI_SERVICES_BUILD_VERSION_REVISION L"2"
12-
#define WINDOWS_MIDI_SERVICES_BUILD_VERSION_DATE_NUMBER L"250118"
13-
#define WINDOWS_MIDI_SERVICES_BUILD_VERSION_TIME_NUMBER L"2124"
12+
#define WINDOWS_MIDI_SERVICES_BUILD_VERSION_DATE_NUMBER L"250119"
13+
#define WINDOWS_MIDI_SERVICES_BUILD_VERSION_TIME_NUMBER L"1653"
1414

1515
#endif
1616

docs/data-translation.md

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,10 +12,21 @@ Internally, the MIDI service moves messages around in the UMP format. This enabl
1212

1313
## A couple definitions
1414

15+
### MIDI 1.0 (Byte) Data format
1516

17+
This is the byte format (also called "byte stream" due to how it operates over MIDI 1.0 DIN/Serial connections) used by MIDI 1.0.
1618

19+
### MIDI UMP Data format
1720

21+
This is the Universal MIDI Packet format. Packets are from 1 to 4 32-bit words in length, and are self-contained and atomic. Internally in Windows MIDI Services, all messages are processed and transports in UMP format, and translated to MIDI 1.0 byte data format as needed
1822

23+
### MIDI 1.0 Protocol
24+
25+
The MIDI messages defined in the MIDI 1.0 specifications, with most values between 0-127, and messages containing 1-3 bytes (except System Exclusive). These messages can be transported in the MIDI 1.0 data format, or in the Universal MIDI Packet format.
26+
27+
### MIDI 2.0 Protocol
28+
29+
The MIDI messages defined in the MIDI 2.0 UMP specifications, excluding the MIDI 1.0 protocol messages in UMP format.
1930

2031
## Translation Scenarios involving data format changes
2132

@@ -32,7 +43,9 @@ Windows MIDI Services supports both MIDI 1.0 and MIDI 2.0 devices.
3243

3344
### Translation between Message type 2 (MIDI 1.0 Channel Voice) and Message type 4 (MIDI 2.0 Channel Voice)
3445

35-
Currently, Windows MIDI Services does not translate messages based on negotiated protocol or Function Block declared protocol. Instead, for native UMP endpoints, applications should send the correct protocol messages (message type 2 for MIDI 1.0-compatible and message type 4 for MIDI 2.0-compatible messages) based upon the information provided by the `MidiEndpointDeviceInformation` class. In addition, for native MIDI 1.0 byte data format endpoints, applications should send the appropriate MIDI 1.0 messages in UMP.
46+
Currently, Windows MIDI Services does not translate messages based on Function Block declared protocol. Instead, for native UMP endpoints, applications should send the correct protocol messages (message type 2 for MIDI 1.0-compatible and message type 4 for MIDI 2.0-compatible messages) based upon the information provided by the `MidiEndpointDeviceInformation` class. In addition, for native MIDI 1.0 byte data format endpoints, applications should send the appropriate MIDI 1.0 messages in UMP.
47+
48+
Windows MIDI Services will downscale messages as needed based on negotiated protocol. We plan to add upscaling (if an endpoing negotiates MIDI 2 but doesn't support MIDI 1), but that is not in place in the first release.
3649

3750
If a MIDI 1.0 device is connected to the new MIDI 2.0 Class Driver, Windows MIDI Services *will* downscale Message Type 4 to Message Type 2 before sending to the driver. This is because the driver, when working with a MIDI 1.0 device, only handles UMP messages which can be directly translated to MIDI 1.0 data format.
3851

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
---
2+
layout: page
3+
title: Bootstrap Windows MIDI Services
4+
parent: Developer How-to
5+
has_children: false
6+
---
7+
8+
# How to bootstrap the SDK and Start the Service
9+
10+
TODO: This document is a work-in-progress.
11+
12+
The SDK is a central installation with a bootstrapper COM component. The COM component handles all WinRT activation for Windows MIDI Services without requiring the MIDI types to be included in any type of manifest (for desktop apps). Applications do not deploy anything except their own compiled code.
13+
14+
Individual applications do not deploy the SDK with their binaries. The C# projection in the NuGet package contains everything a C# application needs. For C++, the NuGet package includes a .hpp file with the required implementation.
15+
16+
## Examples
17+
18+
```cpp
19+
// MTA by default
20+
winrt::init_apartment();
21+
22+
// this is the initializer in the bootstrapper hpp file
23+
std::shared_ptr<init::MidiDesktopAppSdkInitializer> initializer = std::make_shared<init::MidiDesktopAppSdkInitializer>();
24+
25+
// you can, of course, use guard macros instead of this check
26+
if (initializer != nullptr)
27+
{
28+
if (!initializer->InitializeSdkRuntime())
29+
{
30+
std::cout << "Could not initialize SDK runtime" << std::endl;
31+
std::wcout << "Install the latest SDK runtime installer from " << initializer->LatestMidiAppSdkDownloadUrl << std::endl;
32+
return 1;
33+
}
34+
35+
if (!initializer->EnsureServiceAvailable())
36+
{
37+
std::cout << "Could not demand-start the MIDI service" << std::endl;
38+
return 1;
39+
}
40+
}
41+
else
42+
{
43+
// This shouldn't happen, but good to guard
44+
std::cout << "Unable to create initializer" << std::endl;
45+
return 1;
46+
}
47+
```
48+
49+
50+
```csharp
51+
// the initializer implements the Dispose pattern, so will shut down WinRT type redirection when disposed
52+
using (var initializer = Microsoft.Windows.Devices.Midi2.Initialization.MidiDesktopAppSdkInitializer.Create())
53+
{
54+
// initialize SDK runtime
55+
if (!initializer.InitializeSdkRuntime())
56+
{
57+
Console.WriteLine("Failed to initialize SDK Runtime");
58+
return 1;
59+
}
60+
61+
// start the service
62+
if (!initializer.EnsureServiceAvailable())
63+
{
64+
Console.WriteLine("Failed to get service running");
65+
return 1;
66+
}
67+
68+
...
69+
70+
}
71+
```

docs/developer-how-to/how-to-check-for-windows-midi-services.md

Lines changed: 0 additions & 104 deletions
This file was deleted.

docs/endpoints/config-json.md

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -74,7 +74,7 @@ Here's an example of a bare-bones file, with sections for three different transp
7474

7575
> NOTE: This section is in flux, as we're changing how devices are identified, and how properties are set.
7676
77-
The basics of this are identical for each transport. We'll use KS (USB) as an example as it has the most complex lookup mechanisms to attempt to identify devices, even when they are moved from port to port.
77+
Here's how the KS (USB using the new UMP driver) transport works as an example as it has the most complex lookup mechanisms to attempt to identify devices, even when they are moved from USB port to port.
7878

7979
```json
8080
"{26FA740D-469C-4D33-BEB1-3885DE7D6DF1}":
@@ -98,7 +98,10 @@ The basics of this are identical for each transport. We'll use KS (USB) as an ex
9898
},
9999
```
100100

101-
Valid properties you can set across all supported endpoints
101+
> TODO: Include KSA endpoints and their generated group terminal blocks / groups.
102+
103+
104+
Valid properties you can set:
102105

103106
| Property | Type | Description |
104107
| -------- | ---- | ----------- |

docs/endpoints/diagnostic-endpoints.md

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ has_children: false
1010

1111
| Property | Value |
1212
| -------- | ----- |
13-
| Abstraction Id | `{ac9b5417-3fe0-4e62-960f-034ee4235a1a}` |
13+
| Transport Id | `{ac9b5417-3fe0-4e62-960f-034ee4235a1a}` |
1414
| Abbreviation | `DIAG` |
1515

1616
(Note: This transport cannot be disabled and is not listed in the registry. Its activation is hard-coded into the Windows service. Settings for this transport are not read from the configuration file and cannot be changed.)
@@ -50,15 +50,13 @@ If you need the more typical timestamp behavior, you can set up app-to-app MIDI
5050

5151
### Metadata Capture
5252

53-
The Loopback endpoints capture Endpoint and Function Block metadata just like any other endpoint. Because of this, you can change the name of the endpoint through in-protocol messages. If you do that, simply change it back later using the same type of message.
54-
55-
> Note: We're working to purge the endpoint metadata cache on device reconnection or service restart, which would reset those properties and names. Currently, it persists across service and Windows restarts.
53+
The Loopback endpoints capture Endpoint and Function Block metadata just like any other endpoint. Because of this, you can change the name of the endpoint through in-protocol messages. If you do that, simply change it back later using the same type of message, or with a service restart.
5654

5755
## Ping
5856

59-
The ping endpoint is not normally returned through any enumeration. It is for internal use only, and should not be used by any applications. It recognizes only one type of proprietary message.
57+
The ping endpoint is not normally returned through any enumeration. It is for internal use only, and should not be used by any applications. It recognizes only one type of proprietary message that is not part of the standard MIDI 2.0 UMP Protocol.
6058

61-
Behavior and implementation of the Ping endpoint is subject to change and should not be relied upon by any code outside of the API.
59+
Behavior and implementation of the Ping endpoint is subject to change and should not be relied upon by any code outside of the SDK.
6260

6361
## Compatibility
6462

docs/endpoints/kernel-streaming-aggregate.md

Lines changed: 12 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -10,18 +10,16 @@ has_children: false
1010

1111
| Property | Value |
1212
| -------- | ----- |
13-
| Abstraction Id | `TBA` |
13+
| Transport Id | `{0F273B18-E372-4D95-87AC-C31C3D22E937}` |
1414
| Abbreviation | `KSA` |
1515

1616
## Overview
1717

18-
The Kernel Streaming Aggregator transport creates UMP endpoints for MIDI 1.0 devices using MIDI 1.0 byte format devices, like third-party MIDI 1.0 drivers.
19-
20-
> NOTE: This transport may be recombined with the base Kernel Streaming transport in the future
18+
The Kernel Streaming Aggregator transport creates UMP endpoints for MIDI 1.0 devices using MIDI 1.0 byte format devices, like third-party MIDI 1.0 drivers, and our in-box USB MIDI 1.0 Class Driver.
2119

2220
## Suggested Uses
2321

24-
Although this transport is primarily recommended for USB devices, it may be used for access to most other existing MIDI 1.0 devices on Windows.
22+
Although this transport is primarily recommended for USB devices, it may be used for access to most other existing MIDI 1.0 devices on Windows as long as they have a Kernel Streaming driver.
2523

2624
## Compatibility
2725

@@ -33,6 +31,10 @@ The best experience for Windows MIDI Services will be with applications using th
3331
| WinRT MIDI 1.0 | Yes | Data is translated between UMP and MIDI bytes (MIDI 1.0 data format) as required. |
3432
| WinMM MIDI 1.0 | Yes | Data is translated between UMP and MIDI bytes (MIDI 1.0 data format) as required. |
3533

34+
## Grouping
35+
36+
When creating MIDI 2.0 / UMP Endpoints, the aggregation happens at the device level. All interfaces and pins under the device are aggregated and presented as a single UMP endpoint.
37+
3638
## Naming
3739

3840
MIDI 1.0 port names use a new algorithm for naming, compared to what we have had in the past. Specifically, the device interface (the filter) name is the default root of the name. If there is no filter name, then we walk up to the parent device and use that device's name as the root. Next, we query for the pin names, if provided via `iJack`, and append that to the name.
@@ -46,16 +48,18 @@ Endpoints for this transport are not created through the configuration file, but
4648
```json
4749
"endpointTransportPluginSettings":
4850
{
49-
"{26FA740D-469C-4D33-BEB1-3885DE7D6DF1}":
51+
"{0F273B18-E372-4D95-87AC-C31C3D22E937}":
5052
{
5153
"_comment": "KSA MIDI (USB etc.)",
52-
"SWD: \\\\?\\SWD#MIDISRV#MIDIU_KSA_BIDI_6799286025327820155#{e7cce071-3c03-423f-88d3-f1045d02552b}":
54+
"SWD: \\\\?\\swd#midisrv#midiu_ksa_6799286025327820155#{e7cce071-3c03-423f-88d3-f1045d02552b}":
5355
{
5456

5557
}
5658
}
5759
}
5860
```
5961

60-
## Implementation
62+
> TODO: Need to add options for the WinMM port numbers and more
63+
6164

65+
> If you want to see how Windows sees any given device at the Kernel Streaming interface level, run the SDK tool `midiksinfo`. That will list all KS devices as they are seen before we create MIDI endpoints for them.

docs/endpoints/kernel-streaming.md

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ has_children: false
1010

1111
| Property | Value |
1212
| -------- | ----- |
13-
| Abstraction Id | `{26FA740D-469C-4D33-BEB1-3885DE7D6DF1}` |
13+
| Transport Id | `{26FA740D-469C-4D33-BEB1-3885DE7D6DF1}` |
1414
| Abbreviation | `KS` |
1515

1616
## Overview
@@ -29,7 +29,7 @@ The best experience for Windows MIDI Services will be with applications using th
2929
| WinRT MIDI 1.0 | Yes | Data is translated between UMP and MIDI bytes (MIDI 1.0 data format) as required. |
3030
| WinMM MIDI 1.0 | Yes | Data is translated between UMP and MIDI bytes (MIDI 1.0 data format) as required. |
3131

32-
> When creating endpoints for use by MIDI 1.0 applications which connect to MIDI 2.0 devices, we're limited to using the declared Group Terminal blocks and their associated groups, unless the device is MIDI 2.0 and the function blocks retrieved are marked as static function blocks.
32+
> When creating WinMM and WinRT MIDI 1.0 endpoints for applications using the older APIs, we first use the declared Function Blocks. If there are no function blocks, we use the Group Terminal Blocks. If there are no declared group terminal blocks, we currently create 16 input ports and 16 output ports -- 1 for each group in each direction. However, we're likely to change this in the future and require the user to specify if they want more than 1 group in each direction because creating the backwards compatible WinMM ports is costly.
3333
3434
## Configuration
3535

@@ -51,3 +51,7 @@ Endpoints for this transport are not created through the configuration file, but
5151
}
5252
```
5353

54+
> TODO: Need to add options for the WinMM port numbers and more
55+
56+
> If you want to see how Windows sees any given device at the Kernel Streaming interface level, run the SDK tool `midiksinfo`. That will list all KS devices as they are seen before we create MIDI endpoints for them.
57+

0 commit comments

Comments
 (0)