Midi-Relay

From HBC Praise
Jump to navigation Jump to search

Midi-Relay is used by the Companion app to send MIDI note triggers to Proclaim for the start of service automation (first three buttons on the Companion console).

Midi-Relay is a Mac command line script that runs inside a terminal window. Once launched a correctly functioning Midi-Relay will look like this...

Midi Relay screen.png

If Midi-Relay is not functioning, then Companion will not be able to correctly automate and trigger slides in Proclaim, so the only options would be to trigger the slides manually.


NOTE: The following sections are NOT relevant to normal Sunday morning work flow. They are included for upgrades or advance trouble shooting.

INSTALLATION

Midi-Relay was written by Joseph Adams and is distributed under the MIT License.

It is not sold, authorized, or associated with any other company or product.

To contact the author or for more information, please visit www.techministry.blog.

Midi-Relay is designed to allow you to send an HTTP POST request, with JSON data in the body, to the server, which will then send out the appropriate MIDI message to a MIDI port/device available to that server. It can be used to send MIDI across networks and subnets. It can also listen to incoming MIDI messages on ports available to the server and then act on them, sending HTTP requests, running scripts, etc.

RUNNING THIS SOFTWARE FROM BINARY:

  1. Download a binary release from https://github.com/josephdadams/midi-relay/releases for your OS.
  2. Open a terminal window and change directory to the folder where you placed the binary release.
  3. Run the executable from this folder.
  4. If this folder does not contain the midi_triggers.json file, a new one will be created the next time you add a trigger either via the API or the Settings page.

RUNNING DIRECTLY WITHIN NODE:

  1. Install node if not already installed. https://nodejs.org/en/download/
  2. Download the midi-relay source code.
  3. Open a terminal window and change directory to the folder where you placed the source code.
  4. Type node main.js within the this folder.
  5. If this folder does not contain the midi_triggers.json file, a new one will be created the next time you add a trigger either via the API or the Settings page.

RUNNING AS A SERVICE:

  1. Open a terminal window and change directory to the folder where you placed the source code.
  2. Install the Node.js library, pm2, by typing npm install -g pm2. This will install it globally on your system.
  3. After pm2 is installed, type pm2 start main.js --name midi-relay to daemonize it as a service.
  4. If you would like it to start automatically upon bootup, type pm2 startup and follow the instructions on-screen.
  5. To view the console output while running the software with pm2, type pm2 logs midi-relay.

This program runs an HTTP server listening on port 4000. If this port is in use and cannot be opened, you will receive an error.

Upon startup, the program will enumerate through the available MIDI input and output ports. It will also process the stored output triggers into memory and open any MIDI ports mentioned and start listening to them for incoming MIDI messages.

A web interface is available to view MIDI ports, triggers, and other information at /settings: http://127.0.0.1:4000/settings

TROUBLE SHOOTING

TO BE ADDED