MIDI Console

This page covers information about a Windows MIDI Services feature and application that will be released to consumers in November 2026. It’s currently available for developers.

The Windows MIDI Services Console is a command-line tool for listing, inspecting, monitoring and testing MIDI endpoints. It can also set up loopbacks, control the built-in General MIDI synthesizer, connect Bluetooth MIDI devices and report on network MIDI. If you have it installed, you can run it from any command prompt by typing midi. We recommend Windows Terminal for the best experience.

This page documents every command and option. To get the same information at the command line, add --help to any command.

Where to get it

The console is installed with the Windows MIDI Services SDK Runtime and Tools package. Developers and technical users can download the latest preview release from GitHub.

Commands, arguments and options

• Commands are words with no dashes in front, such as endpoint or send-message-file. Some commands have more commands under them, as in midi endpoint monitor.
• Arguments are values that come after a command, such as a file name or an endpoint device id.
• Options start with two dashes for the full name, such as --verbose, or one dash for the one-letter short form, such as -v.

Most commands and many options have shorter aliases. They’re listed with each command on this page.

Type commands and options in lowercase. The console doesn’t recognize Enumerate or --Verbose.

Some options are on unless you turn them off. The tables on this page show On in the Default column for those, and each one has a --no- form that turns it off, such as --no-decode-messages.

Getting help

Add --help or -h to any command to see its description, examples, arguments and options. --help-all shows the help for every command at once.

midi --help
midi endpoint --help
midi endpoint monitor --help
midi --help-all

The help always matches the version you have installed, so it’s the one to trust if this page and the console ever disagree.

“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 in typical implementations) 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 by the concept of a port.

MIDI 2.0 does not have the 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. Like the virtual cable, it helps address where the message is being sent.

So where you may have seen a device with 5 input and 5 output ports in the past show up as 10 discrete ports, 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.

Specifying an endpoint

Most commands under midi endpoint work with one endpoint. To say which one, put its endpoint device id after the command name. Put the id in quotes, because PowerShell treats the { and } in it as special characters.

midi endpoint properties "\\?\swd#midisrv#midiu_loop_a_default#{e7cce071-3c03-423f-88d3-f1045d02552b}"

The general form is:

midi endpoint <command> [Endpoint Device Id] [OPTIONS]

To find an endpoint’s id, run midi enumerate endpoints --show-endpoint-id.

If you leave the id out, the console shows a list of endpoints to pick from. Use the up and down arrow keys to move, Enter to choose, and Esc to cancel.

In a script, always give the id, so the script doesn’t stop and wait for someone to pick from the list. When the console’s output goes to a file or another program instead of the screen, it can’t show the list, so a command without an id stops with an error.

send-message, send-message-file and play-notes take the id as an option instead, --endpoint-id, because they already take a list of words, a file name or a list of notes.

midi endpoint play-notes 60 64 67 --endpoint-id "\\?\swd#midisrv#midiu_loop_a_default#{e7cce071-3c03-423f-88d3-f1045d02552b}"

Scripts written for earlier versions of the console put the id straight after endpoint, as in midi endpoint "<id>" properties. That still works with every endpoint command.

Command summary

Enumerate

Lists what’s on this PC. The enumerate command has the aliases enum and list, so midi enumerate endpoints, midi enum endpoints and midi list endpoints all do the same thing.

enumerate midi-services-endpoints

Aliases: endpoints, ump-endpoints, ep

Lists the MIDI endpoints that apps using Windows MIDI Services can see.

midi enumerate midi-services-endpoints --include-diagnostic-loopback
midi enumerate endpoints
midi list endpoints --show-endpoint-id
midi enum ep

Note: The MIDI service has two built-in diagnostic loopback endpoints, Service Test Loopback A and Service Test Loopback B. Anything sent to A arrives at B, and anything sent to B arrives at A. They’re always there and can’t be removed or turned off. Because they’re for testing and support, they aren’t listed unless you add --include-diagnostic-loopback. See About the Diagnostics Endpoints Transport.

enumerate legacy-winrt-api-endpoints

Aliases: legacy-endpoints, bytestream-endpoints, legacy, winrt1

Lists the MIDI 1.0 ports Windows MIDI Services creates, the way apps using older MIDI APIs see them. Use it to compare what older apps see with what newer apps see.

It lists only the ports that come from the MIDI service. Ports from older MIDI drivers, and the older Microsoft GS Wavetable Synth, aren’t included. The numbers are the real WinMM port numbers, so there may be gaps.

midi enumerate legacy-winrt-api-endpoints --direction Destination
midi enumerate legacy --include-endpoint-id
midi list legacy-endpoints

enumerate active-sessions

Alias: sessions

Lists the apps and services that have a Windows MIDI Services session open right now, and the endpoints each one is connected to.

midi enumerate active-sessions
midi enumerate sessions --all

enumerate transport-plugins

Alias: transports

Lists the MIDI transports installed on this PC. A transport is the part of Windows MIDI Services that works with one kind of connection, such as USB, Bluetooth, the network or loopbacks.

midi enumerate transport-plugins
midi enumerate transports --verbose

enumerate endpoint-property-keys

Alias: property-keys

Lists the property keys Windows MIDI Services adds to endpoints. This command has no options beyond --help.

midi enumerate endpoint-property-keys
midi enumerate property-keys

Endpoint

Commands that work with a single endpoint. The endpoint command has the alias ep. To say which endpoint, see Specifying an endpoint.

endpoint monitor

Alias: listen

Shows messages as they arrive at an endpoint. Press Esc to stop. While it’s running, press C to type a comment, which is added to the list of messages so you can mark what you were doing at the time.

Endpoints in Windows MIDI Services can be used by more than one app at once, so you can monitor an endpoint while another app is using it.

The verbose view is wide. Make the window wide enough that each message fits on one line.

midi endpoint monitor
midi endpoint monitor --verbose
midi endpoint monitor --include-real-time-messages --no-decode-messages

Saving messages to a file

The monitor can save what it receives to a file as well as showing it. This is handy for recording test data or a System Exclusive dump.

midi endpoint monitor --capture-to-file %USERPROFILE%\Documents\MyCapture.txt --annotate-capture
midi endpoint monitor --capture-to-file %USERPROFILE%\Documents\MyCapture.mid --capture-format smf

There are three formats:

• ump, the default, writes each message as its 32-bit words, one message per line. You can send a ump capture again later with send-message-file.
• csv writes one row per message under a heading row, for opening in a spreadsheet.
• smf writes a Standard MIDI File, which DAWs and MIDI file players can open.

A ump or csv capture is added to the end of the file if the file already exists. Check the file name before you start, so you don’t add MIDI data to an unrelated file. An smf capture replaces the file instead.

The file name can include environment variables such as %USERPROFILE%. Press Esc to stop monitoring and close the file.

endpoint properties

Aliases: props, information, info

Lists what Windows knows about an endpoint: its name and id, its transport, its MIDI 2.0 details, its function blocks and MIDI 1.0 ports, the device it belongs to, and which apps are using it. Device Manager and pnputil show only some of this.

midi endpoint properties
midi endpoint properties --verbose

endpoint send-message

Aliases: send-ump, send

Sends one message, written as one to four 32-bit MIDI words.

Argument: the MIDI words, usually written in hexadecimal like 0x21234567, in the same order they’re sent.

The console doesn’t check the message beyond its type, the first 4 bits, so the rest can be anything. The number of words has to match the message type, though, as the MIDI 2.0 specification says.

midi endpoint send-message 0x21234567
midi endpoint send-message 0x41234567 0xDEADBEEF --count 10
midi endpoint send-message 0x41234567 0xDEADBEEF --count 15 --pause 2000

We recommend writing messages in hexadecimal, because it’s easier to see what you’re sending. The one to four words go in order from left to right.

Special debug messages

Sending messages whose last word goes up by 1 each time helps you check that your app received all of them, in the right order. The message needs at least two words. We don’t recommend Type F stream messages, because they can confuse the device or the service. A Type 4 MIDI 2.0 channel voice message is usually safer.

midi endpoint send-message 0x41234567 0x00000000 --count 10000 --pause 2 --debug-auto-increment

You should see the second word count up from 0x00000000 to 0x0000270F (9,999). We recommend a pause when you send a lot of messages. With a pause of 0, messages can arrive faster than the app reading them can keep up, and some may be lost.

Scheduling messages

--offset-microseconds schedules each message a fixed time in the future. Offsets are in microseconds so you can be more precise than with milliseconds.

midi endpoint send-message 0x41234567 0xFEEDF00D --offset-microseconds 2000000

You can also give an exact timestamp. Most often that’s 0, which skips scheduling and sends right away.

midi endpoint send-message 0x41234567 0xFEEDF00D --timestamp 0

Run midi time to see the current timestamp, and use that to pick one in the future. If you don’t give a timestamp, the current time is used.

endpoint send-message-file

Aliases: send-ump-file, send-file

Sends a text file of messages to an endpoint, one message per line.

Argument: the file to send. Lines that start with # are comments, and blank lines are skipped. Every other line is one message, written as 32-bit words. The file name can include environment variables such as %USERPROFILE%.

midi endpoint send-message-file %USERPROFILE%\Documents\SysExBank12.txt --new-group-index 5

Here’s one of the test files we use. It shows comments, different ways of writing numbers, different delimiters and more.

# This is a test file for sending UMPs through Windows MIDI Services
# It uses auto for the field delimiter so we can have different
# delimiters on each line. Numeric format for this file is always hex.

# The line above was empty. The next data line is a UMP32

0x22345678

# The messages aren't valid beyond their message type matching the number of words

0xF1345678 0x12345678 0x03263827 0x86753099
0xF2345678,0x12345678,0x86754321, 0x86753099
0xF3345678|0x12345678|       0x86754321|0x86753099

0x21345678
0x42345678 0x12341234
0x26989898

# The next two lines have different hex formatting

41345678h 12341234h
22989898h

# The next lines have no hex formatting

41345678 12341234
22989898

# And the file ends with a comment

endpoint play-notes

Alias: play

Sends MIDI 1.0 or MIDI 2.0 note on and note off messages to an endpoint. It isn’t meant to be a sequencer with the timing you’d get in a DAW. It’s a quick way to play some notes on an endpoint.

Argument: the notes to play, as MIDI 1.0 note numbers from 0 to 127, separated by spaces.

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

endpoint send-beat-clock

Aliases: send-clock, clock

Sends MIDI beat clock to an endpoint until you press Esc. Devices that follow MIDI clock, such as drum machines and sequencers, play along at this tempo. The MIDI service schedules each clock pulse ahead of time, so the tempo stays steady even when the PC is busy.

midi endpoint send-beat-clock --group 1
midi endpoint send-beat-clock --group 1 2 --tempo 98.5 --send-start --send-stop

endpoint send-time-code

Aliases: send-mtc, time-code, mtc

Sends MIDI Time Code (MTC) to an endpoint until you press Esc. Recorders, video software and some sequencers follow time code to stay in sync.

midi endpoint send-time-code --group 1
midi endpoint send-time-code --group 1 --frame-rate 25 --begin-at 01:00:00:00

endpoint customize

Changes how an endpoint appears and behaves in Windows: its name, description and picture, how its MIDI 1.0 ports are named, and a few MIDI settings. Changes are saved and applied every time the device is connected, unless you add --temporary. Not every kind of endpoint can be customized, and the console tells you when one can’t.

midi endpoint customize --name "Studio Synth" --description "The synth in the rack by the window"
midi endpoint customize --port-naming group
midi endpoint customize --clear

endpoint customizations

Windows MIDI Services keeps the customizations you’ve saved for each device, even while the device is unplugged. These commands list them, and move or delete ones that no longer match a device, for example after a firmware update changed how a device identifies itself. For when that happens and what to do about it, see When saved endpoint settings do not match a device.

endpoint customizations list

Lists the stored customizations, with the stored id the other two commands need.

endpoint customizations relink

Moves a stored customization onto a different endpoint.

endpoint customizations forget

Deletes a stored customization.

midi endpoint customizations list --orphaned
midi endpoint customizations relink --from <stored id> --to "<endpoint device id>"
midi endpoint customizations forget --from <stored id>

endpoint short-id and endpoint full-id

Alias for full-id: long-id

Endpoint device ids are long. The short form leaves out the parts that every id shares, so it’s easier to read. short-id prints the short form of an id, and full-id turns a short form back into the full id. The other commands on this page need the full id.

Leave the id out to pick an endpoint from the list.

midi endpoint short-id "\\?\swd#midisrv#midiu_diag_loopback_b#{e7cce071-3c03-423f-88d3-f1045d02552b}"
midi endpoint full-id diag_loopback_b

Endpoint request

Sends MIDI 2.0 stream request messages without you having to remember their exact format. These are mostly for developers, and for checking MIDI 2.0 hardware. The request command has the alias req.

Before you send a request, you may want another console window running midi watch-endpoints, so you can see when the stored properties change. A midi endpoint monitor --verbose window lets you see the reply messages come back.

endpoint request function-blocks

Aliases: function-block, fb, function, functions

Asks the endpoint for its function blocks. The singular aliases read better when you ask for just one block.

By default you get both the information and the name. To get only one, turn the other off with its --no- option. You have to ask for at least one.

midi endpoint request function-blocks --all
midi endpoint request function-blocks --function-block-number 3
midi endpoint request function-blocks --all --no-request-name
midi endpoint request function-blocks --all --no-request-info

endpoint request endpoint-info

Aliases: endpoint-metadata, endpoint-data, em, metadata

Sends an endpoint discovery message to the endpoint.

midi endpoint request endpoint-info --all
midi endpoint request endpoint-info --device-identity --product-instance-id
midi endpoint request metadata --name --no-endpoint-info

Forward

Alias: bridge

Forwards every message from one endpoint and group to another endpoint and group, until you press Esc. Anything you leave out, you pick from a list.

Messages keep their timestamps. Messages that don’t belong to a group, such as utility and stream messages, aren’t forwarded. For routing you want to leave running, use Windows MIDI Patchbay.

midi forward
midi forward --source-group 1 --destination-group 10

SysEx

Alias: system-exclusive

Sends and receives MIDI 1.0 System Exclusive (SysEx) files, such as patch dumps. For a window with buttons instead, use Windows MIDI SysEx Utility.

sysex send-file

Alias: send

Sends a file of MIDI 1.0 SysEx bytes, usually a .syx file, to an endpoint. The bytes are sent as Universal MIDI Packet (UMP) SysEx 7 messages.

Arguments: the file to send, then the optional endpoint device id.

Older devices can lose data that arrives too fast. If a transfer fails, or the device ends up with garbage in it, lower --message-transfer-count, raise --pause, and try again.

midi endpoint send-sysex-file and midi endpoint send-sysex, from earlier versions of the console, still work and do the same thing.

midi sysex send-file .\patch.syx
midi sysex send-file .\patch.syx --group 1 --pause 20

sysex receive-file

Alias: receive

Waits for SysEx from an endpoint and writes it to a file. It stops when nothing has arrived for the timeout, or when you press Esc.

Arguments: the file to write, then the optional endpoint device id.

midi sysex receive-file .\dump.syx
midi sysex receive-file .\dump.syx --overwrite

Loopback endpoints

Loopbacks connect apps on the same PC. What one app sends into a loopback comes out for another app to receive. Loopbacks you create with the console last until the MIDI service restarts, unless you add --save-to-config. Windows MIDI Loopback Setup does the same things with buttons, and explains which kind to choose.

Every loopback needs its own name. To mute or remove one, you need its association id, which list shows and create prints.

loopback

Aliases: midi2-loopback, bidirectional-loopback

A MIDI 2.0 loopback is a pair of endpoints, A and B. What’s sent to A arrives at B, and what’s sent to B arrives at A. Each pair also gets MIDI 1.0 ports.

loopback list

Lists the MIDI 2.0 loopback pairs that exist right now, with each pair’s association id. This command has no options beyond --help.

loopback create

midi loopback create --name-a "My Loopback A" --name-b "My Loopback B"
midi loopback create --root-name "My Loopback" --save-to-config

loopback remove

Alias: delete

midi loopback remove --association-id "{bb872b25-bc38-4009-a85a-559824398a13}" --save-to-config

loopback mute and loopback unmute

mute stops messages going through a loopback without removing it, so apps keep their connections. unmute lets messages through again.

midi loopback mute --association-id "{bb872b25-bc38-4009-a85a-559824398a13}"
midi loopback unmute --association-id "{bb872b25-bc38-4009-a85a-559824398a13}"

basic-loopback

Aliases: midi1-loopback, simple-loopback

A basic loopback is a single endpoint whose output comes straight back in as its input, the way older loopback drivers work. It has the same list, create, remove, mute and unmute commands as loopback. remove has the alias delete.

basic-loopback create takes these options:

remove, mute and unmute take --association-id (-i), and remove also takes --save-to-config (-s), the same as for loopback.

midi basic-loopback list
midi basic-loopback create --name "My Loopback" --save-to-config
midi basic-loopback remove --association-id "{bb872b25-bc38-4009-a85a-559824398a13}" --save-to-config

Synth

Aliases: gm-synth, synthesizer

Controls the General MIDI synthesizer built into Windows MIDI Services. For what it plays and what each setting does, see About the in-box General MIDI synthesizer.

enable, disable and configure take --temporary (-t), which applies the change now without saving it, so it’s undone when the MIDI service restarts.

synth configure changes only the settings you give it:

midi synth status
midi synth configure --synth-mode modern
midi synth configure --audio-mode sharedLowLatency
midi synth disable --temporary

Network MIDI 2.0

Aliases: net, network-midi

Reports on Network MIDI 2.0. These commands only show information. To set up connections, use Windows MIDI Network Setup.

Every command except pending takes --verbose (-v) for more details.

midi network browse --verbose
midi network status

RTP-MIDI

Aliases: rtp-midi, rtpmidi

The same reports for RTP-MIDI, the older network MIDI protocol that Apple devices and many network MIDI interfaces use. These commands need the RTP-MIDI transport to be installed.

Every command except pending takes --verbose (-v) for more details.

midi rtp browse
midi rtp status --verbose

Bluetooth

Alias: ble

Works with Bluetooth LE MIDI devices. Windows MIDI Bluetooth Setup does the same things with buttons.

bluetooth list and bluetooth status

bluetooth list (alias list-devices) lists the Bluetooth MIDI devices Windows has found, with the Bluetooth device id the other commands need. bluetooth status (alias radio) reports on the Bluetooth radio and the Bluetooth MIDI transport, and lists any device waiting for your approval.

bluetooth connect

Connects to a device and creates a MIDI endpoint for it.

Argument: the Bluetooth device id, from bluetooth list.

bluetooth disconnect

Disconnects a device and removes its MIDI endpoint.

Argument: the Bluetooth device id, from bluetooth list.

bluetooth customize

Sets the name, description and picture shown for a device.

Argument: the Bluetooth device id, from bluetooth list.

midi bluetooth list
midi bluetooth connect <bluetooth device id>
midi bluetooth customize <bluetooth device id> --name "Stage Keyboard" --keep-when-offline always
midi bluetooth disconnect <bluetooth device id> --forget

bluetooth peripheral

Publishes this PC as a Bluetooth MIDI device, so a phone, tablet or another computer can connect to it.

start, stop and customize take --temporary (-t), which doesn’t save the change, so it’s undone when the MIDI service restarts.

approve, deny and forget take the twelve-digit Bluetooth address of the device that connected to this PC. approve and deny also take --scope (-s), which says how long the decision lasts: once, the default, untilRestart or always.

midi bluetooth peripheral start --protocol midi2
midi bluetooth peripheral approve 0123456789AB --scope always

Service

Alias: svc

The midi service command reports on the MIDI service, which helps when you’re troubleshooting.

Note: Starting, stopping, restarting, and changing the start type of the MIDI service are standard Windows service management operations, and are no longer part of the MIDI Console. Use the built-in Windows tooling for those tasks: the Services applet (services.msc), sc.exe, or the PowerShell Start-Service, Stop-Service, Restart-Service, and Set-Service cmdlets. For example, sudo pwsh -c "Restart-Service MidiSrv".

service status

Checks whether the MIDI service is running, and shows how it starts.

midi service status
midi svc status --verbose

service ping

Pings the MIDI service through its ping endpoint, and reports how long the round trips took.

midi service ping --verbose
midi service ping --count 50 --timeout 20000

Watching for changes

Listing gives you a snapshot at one moment. Watching gives you a list that keeps up as endpoints are added and removed and their properties change. This is useful for developers, and for checking that a change you made with another tool was reported.

To stop watching, press Esc.

watch-endpoints

Alias: watch-ump

Watches endpoints being added, removed and changed.

midi watch-endpoints
midi watch-ump --include-loopback

watch-ports

Alias: watch-legacy

Watches MIDI 1.0 ports being added, removed and changed.

midi watch-ports
midi watch-legacy --verbose

Time

Alias: clock

Shows the current MIDI clock timestamp, how many ticks there are in a second, and the Windows timer settings that affect timing. This command has no options beyond --help.

midi time
midi clock

API mode

Alias: mode

Windows can run MIDI in three modes. Most PCs should stay in the full Windows MIDI Services mode. Before you change it, read How to change the MIDI API mode for what each mode gives you and takes away.

midi api-mode get
midi api-mode set full

In legacy mode, Windows MIDI Services isn’t running, so every other console command stops with an error. api-mode and --help still work, so you can switch back.

Technical information

The console is written in C++ using C++/WinRT, and the open source CLI11, {fmt} and FTXUI libraries.

It uses the same Windows MIDI Services API that other apps use. Its full source code is available on our GitHub repo. Pull requests, feature requests and bug reports are welcome. The project is open source, but instead of forking it to make your own version, please consider contributing to the project.