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/console/endpoints.md
+13-163
Original file line number
Diff line number
Diff line change
@@ -1,152 +1,10 @@
1
1
---
2
2
layout: page
3
-
title: MIDI Console
4
-
parent: Windows Midi Services
3
+
title: Endpoints and Messages
4
+
parent: MIDI Console
5
5
---
6
6
7
-
# Windows MIDI Services Console
8
-
9
-
If you have the midi console installed, you can invoke it from any command prompt using `midi`. We recommend using [Windows Terminal](https://aka.ms/terminal) for the best experience.
10
-
11
-
## General Information
12
-
13
-
### Commands vs Options
14
-
15
-
MIDI Console commands are words with no symbol prefix. For example `endpoint` or `send-message-file`. Options are prefixed with two dashes if you use the full word, or a single dash if you use the single-letter abbreviation. For example `--help` or `-h`. There is no statement completion built in to the console, but there are some supported abbreviations for commands. These are not yet fully documented but are present in the Program.cs in the console source code.
16
-
17
-
### "Ports" vs "Streams"
18
-
19
-
In MIDI 1.0, specifically USB MIDI 1.0, a connected device would have a single input and single output stream. Inside that stream are packets of data with virtual cable numbers. Those numbers (16 total at most) identify the "port" the data is going to. Operating systems would then translate those into input and output ports. Those cable numbers were hidden from users.
20
-
21
-
MIDI 2.0 does not have a concept of a port. Instead, you always work with the stream itself. The group number, which is in the MIDI message now, is the moral equivalent of that cable number.
22
-
23
-
So where you may have seen a device with 5 input and 5 output ports in the past, you will now see a **single bidirectional UMP Endpoint stream** with 5 input groups and 5 output groups. We know this can take some getting used to, but it enables us to use MIDI 1.0 devices as though they are MIDI 2.0 devices, and provide a unified API.
24
-
25
-
### Help
26
-
27
-
Add the option `--help` or its short version `-h` to any command to get information and examples for that command.
28
-
29
-
```
30
-
midi --help
31
-
midi service --help
32
-
midi enumerate --help
33
-
midi enumerate endpoints --help
34
-
```
35
-
36
-
The `--help` option will always provide the most up-to-date list of commands and options supported by the MIDI Services Console.
37
-
38
-
## Check the MIDI Service Health
39
-
40
-
The heart of Windows MIDI Services is the Windows Service which processes and routes messages, creates endpoints, and more. The MIDI Services Console app includes a few commands to check the status and health of the service.
41
-
42
-
### Check MIDI Service Status
43
-
44
-
If you want to verify that the MIDI Service is running, you can check its status using the Service Control Manager, or through the MIDI Console.
45
-
46
-
```
47
-
midi service status
48
-
midi svc status
49
-
```
50
-
51
-
If you uset the `--verbose` or `-v` option, the console will display more information about the service.
52
-
53
-
```
54
-
midi service status
55
-
midi svc status
56
-
```
57
-
58
-
### Ping the Service
59
-
60
-
If you want to verify that the service is transmitting and receiving messages, you can use the ping command, much like you would
61
-
62
-
```
63
-
midi service ping
64
-
midi svc ping
65
-
```
66
-
67
-
This command also supports the `--verbose` or `-v` option to display the full results of the ping. It also supports a `--count` or `-c` parameter for the number of messages you want to send. Finally, the call supports a `--timeout` or `-t` parameter to set the timeout in milliseconds before the ping is considered to have failed.
68
-
69
-
Here are examples of the command with various parameters.
70
-
71
-
```
72
-
midi service ping --verbose
73
-
midi service ping --verbose --count 20 --timeout 20000
74
-
```
75
-
76
-
### Stop / Start / Restart the Service
77
-
78
-
The MIDI console has three commands for managing the Windows service. These can be useful when developing or debugging service-side plugins. Note that these must be run from an Administrator console session.
79
-
80
-
```
81
-
midi service stop
82
-
midi service start
83
-
midi service restart
84
-
```
85
-
86
-
## See the Current Timestamp and Frequency
87
-
88
-
If you want to see the MIDI clock we're using for timestamps and message scheduling, you can use the `time` command. It will display the current timestamp in ticks, and the number of ticks per second (the resolution)
89
-
90
-
```
91
-
midi time
92
-
midi clock
93
-
```
94
-
95
-
## Enumerate (List) MIDI Entities
96
-
97
-
A basic operation you may do with the tool is list the major entities (Endpoints and Plugins) in the system.
98
-
99
-
The enumerate command has the aliases `enum` and `list` which may be used instead of the full `enumerate` command.
100
-
101
-
### Enumerate MIDI UMP Endpoints
102
-
103
-
The `ump-endpoints` parameter has the alias `endpoints` and the alias `ump` so either may be used with the same results. These commands are all equivalent:
104
-
105
-
```
106
-
midi enumerate ump-endpoints
107
-
midi enumerate endpoints
108
-
midi enum endpoints
109
-
midi list endpoints
110
-
midi list ump
111
-
```
112
-
113
-
All of the above statements will return a list of all the user-focused UMP endpoints on the system.
114
-
115
-
> **Note:** There are loopback endpoints A and B that are always available and are built into the service. They are crosswired to each other so that any message sent to A is received on B, and vice versa. They cannot be removed or disabled. Because these are more for support, testing, and developer scenarios, they are not returned from enumeration calls by default. Instead, you would supply the `--include-loopback` option for the enumeration commands.
This uses the old WinRT API. Its primary reason for existance is so you can see what's shown to older APIs vs what is shown for the new Windows MIDI Services API. As with the UMP endpoints, the commands have aliases, so the following are all equivalent
120
-
121
-
```
122
-
midi enumerate bytestream-endpoints
123
-
midi enumerate legacy-endpoints
124
-
midi enum legacy-endpoints
125
-
midi list legacy
126
-
```
127
-
128
-
### Enumerate Transport Plugins
129
-
130
-
TODO: This feature is actively in development.
131
-
132
-
### Enumerate Message Processing Plugins
133
-
134
-
TODO: This feature is actively in development.
135
-
136
-
## Watch UMP Endpoints for Changes
137
-
138
-
Enumerating endpoints gives you a snapshot of the list at a moment in time. Watching the endpoints will give you a constantly updating list, which reflects device add/remove as well as property updates. This is useful more for developers, or those who are using tools to modify endpoints and want to verify that the changes were reported.
139
-
140
-
The `watch-endpoints` command has the alias `watch`, so these are equivalent:
141
-
142
-
```
143
-
midi watch-endpoints
144
-
midi watch
145
-
```
146
-
147
-
Note that only UMP endpoints (or bytestream endpoints converted to UMP by the new USB driver and service) are watched for changes. The older MIDI API is not used here. When you want to stop watching the endpoints for changes, hit the `escape` key.
148
-
149
-
## Single-Endpoint Commands
7
+
# Single-Endpoint Commands
150
8
151
9
There are a number of commands, including those for monitoring and sending messages, which operate on a single endpoint.
152
10
@@ -158,7 +16,7 @@ If you want to script the commands without requiring any user interaction, provi
In the Device Manager in Windows, you can only see a subset of properties for a device. The same goes with the `pnputil` utility. It can be useful to see all of the key properties of a MIDI Endpoint. Therefore, we've baked property reporting right into the MIDI Services Console.
As with other endpoint commands, if you provide the endpoint device Id, it will be used. Otherwise, you will be prompted to select an endpoint.
176
34
177
-
###Monitor an Endpoint for Incoming Messages
35
+
## Monitor an Endpoint for Incoming Messages
178
36
179
37
By default, every UMP Endpoint in Windows MIDI Services is multi-client. That means that more than one application can open a connection to the endpoint and send and/or receive messages. This also makes it possible to monitor all the incoming messages on an endpoint, even when that endpoint is in use by another application.
180
38
@@ -194,7 +52,7 @@ Verbose mode:
194
52
midi endpoint monitor --verbose
195
53
```
196
54
197
-
####Saving messages to a file
55
+
### Saving messages to a file
198
56
199
57
When monitoring, you also have the option to save the messages to a file. This can be used to capture test data which you will send using the `send-message-file` command, or for storing something like a System Exclusive dump.
200
58
@@ -211,7 +69,7 @@ If no file extension is specified, the extension `.midi2` will be automatically
211
69
212
70
When you have completed monitoring an endpoint, hit the `escape` key to close the connection and the app.
213
71
214
-
###Send a Message from the Command Line
72
+
## Send a Message from the Command Line
215
73
216
74
Sending a message to an endpoint is very helpful for testing, but can also be used in automation to, for example, change the current program, or set a MIDI CC value. It would be very easy for a person to build a batch file or PowerShell script which used midi.exe to synchronize different devices, or reset devices to a known state in preparation for a performance.
In general, we recommend sending messages in hexadecimal format (prefix `0x` followed by 8 hexadecimal digits)as it is easier to visually inspect the information being sent. The 1-4 MIDI words are in order from left to right, from 1 to 4.
239
97
240
-
####Special debug messages
98
+
### Special debug messages
241
99
242
100
One thing that can be useful is to send otherwise valid UMP messages where the last word is incremented by 1 for each sent message. This helps to validate that all messages were received by your application, and in the correct order. Note that this requires a message type of at least two words. We don't recommend sending Type F stream messages as those have the potential to corrupt data. Instead, a Type 4 MIDI 2.0 channel voice message is usually safer.
When sent, you should see messages where the second word is updated from `0x00000000` through `0x00002710` (decimal 10000). We recommend the pause when sending large numbers of messages because a pause of 0 ("send as fast as possible") can flood the buffers with more data than the client may be able to retrieve in time and may result in dropped messages. A warning is displayed when that possibility seems likely.
249
107
250
-
#### Scheduling messages
251
-
252
-
> NOTE: In current Developer Preview builds, message scheduling is turned off so the timestamp is ignored. Refer to the release notes.
108
+
### Scheduling messages
253
109
254
110
When sending messages, you have two options for timestamps:
255
111
@@ -271,7 +127,7 @@ Of course, you can also use the `midi time` command to see the current timestamp
271
127
272
128
Finally, if you do not specify a timestamp, the current time is used.
273
129
274
-
###Send a File full of Messages
130
+
## Send a File full of Messages
275
131
276
132
If you want to send a file full of messages, for SysEx or testing, for example, the console has provision for this.
# bunch of empty lines above. And the file ends with a comment
335
191
```
336
192
337
-
###Sending Endpoint Metadata Requests
193
+
## Sending Endpoint Metadata Requests
338
194
339
195
The MIDI Services Console also makes it possible to send some common stream request messages without having to remember their exact format.
340
196
@@ -344,7 +200,7 @@ These are primarily a convenience for developers.
344
200
345
201
Note that in all the request commands, you may abbreviate `request` as `req`
346
202
347
-
####Send a Function Block Request Message
203
+
### Send a Function Block Request Message
348
204
349
205
In the command, you may abbreviate `function-blocks` as `fb`, `functions`, `function` or `function-block`. The singular versions are available to make the command make more sense when requesting a single block's data.
Finally, note that you can provide a UMP version to send with the request. By default, the version is Major 1, Minor 1. The `--ump-version-major` and `--ump-version-minor` options are what you want to use here.
405
-
406
-
## Technical Information
407
-
408
-
The Windows MIDI Services Console app has been developed using C#, .NET 8, the MIT-licensed open source [Spectre.Console](https://spectreconsole.net/) library, and the Microsoft-developed open source [C#/WinRT](https://learn.microsoft.com/windows/apps/develop/platform/csharp-winrt/) toolkit.
409
-
410
-
The console uses the same Windows MIDI Services WinRT APIs available to other desktop applications. Its full source code is available [on our Github repo](https://aka.ms/midirepo). Pull-requests, feature requests, and bug reports welcome. The project is open source, but we request that instead of forking it to create your own version, you consider contributing to the project.
The `ump-endpoints` parameter has the alias `endpoints` and the alias `ump` so either may be used with the same results. These commands are all equivalent:
12
+
13
+
```
14
+
midi enumerate ump-endpoints
15
+
midi enumerate endpoints
16
+
midi enum endpoints
17
+
midi list endpoints
18
+
midi list ump
19
+
```
20
+
21
+
All of the above statements will return a list of all the user-focused UMP endpoints on the system.
22
+
23
+
> **Note:** There are loopback endpoints A and B that are always available and are built into the service. They are crosswired to each other so that any message sent to A is received on B, and vice versa. They cannot be removed or disabled. Because these are more for support, testing, and developer scenarios, they are not returned from enumeration calls by default. Instead, you would supply the `--include-loopback` option for the enumeration commands.
This uses the old WinRT API. Its primary reason for existance is so you can see what's shown to older APIs vs what is shown for the new Windows MIDI Services API. As with the UMP endpoints, the commands have aliases, so the following are all equivalent
28
+
29
+
```
30
+
midi enumerate bytestream-endpoints
31
+
midi enumerate legacy-endpoints
32
+
midi enum legacy-endpoints
33
+
midi list legacy
34
+
```
35
+
36
+
## Watch UMP Endpoints for Changes
37
+
38
+
Enumerating endpoints gives you a snapshot of the list at a moment in time. Watching the endpoints will give you a constantly updating list, which reflects device add/remove as well as property updates. This is useful more for developers, or those who are using tools to modify endpoints and want to verify that the changes were reported.
39
+
40
+
The `watch-endpoints` command has the alias `watch`, so these are equivalent:
41
+
42
+
```
43
+
midi watch-endpoints
44
+
midi watch
45
+
```
46
+
47
+
Note that only UMP endpoints (or bytestream endpoints converted to UMP by the new USB driver and service) are watched for changes. The older MIDI API is not used here. When you want to stop watching the endpoints for changes, hit the `escape` key.
0 commit comments