You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: docs/api/README.md
+5-3
Original file line number
Diff line number
Diff line change
@@ -10,6 +10,7 @@ The Windows.Devices.Midi2 types are documented in these pages.
10
10
11
11
Typical API workflow:
12
12
13
+
1.**Check for Windows MIDI Services availability**. Windows MIDI Services is not available on older versions of Windows, or on devices like Xbox, Hololens, and others. The first step is to make a call to check for availability of the services on Windows. If Windows MIDI Services is not available, you may want to fall back to an older MIDI API, or simply inform the user and terminate the application.
13
14
1.**Create a new session**, with an appropriate name. The name will be visible to users and so should be meaningful. Each application may open more than one session at a time (for example, different songs in a DAW, or different tabs in a browser). A single session manages the lifetime of the connections opened through it.
14
15
2.**Connect to an endpoint**. Typically, you'll get the endpoint's id through the enumeration functions.
15
16
3.**Wire up a MidiMessageReceived event handler**. This is how you will receive incoming messages from the endpoint. Messages are received individually, with one event per message.
@@ -20,6 +21,10 @@ Typical API workflow:
20
21
21
22
Enumeration is how you discover endpoints and get notified of endpoints when they are added, updated, or removed. For the best user experience, keep a `MidiEndpointDeviceWatcher` running in a background thread so you can monitor device removal, and property updates (name, function blocks, etc.)
22
23
24
+
## Service
25
+
26
+
The MidiService class is a utility class which provides access to health and status information related to the MidiSrv Service. This is also where you can check to see if Windows MIDI Services is available on this PC.
27
+
23
28
## Session
24
29
25
30
Interaction with a MIDI Endpoint always starts with creating a session.
@@ -52,6 +57,3 @@ A virtual device is the mechanism through which app-to-app MIDI works through th
52
57
53
58
There are several simple or basic types used in Windows MIDI Services. These types provide formatting and validation to help ensure applications display data in similar ways.
54
59
55
-
## Service
56
-
57
-
The MidiService class is a utility class which provides access to health and status information related to the MidiSrv Service.
Copy file name to clipboardexpand all lines: docs/api/service/MidiService.md
+27-34
Original file line number
Diff line number
Diff line change
@@ -8,57 +8,50 @@ has_children: false
8
8
9
9
# MidiService
10
10
11
+
## Remarks
12
+
11
13
The MidiService class contains a number of static functions which enable working with the service outside of a specific session.
12
14
13
-
##Static Functions : Reporting
15
+
### Service Health
14
16
15
-
| Static Function | Description |
16
-
|---|---|
17
-
|`GetInstalledTransportPlugins()`| Returns a list of `MidiServiceTransportPluginInformation` representing all service transport plugins (also called Abstractions) |
18
-
|`GetInstalledMessageProcessingPlugins()`| Returns a list of `MidiServiceMessageProcessingPluginInformation` objects representing all service message processing plugins (also called Transforms) |
19
-
|`GetActiveSessions()`| Returns a list of `MidiSessionInformation` detailing all active Windows MIDI Services sessions on this PC. |
17
+
|`IsAvailable()`| Returns true of Windows MIDI Services is available on this PC. Calling this function is typically the first step in using Windows MIDI Services in your application. |
18
+
|`PingService(UInt8)`| Send the specified count of ping messages to the ping endpoint and report on the status and time. Return if the responses are not received in an internally calculated timeout period. |
19
+
|`PingService(UInt8, UInt32)`| Send the specified count of ping messages to the ping endpoint and report on the status and time. Return if responses are not received in the specified timeout period (milliseconds). |
20
20
21
-
## Static Functions : Loopback Endpoints
22
-
23
-
| Static Function | Description |
24
-
|---|---|
25
-
|`CreateTemporaryLoopbackEndpoints(associationId, endpointA, endpointB)`| Create a pair of loopback endpoints which will live until removed through the API or the service is restarted. |
26
-
|`RemoveTemporaryLoopbackEndpoints(associationId)`| Remove a pair of temporary loopback endpoints. |
21
+
Pinging the Windows service uses the same mechanism as sending any UMP message. The actual message sent is a prioprietary message. (At the time this was created, there was no standard MIDI 2.0 UMP ping message). The message itself is sent to the diagnostics endpoint in the service, which is implemented like any other transport. Therefore, the speed of the pings here and the success of the ping process is a reasonable indicator of service, cross-process queue, and client API health.
27
22
28
-
Applications creating endpoints for app-to-app MIDI should generally use the Virtual Device support built into the API. However, applications may need to create lightweight loopback endpoints without the protocol negotiation, MIDI 2.0 discovery process, and lifetime management provided by the Virtual Device support. For those scenarios, we have a simple loopback endpoint type.
23
+
The diagnostic ping endpoint does not understand any other type of message, and should not be used by applications other than through the ping functions here.
29
24
30
-
Loopback endpoints created by the user and stored in the configuration file will persist after the service is restarted or the PC rebooted. Loopback endpoints created through this API call are temporary, and will disappear if the service is restarted. In both cases, this feature requires that the loopback endpoint transport is installed and enabled.
25
+
The ping does not tell you if a specific transport or device is in a bad state. For example, if a specific USB MIDI device has crashed, this ping message will still work because it is not sent out over USB.
31
26
32
-
## Static Functions : Runtime Configuration
27
+
Here's an example of ping responses through the MIDI console app
33
28
34
-
| Static Function | Description |
35
-
|---|---|
36
-
|`UpdateTransportPluginConfiguration(configurationUpdate)`| Sends an update to the service to be used by a transport plugin ("Abstraction") |
37
-
|`UpdateProcessingPluginConfiguration(configurationUpdate)`| Sends an update to the service to be used by a message processing plugin ("Transform") |
29
+
38
30
39
-
For plugins which support updates at runtime, developers of those plugins should create configuration WinRT types which implement the required configuration interfaces, and create the JSON that is used in the service. In this way, third-party service transport and message processing plugins can be created and configured without changes to the API.
31
+
### Reporting
40
32
41
-
> Note: In version 1 of the API, only transports can be configured at runtime. We're working on enabling configuration of message processing plugins. The API is a no-op.
33
+
|`GetInstalledTransportPlugins()`| Returns a list of `MidiServiceTransportPluginInformation` representing all service transport plugins (also called Abstractions) |
34
+
|`GetInstalledMessageProcessingPlugins()`| Returns a list of `MidiServiceMessageProcessingPluginInformation` objects representing all service message processing plugins (also called Transforms) |
35
+
|`GetActiveSessions()`| Returns a list of `MidiSessionInformation` detailing all active Windows MIDI Services sessions on this PC. |
42
36
43
-
##Static Functions : Service Health
37
+
### Loopback Endpoints
44
38
45
-
| Static Function | Description |
46
-
|---|---|
47
-
|`PingService(pingCount)`| Send one or more ping messages to the ping endpoint and report on the status and time. Return if the responses are not received in a calculated timeout period. |
48
-
|`PingService(pingCount, timeoutMilliseconds)`| Send one or more ping messages to the ping endpoint and report on the status and time. Return if responses are not received in the specified timeout period. |
39
+
|`CreateTemporaryLoopbackEndpoints(Guid, MidiServiceLoopbackEndpointDefinition, MidiServiceLoopbackEndpointDefinition)`| Create a pair of loopback endpoints which will live until removed through the API or the service is restarted. |
40
+
|`RemoveTemporaryLoopbackEndpoints(Guid)`| Remove a pair of temporary loopback endpoints when provided their association Id Guid. |
49
41
50
-
### The ping process
42
+
Applications creating endpoints for app-to-app MIDI should generally use the Virtual Device support built into the API. However, applications may need to create lightweight loopback endpoints without the protocol negotiation, MIDI 2.0 discovery process, and lifetime management provided by the Virtual Device support. For those scenarios, we have a simple loopback endpoint type.
51
43
52
-
Pinging the Windows service uses the same mechanism as sending any UMP message. The actual message sent is a prioprietary message. (At the time this was created, there was no standard MIDI 2.0 UMP ping message). The message itself is sent to the diagnostics endpoint in the service, which is implemented like any other transport. Therefore, the speed of the pings here and the success of the ping process is a reasonable indicator of service, cross-process queue, and client API health.
44
+
Loopback endpoints created by the user and stored in the configuration file will persist after the service is restarted or the PC rebooted. Loopback endpoints created through this API call are temporary, and will disappear if the serviceis restarted. In both cases, this feature requires that the loopback endpoint transport is installed and enabled.
53
45
54
-
The diagnostic ping endpoint does not understand any other type of message, and should not be used by applications other than through the ping functions here.
46
+
### Runtime Configuration
55
47
56
-
The ping does not tell you if a specific transport or device is in a bad state. For example, if a specific USB MIDI device has crashed, this ping message will still work because it is not sent out over USB.
48
+
|`UpdateTransportPluginConfiguration(IMidiServiceTransportPluginConfiguration)`| Sends an update to the service to be used by a transport plugin ("Abstraction") |
49
+
|`UpdateProcessingPluginConfiguration(IMidiServiceMessageProcessingPluginConfiguration)`| Sends an update to the service to be used by a message processing plugin ("Transform") |
57
50
58
-
Here's an example of ping responses through the MIDI console app
51
+
For plugins which support updates at runtime, developers of those plugins should create configuration WinRT types which implement the required configuration interfaces, and create the JSON that is used in the service. In this way, third-party service transport and message processing plugins can be created and configured without changes to the API.
59
52
60
-
53
+
> Note: In version 1 of the API, only transports can be configured at runtime. We're working on enabling configuration of message processing plugins. The API is a no-op.
Copy file name to clipboardexpand all lines: docs/api/service/README.md
+1-2
Original file line number
Diff line number
Diff line change
@@ -7,5 +7,4 @@ has_children: true
7
7
8
8
# Service
9
9
10
-
The MidiService class is a utility class which provides access to health and status information related to the MidiSrv Service.
11
-
10
+
The MidiService class is a utility class which provides access to health and status information related to the MidiSrv Service. This is also where you can check to see if Windows MIDI Services is available on this PC.
Copy file name to clipboardexpand all lines: docs/api/simple-types/MidiChannel.md
+11-15
Original file line number
Diff line number
Diff line change
@@ -8,33 +8,29 @@ has_children: false
8
8
9
9
# MidiChannel
10
10
11
-
The MidiChannel class is used to provide formatting and data validation for MIDI 1.0 and MIDI 2.0 channels.
11
+
## Remarks
12
+
13
+
The `MidiChannel` class is used to provide formatting and data validation for MIDI 1.0 and MIDI 2.0 channels. For clarity, the 0-15 value used in all messages is the `Index` and the 1-16 value those are mapped to for user display, is the `NumberForDisplay`.
14
+
15
+
## Constructors
16
+
17
+
|`MidiChannel`| Create an empty MidiChannel object (Index 0) |
18
+
|`MidiChannel(UInt8)`| Create a MidiChannel with the specified channel Index (0-15) |
12
19
13
20
## Properties
14
21
15
-
| Property | Description |
16
-
| --------------- | ----------- |
17
22
|`Index`| The data value, or channel Index (0-15) |
18
23
|`NumberForDisplay`| The number that should be displayed in any UI. (1-16) |
19
24
20
25
## Static Properties
21
26
22
-
| Static Property | Description |
23
-
| --------------- | ----------- |
24
27
|`LabelShort`| Returns the localized abbreviation. For example, "Ch" in English. |
25
28
|`LabelFull`| Returns the localized full name. For example, "Channel" in English. |
26
29
27
-
## Functions
28
-
29
-
| Function | Description |
30
-
| --------------- | ----------- |
31
-
|`MidiChannel()`| Constructs an empty `MidiChannel`|
32
-
|`MidiChannel(index)`| Constructs a `MidiChannel` with the specified index |
30
+
## Static Methods
33
31
34
-
## Static Functions
32
+
|`IsValidChannelIndex(UInt8)`| Verifies that the provided index is valid (between 0 and 15) |
35
33
36
-
| Static Function | Description |
37
-
| --------------- | ----------- |
38
-
|`IsValidChannelIndex(index)`| Verifies that the provided index is valid (between 0 and 15) |
Copy file name to clipboardexpand all lines: docs/api/simple-types/MidiGroup.md
+12-16
Original file line number
Diff line number
Diff line change
@@ -8,33 +8,29 @@ has_children: false
8
8
9
9
# MidiGroup
10
10
11
-
The `MidiGroup` class is used to provide formatting and data validation for UMP (Universal MIDI Packet) groups.
11
+
## Remarks
12
+
13
+
The `MidiGroup` class is used to provide formatting and data validation for MIDI 2.0 groups. For clarity, the 0-15 value used in all messages is the `Index` and the 1-16 value those are mapped to for user display, is the `NumberForDisplay`.
14
+
15
+
## Constructors
16
+
17
+
|`MidiGroup`| Create an empty MidiGroup object (Index 0) |
18
+
|`MidiChannel(UInt8)`| Create a MidiChannel with the specified channel Index (0-15) |
12
19
13
20
## Properties
14
21
15
-
| Property | Description |
16
-
| --------------- | ----------- |
17
-
|`Index`| The data value, or group Index (0-15) |
22
+
|`Index`| The data value, or channel Index (0-15) |
18
23
|`NumberForDisplay`| The number that should be displayed in any UI. (1-16) |
19
24
20
25
## Static Properties
21
26
22
-
| Static Property | Description |
23
-
| --------------- | ----------- |
24
27
|`LabelShort`| Returns the localized abbreviation. For example, "Gr" in English. |
25
28
|`LabelFull`| Returns the localized full name. For example, "Group" in English. |
26
29
27
-
## Functions
28
-
29
-
| Function | Description |
30
-
| --------------- | ----------- |
31
-
|`MidiGroup()`| Constructs an empty `MidiGroup`|
32
-
|`MidiGroup(index)`| Constructs a `MidiGroup` with the specified index |
30
+
## Static Methods
33
31
34
-
## Static Functions
32
+
|`IsValidGroupIndex(UInt8)`| Verifies that the provided index is valid (between 0 and 15) |
35
33
36
-
| Static Function | Description |
37
-
| --------------- | ----------- |
38
-
|`IsValidGroupIndex(index)`| Verifies that the provided index is valid (between 0 and 15) |
Copy file name to clipboardexpand all lines: docs/api/simple-types/MidiUniqueId.md
+21-22
Original file line number
Diff line number
Diff line change
@@ -8,43 +8,42 @@ has_children: false
8
8
9
9
# MidiUniqueId
10
10
11
-
The `MidiUniqueId` class is used to provide formatting and data validation for MIDI-CI MUID types used in Function Blocks and MIDI CI transactions.
11
+
## Remarks
12
+
13
+
The `MidiUniqueId` class is used to provide formatting and data validation for MIDI-CI MUID (MIDI Unique Id) types used in Function Blocks and MIDI CI transactions.
12
14
13
15
In the specification, Byte1 is the LSB and Byte4 is the MSB. We follow that convention here.
14
16
17
+
## Constructors
18
+
19
+
|`MidiUniqueId()`| Constructs an empty `MidiUniqueId`|
20
+
|`MidiUniqueId(UInt32)`| Constructs the `MidiUniqueId` from the given 28 bit integer |
21
+
|`MidiUniqueId(UInt8, UInt8, UInt8, UInt8)`| Constructs a `MidiUniqueId` with the specified seven-bit bytes |
22
+
15
23
## Properties
16
24
17
-
| Property | Description |
18
-
| --------------- | ----------- |
19
-
|`Byte1`| The data value for byte 1 of the MUID |
20
-
|`Byte2`| The data value for byte 2 of the MUID |
21
-
|`Byte3`| The data value for byte 3 of the MUID |
22
-
|`Byte4`| The data value for byte 4 of the MUID |
25
+
|`Byte1`| The data value for byte 1 of the MUID (LSB) |
26
+
|`Byte2`| The data value for byte 2 of the MUID (second-most LSB) |
27
+
|`Byte3`| The data value for byte 3 of the MUID (second-most MSB) |
28
+
|`Byte4`| The data value for byte 4 of the MUID (MSB) |
23
29
|`As28BitInteger`| The data value converted to a 28 bit integer |
24
-
|`IsBroadcast`| True if this is the broadcast MUID value |
25
-
|`IsReserved`| True if this is the reserved MUID value |
30
+
|`IsBroadcast`| True if this is the broadcast MUID value from the MIDI CI specification|
31
+
|`IsReserved`| True if this is the reserved MUID value from the MIDI CI specification |
26
32
27
33
## Static Properties
28
34
29
35
| Static Property | Description |
30
36
| --------------- | ----------- |
31
-
|`LabelShort`| Returns the localized abbreviation. |
32
-
|`LabelFull`| Returns the localized full name. |
33
-
34
-
## Functions
35
-
36
-
| Function | Description |
37
-
| --------------- | ----------- |
38
-
|`MidiUniqueId()`| Constructs an empty `MidiUniqueId`|
39
-
|`MidiUniqueId(integer28bit)`| Constructs the `MidiUniqueId` from the given 28 bit integer |
40
-
|`MidiUniqueId(byte1, byte2, byte3, byte4)`| Constructs a `MidiUniqueId` with the specified bytes |
37
+
|`LabelShort`| Returns the localized abbreviation for use in UI. |
38
+
|`LabelFull`| Returns the localized full name for use in UI. |
41
39
42
-
## Static Functions
40
+
## Static Methods
43
41
44
42
| Function | Description |
45
43
| --------------- | ----------- |
46
-
|`CreateBroadcast()`| Constructs a broadcast `MidiUniqueId`|
47
-
|`CreateRandom()`| Constructs a random `MidiUniqueId`|
44
+
|`CreateBroadcast()`| Constructs a broadcast `MidiUniqueId`per the MIDI CI specification |
45
+
|`CreateRandom()`| Constructs a random `MidiUniqueId`per the MIDI CI specification |
Copy file name to clipboardexpand all lines: docs/api/simple-types/README.md
-1
Original file line number
Diff line number
Diff line change
@@ -8,4 +8,3 @@ has_children: true
8
8
# Simple Types
9
9
10
10
There are several simple or basic types used in Windows MIDI Services. These types provide formatting and validation to help ensure applications display data in similar ways.
0 commit comments