Control your rig from your Stream Deck

1 What you need

• A Stream Deck — any model (Mini, MK.2, XL, Neo, Stream Deck + or + XL, Studio, Pedal, or Mobile).
• The Stream Deck app installed (Elgato, free).
• Windows: a virtual MIDI port — the free loopMIDI.macOS: nothing extra to send — MIDIRover creates its own port automatically. For the optional Feedback input it needs a two-way bus: switch on an IAC Driver bus in Audio MIDI Setup. MIDIRover's own port can be listened to, but nothing can send into it.
• The software you want to control — Neural DSP (any plugin), another amp sim, a synth, or a DAW that accepts MIDI.

2 Install & first run

3 Core concepts

MIDI port

The virtual cable between MIDIRover and your software. One port is shared across all your keys — set it once.

Channel

MIDI has 16 channels (1–16). Your key and your software must agree on the channel. Most setups leave everything on channel 1. New keys default to the channel you last picked, so once you move your rig to, say, channel 2, every key you add follows automatically.

CC, Program, Note

The three everyday message types. CC = a knob/switch (0–127). Program = recall a preset. Note = a musical note on/off.

MIDI Learn

Most plugins have a “MIDI Learn” mode: you arm a control, send it a message, and it binds. MIDIRover sends the message — you press the key to teach your plugin.

Colour theme

A shared Deck theme recolours every MIDIRover key and dial at once — pick one of six presets, or set your own two colours, in any action's settings. Each key can also override it: its This key setting follows the deck theme by default, or takes its own preset or custom colour, handy for colour-coding by function. The second box on both rows sets the key background — dark (the default) or light — deck-wide or per key; presets adjust their colours per background so both stay readable, and on light keys the key's Name is drawn in black as part of the face. (The dial's touch-strip visuals and built-in value bar keep their system look.)

4 Actions reference

Drag any of these onto a key (or a dial, on a Stream Deck + / + XL). Give it a Name to label the key — or leave it empty, and the key names the message it sends: CC22 ch1, PC22 ch1, C4 ch1, or a Bank pair’s id and channel like A ch1. If you have already named that CC, program or note in its dropdown, the key uses that name instead, so you never type it twice — on every key type, dials included. A Bank key is the one that needs a word of explanation: in its usual Program Change mode it does not sit on one preset, it walks a range, so the preset name appears on the key’s value line as the counter reaches it (Lead instead of 3) while the top line keeps the A ch1 that tells one counter from another. In Control Change mode there is one controller, so its name goes on the name line with the id kept: Drive A. The box beside Name sets its font size in px — 10 to 30, 22 by default. MIDIRover draws the label into the key face itself, so it always matches the key's colours and its light or dark background. The Stream Deck app's own Title field still works and draws on top in whatever font and colour you choose — so use one or the other, or the label appears twice.

5 Learning Mode

The fast way to set up a key — no typing CC numbers. Available on Control Change, Note, and MIDI Dial.

6 Naming values

Give channels, CCs, programs and notes friendly names so the dropdowns read 22 · Drive instead of just 22.

• Type a name in the small field next to a Channel / CC / Program / Note dropdown.
• Names are shared across every key that offers that dropdown, so you label a value once — and every list of channels, CC numbers, programs or notes shows them, including the three you cannot type a name into. Those three are read-only for three different reasons. The MIDI Readout key’s Number list is the same field for a CC number or a note number depending on what the key is watching, so there is no one list to rename into — it reads both, following Watch. The Panic key’s Send on list is a target selector with an All channels option rather than a plain channel dropdown, so it shows the name of the gear on each channel and nothing more. The MIDI Monitor key’s Channel list is a filter on what arrives, and a name there tells you whose traffic you are watching. In all three, renaming stays on the keys that actually address a channel, a controller or a note. One more thing worth knowing about channel names in particular: they show in every list — each panel’s Channel row, the Monitor’s filter, Panic’s destination list — and never on a key face. An unnamed key names the message it sends (CC127 ch16), and that form is already at the ten-character limit the key face allows, so there is no room for a name as well; the number is the half you cannot do without.
• CC and program names are scoped per channel — CC 22 on channel 1 and channel 2 keep separate names and never mix. Note names are global, since a note number means the same thing on every channel.
• Names in brackets are ours, not yours. Where MIDI already has a name for a control number, the list shows it in brackets — 6 · (Data Entry MSB), 120 · (All Sound Off)— so you can tell at a glance which values you have actually named. Type your own name for one and the brackets go: 6 · Gain. Every list follows this, the read-only ones included, so the same number reads the same way wherever you meet it. Note names have no brackets, because 60 really is C4 on any gear, while a control-number name only describes what the protocol does with it.
• Note names start from the musical name (60 · C4) and you can replace it — 36 · Kick is the usual reason. Which octave numbering those built-in names use is a single global choice under Naming on any Note key: Middle C = C4 for Roland gear and most DAWs, C3 for Yamaha, or C5, which suits a few older sequencers. It changes the label only; the note number sent never changes.
• Name map — import a whole set of names at once, rather than typing them one at a time. Any key that offers naming has this row; the names are shared, so it does the same thing wherever you open it.MIDI Map Studio can build one for you from a Neural DSP mapping file: under Names for MIDIRover, press Copy name map. A map is also plain JSON, so anyone can write one by hand or share theirs. You can paste it in either of two notations. A name-map JSON document is what Map Studio copies and what one machine hands another. For typing by hand there is a plainer form, which needs no brackets, quotes or commas:

  # my rig
  [channel 1]
  name = Amp
  cc 22 = Drive
  program 0 = Clean
  
  [notes]
  36 = Kick

  Sections are [channel N] and [notes]; a line is what = name;# starts a comment and blank lines are ignored. Case does not matter, : works as well as =, and pc or prog mean program. If a line cannot be read, the import is refused whole and names the line — which is the reason this form exists, because a JSON error can only point at a character. You do not need this page to hand: the panel shows an example of both notations — press the small ? beside the buttons — each with a button that copies it, ready to edit. Press Import — it merges: a name the document does not mention is left exactly as it was, so importing a map for one device never costs you the names you typed for another. A document that is not a name map, or is from a newer version of MIDIRover, is refused whole and nothing changes — you are told which, rather than being left with half a map applied. What you pasted stays in the box so you can correct it. Two more documents are refused for the same reason, and both matter most if you aregenerating a map rather than typing one: a blank name (a name with no text in it would quietly delete the name that was there, so leave the entry out instead, or use Clear), and thesame number written twice in one section — 7 and 07 are the same controller, and a document that names it twice is saying two things about one address. Leading zeros themselves are fine: cc 07 and cc 7 mean the same thing, in either notation. A third refusal joins those two: a name containing a character with nothing to draw — a control character, a text-direction override, a zero-width space. These are invisible, so a name carrying one cannot be read, retyped or told apart from the name beside it, and a tool that pads or converts text is the usual way one arrives. MIDIRover names the character it found and the line it is on, so you can fix the document at the source. Ordinary text is untouched: spaces, punctuation, accented letters and non-Latin scripts are all names — Bank P3,Amp Ch. 2 and リード all import. The last refusal is length: a name can be up to 40 characters. That is not a limit invented for imports — it is the longest name the panel already lets you type into a key’s Namebox, and the rename boxes stop at 24, so a longer one in a document is asking for something you could not have created by hand. A key shows roughly a dozen characters anyway. As with every other refusal, MIDIRover says which name and how long it was, and changes nothing — it will not quietly shorten a name, because that would rewrite a document you may be sharing with someone else.Export goes the other way: it reads out the names you have already typed, into the same box and selected, so Ctrl+C copies them. That is how a set of names you built by hand leaves this computer — to keep, to move to another machine, or to give to someone with the same gear. One thing an export does not carry is a source block saying where the names came from, and that is deliberate: your profile is whatever you have merged — perhaps a pack for one device, a pack for another, and a dozen names you typed — so no single origin would be true of the result. If you are putting together a pack to share, add that block to the exported document by hand.Clear removes them all. Because importing merges, names from two different rigs otherwise accumulate with no way to separate them — Clear is how you start again. It asks twice (the button becomes Really clear?, and waiting cancels), tells you how many it removed, and touches nothing but names: your MIDI port, your remembered channel, your colours and your Middle C setting all stay. Export first if you might want them back — that copy is the only undo. One thing to expect: keys on other pages keep showing their old names until you next open those pages. MIDIRover can only redraw the keys the deck is currently showing, and a key redraws itself correctly the moment it appears. An import also tells you if the map renames one of MIDI’s own control numbers — CC 120All Sound Off, CC 0 Bank Select and a handful of others. It still imports, because plenty of gear really does drive its own parameters from those numbers; it is worth knowing because on most gear they do something structural rather than setting a value.

7 Neural DSP quick-start

8 Troubleshooting

Nothing happens when I press a key

Open any MIDIRover key’s settings and read the line under MIDI Port — it names the port and says whether anything is leaving the plugin at all. Red: nothing is being sent, and the line says why. Amber: MIDI is going somewhere other than the port this key is set to. Grey: MIDIRover is sending where you meant, so the problem is downstream — check that loopMIDI is running (Windows), that your software’s MIDI input is the same port, and that the channel matches on both sides. Opening the settings is worth doing on its own: it makes MIDIRover re-check the port and reopen it.

MIDIRover has gone grey — the Stream Deck app has disabled it

This is not a licence problem, a broken install, or anything to do with your MIDI setup: it means MIDIRover failed to start, and the app has stopped trying. A plugin that dies while starting is relaunched automatically every few seconds, and after twelve failed launches the app gives up and greys it out — so this appears a couple of minutes after the first failure rather than the moment something goes wrong. It is nearly always a machine still waking up: MIDIRover waits and retries while the app starts, and the disable only lands when whatever it is waiting for takes longer than that.

The way back is to restart the Stream Deck app for real. The disabled mark lives in the running app and is written nowhere on disk, so a genuine restart always clears it — there is nothing to repair, nothing to reinstall, and no reason to delete your keys. What does not work is closing the window: the app keeps running in the Windows notification area (or the macOS menu bar), and MIDIRover stays grey however many times you bring the window back. Quit it properly — right-click the tray icon and choose Quit on Windows, or Quit Stream Deck from the menu bar on macOS — then start it again. If the actions are still grey after that, the app never really quit; restarting the computer is the sure way and costs less than it sounds, because your keys and their settings are stored and come back exactly as they were.

If it keeps happening, the file to send is startup-error.log — MIDIRover writes it beside its own bundle, in the bin folder of its plugin folder (%appdata%\Elgato\StreamDeck\Plugins\com.midirover.plugin.sdPlugin\bin on Windows, or ~/Library/Application Support/com.elgato.StreamDeck/Plugins/com.midirover.plugin.sdPlugin/bin on macOS). That file is the only artifact this failure leaves: the ordinary MIDIRover log is empty, because the plugin never got far enough to open it. Send startup-error.log and say what the machine was doing at the time — waking from sleep, first login, a fresh install — and that is enough to work from.

Where the log file is, and what to send if you report a problem

MIDIRover writes a log beside the plugin, and on Windows the real file lives at %LOCALAPPDATA%\midirover-logs — paste that into the address bar of any Explorer window. (The logs folder inside the plugin itself is a shortcut to the same place; it is arranged that way so the log is never inside a synced folder, where it would be locked or duplicated.) On macOS the log sits in the plugin’s own logs folder under the Stream Deck app’s Plugins directory. Take the newest file: the log rotates every time the plugin restarts, so the one you want is usually .0.log, and timestamps inside it are UTC rather than your local clock. If you are reporting something, the last hundred lines around the moment it went wrong are far more useful than the whole file — and a MIDI Monitor key on screen at the time answers “did anything arrive at all”, which the log alone often cannot.

The plugin isn’t receiving in Neural DSP

Confirm the channel matches on both sides, and that you MIDI-Learned the right control. Watch incoming MIDI with a monitor if unsure.

I can’t find the MIDI Dial action

The dial actions need a model with dials; the Stream Deck + and + XL are the two Elgato documents with a touch strip to display the value on. On other models the dial action is hidden by design — use the key actions (e.g. CC Sweep mode to ride by hand).

The port is there, opens fine, and nothing crosses it

A loopMIDI port created — or re-created — while other apps already held loopMIDI ports open can come up listed but non-functional. Every screen looks correct and no error appears anywhere; the only tell is a MIDI monitor showing zero traffic. Restart loopMIDI (quit it fully and reopen) — you don’t need to restart the Stream Deck app, because MIDIRover notices the port coming back and reopens by itself. Re-adding the port while apps are attached often reproduces it. Seen twice on one Windows machine. Detail in the troubleshooting guide.

I deleted and re-created a virtual port — do I need to restart?

No. If the port disappears and comes back, MIDIRover notices within about three seconds and reopens both its MIDI output and its Feedback input by itself, with nothing to touch. (That is for a port you picked by name. If you left the port on Auto, MIDIRover picks again on your next key press rather than in the background.)

My port vanished from loopMIDI — why does the key still look fine?

It shouldn’t any more. Open any key’s settings and the line under MIDI Port turns red and names the port that went missing, and the dropdown shows it marked (not present). MIDIRover deliberately does not switch you to some other device when your saved port disappears — quietly rerouting a rig into whatever else happens to be plugged in is worse than sending nothing — so nothing is sent until the port returns (it reopens by itself) or you pick another one. Re-create it in loopMIDI with the same name and it reconnects on its own. If the port is gone for good — renamed, or a device you no longer have — choose Auto at the top of the dropdown: that releases the saved name and lets MIDIRover pick again.

Windows: no ports listed

Open loopMIDI and create at least one port, then reopen the key settings so the list refreshes.

None of the above — it still doesn’t work

That is worth telling me about: an unexplained failure here is a bug in MIDIRover or a gap in this manual, and both are mine to fix. Report it with what you pressed, what you expected, and what the line under MIDI Port says — those three sentences are usually enough to identify it.

The key shows a fixed picture and never updates

If you set your own image on a key in the Stream Deck app, that image wins — Stream Deck stops letting the plugin draw, so the live graphics freeze. Nothing is broken and no error appears; the key just never changes again. It affects everything MIDIRover draws: the Sweep slider and knob, the Toggle on/off graphic, the Bank and Program numbers, and the MIDI Readout value. Clear the custom image on that key in the Stream Deck app (reset its icon back to the action's default) and the live graphic returns immediately. To keep a personal look, use MIDIRover's own colour settings instead — a per-key palette or the deck theme — which restyle the graphic rather than replacing it.

9 Support & feedback

Something not working, or a key you wish existed? Report a bug or ask for help — it goes straight to the developer, and a clear report is the fastest way to get a fix.

MIDIRover is free and made by an independent developer who plays guitar. If it saves you setup time,buy me a coffee.