Skip to content

Commit

Permalink
Console docs updates
Browse files Browse the repository at this point in the history
  • Loading branch information
Psychlist1972 committed Feb 5, 2025
1 parent 3282f4c commit 98208ed
Show file tree
Hide file tree
Showing 6 changed files with 23 additions and 3 deletions.
20 changes: 20 additions & 0 deletions docs/console/endpoints.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,12 +10,16 @@ There are a number of commands, including those for monitoring and sending messa

In most any command which takes an Endpoint Device Id as a parameter, that parameter is optional. If you leave it out, and the command operates on a single endpoint, you will be prompted with a menu of available endpoints to work with.

![midi endpoint prompt](midi-endpoint-prompt.png)

If you want to script the commands without requiring any user interaction, provide the endpoint device ID as the first parameter after the `endpoint` command. For example:

```
midi endpoint \\?\SWD#MIDISRV#MIDIU_DIAG_LOOPBACK_B#{e7cce071-3c03-423f-88d3-f1045d02552b} properties --verbose
```

![midi endpoint help](midi-endpoint-help.png)

## Get Detailed Endpoint Properties

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.
Expand Down Expand Up @@ -52,6 +56,8 @@ Verbose mode:
midi endpoint monitor --verbose
```

![midi endpoint monitor verbose](midi-endpoint-monitor-verbose.png)

### Saving messages to a file

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.
Expand Down Expand Up @@ -190,6 +196,20 @@ F3345678h 12345678h 86754321h 86753099h
# bunch of empty lines above. And the file ends with a comment
```

## Easily play MIDI 1.0 or MIDI 2.0 Notes

To make it easy to send notes to an endpoint, the play-notes command accepts parameters including the note number and other information, and generates the appropriate channel voice messages at the appropriate times. The `--forever` switch has the messaging sending loop forever, making it useful for testing devices.

```
midi endpoint play-notes 50 55 52 60 72 90 --group 1 --channel 10 --velocity 100 --length 250 --rest 500 --forever
```

The parameters are all described when you type `midi endpoint play-notes --help`

This is not meant to be a sequencer with the kind of timing accuracy you would have in a DAW, but is instead a simple way to play notes on an endpoint.

![Play Notes](midi-endpoint-play-notes.png)

## Sending Endpoint Metadata Requests

The MIDI Services Console also makes it possible to send some common stream request messages without having to remember their exact format.
Expand Down
6 changes: 3 additions & 3 deletions docs/console/midi-console.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,15 +10,15 @@ If you have the midi console installed, you can invoke it from any command promp

## Where to Get it

While in developer preview, the Windows MIDI Services console is delivered as part of the developer preview installer. In the future, it will be delivered and serviced through the Microsoft Store on Windows
The Windows MIDI Services console is delivered as part of the SDK Runtime and Tools installer. While in preview, this is available on our [GitHub releases page](https://aka.ms/midireleases).

## General Information

### Commands vs Options

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.

### "Ports" vs "Streams"
### "Ports" vs "Endpoints"

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.

Expand All @@ -34,7 +34,7 @@ If you want to see the MIDI clock we're using for timestamps and message schedul
midi time
midi clock
```
![MIDI Clock Command](./midi-clock.png)
![MIDI Clock Command](midi-clock.png)

## Technical Information

Expand Down
Binary file added docs/console/midi-endpoint-help.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/console/midi-endpoint-monitor-verbose.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/console/midi-endpoint-play-notes.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/console/midi-endpoint-prompt.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 98208ed

Please sign in to comment.