midi-interceptor

A small Node.js application that listens to available MIDI input devices, processes incoming messages, and sends them to a virtual MIDI output, which can be used by your DAW as a MIDI input source.

The application merges MIDI inputs and offers flexible control over how incoming MIDI Note On and Note Off messages are routed and split across MIDI channels.

You can define split definitions for routing either individual notes or note ranges to specific MIDI channels (currently supports channels 1-16). This can be leveraged within your DAW or sequencer, for example, to record specific notes to specific tracks or assign virtual instruments to specific zones of your keyboard.

This project is designed as a command-line tool and is powered by cli-primer, making it highly configurable through CLI arguments and/or a configuration file.

Typical scenarios

• You have several MIDI controllers but your DAW/notation editor only supports one input controller at a time.
• You want to input/record distinct musical elements from your MIDI keyboard (e.g., simultaneously record a bassline and a melody on two different tracks), but your MIDI keyboard does not have built-in split functionality.

Installation

Ensure you have the latest LTS version of Node.js installed. If not, check their official releases page.

1. Use npm to globally install midi-interceptor:

npm install -g midi-interceptor

2. Ensure you have a virtual MIDI port. This is needed to collect the MIDI messages midi-interceptor rewrites, and to send them to your DAW, sequencer, or notation editor.

   To set up a virtual MIDI port:

   • Windows: Install loopMIDI, a free tool for creating virtual MIDI ports. Once installed, open it, add a virtual MIDI port (e.g., name it "MIDI Interceptor Output"), and note the name you gave it.

   • macOS: Use the built-in IAC Driver:

     1. Open Audio MIDI Setup.
     2. Go to Window > Show MIDI Studio.
     3. Double-click IAC Driver and check Device is online.
     4. Create a new port (e.g., name it "MIDI Interceptor Output") and note the name you gave it. Note that "IAC Driver " might get prepended to the actual name you give there. You might need to provide something like, e.g., "IAC Driver MIDI Interceptor Output" instead (remember to use quotes for any argument values that contains spaces).

   • Linux: Depending on your distribution, there may be a built-in virtual MIDI port, or you may need to install and configure an additional package. Consult your distribution's documentation for details.

Configuration

To initialize a configuration file:

midi-interceptor --ic

This creates the file midi-interceptor.config in your home directory. Open it in a JSON editor. The file allows you to define multiple profiles, which you can switch between at runtime, via the --cp=<profile_name> argument.

Here is a sample configuration:

{
  "profiles": [
    {
      "name": "satb_choir",
      "settings": {
        "virtualOutputName": "MIDI Interceptor Output",
        "splitTable": [
          { "type": "range", "midiFrom": 74, "midiTo": 88, "channel": 1 },
          { "type": "range", "midiFrom": 63, "midiTo": 73, "channel": 2 },
          { "type": "range", "midiFrom": 55, "midiTo": 62, "channel": 3 },
          { "type": "range", "midiFrom": 35, "midiTo": 54, "channel": 4 }
        ]
      }
    }
  ]
}

This defines a profile named "satb_choir," which splits the customary range of a mixed choir across four MIDI channels and sends all transformed messages to a virtual MIDI port named "MIDI Interceptor Output".

Take this as a starting point, adjust as needed, and don't forget to set "MIDI Interceptor Output" (or whatever you named it) as a MIDI input in your DAW/sequencer/notation editor.

Additional options

In the settings section of the configuration file you can also add these keys:

• inputPortsExclusions: use it to exclude certain MIDI ports, by their name. Supports the wildcards * and ? that match any chars and any char, respectively. Excluding a port prevents midi-interceptor from listening to it, thus leaving that port available for other applications to use. Example:

"inputPortsExclusions": ["Akai MPK Mini", "Native Instruments*", "Alesis V??"]

• debug: use it to cause incoming Note On and Note Off messages to be printed to the console, along with any rerouting they are affected by. Example:

"debug": true

Note: for infrequent use, it is better to provide debug as a command line argument rather than a configuration file setting.

Note: A virtualOutputName is mandatory; midi-interceptor will exit with an error if one is not provided.

Note: Ensure the midi-interceptor.config file contains valid JSON. Use a JSON validator like the one from curiousconcept if unsure.

Execution

Run the midi-interceptor application from the command line. Ensure the MIDI gear you want to intercept is plugged in and turned on, then run, e.g.:

midi-interceptor --cp=satb_choir

Note: You can override any setting from the configuration file via the command line. For example, to specify on-the-fly a different virtual output you would do:

midi-interceptor --cp=satb_choir --virtualOutputName="my Other Virtual Port"

on Windows, or

midi-interceptor --cp=satb_choir --virtualOutputName=my\ Other\ Virtual\ Port

on macOs/Linux.

The default profile

You can define a profile named "default" in your configuration file. This profile will be loaded automatically and serve as the base for any subsequent settings given in another profile (loaded via --cp) or specified on the command line. Here’s how you can use this to your advantage:

• Single Profile Use: If you only plan to use one profile, name it default and include all your settings there. This way, you can run midi-interceptor without any arguments:

midi-interceptor

• Common Settings: If you have settings that should apply across multiple profiles, place them in the default profile.

Accessing the Built-in Documentation

To view the documentation for all supported settings, run the following command in your console:

midi-interceptor --h

Other considerations

This open-source project is still in its early stages. Any help is appreciated. Feel free to report bugs and suggest features, or fork the code and send pull requests.

License

This project is licensed under the MIT License.