Enzyme MIDI
A MIDI fader box, pad controller or Mackie-style surface driving Enzyme, and the show's other devices, from Enzyme MIDI.app. Its faders and lights follow what Enzyme reports. For Enzyme itself, see Enzyme Essentials and the full Enzyme User Guide in the same docs folder.
What it is
Enzyme has no MIDI of its own. Enzyme MIDI is a separate program that turns a surface's notes and controllers into Enzyme's OSC commands, and turns what Enzyme reports back into the surface's lights and motor faders. It can also send to the show's other devices: a fader to a lighting desk's master, a key to QLab's GO, a button to switch a matrix.
It runs on the show machine or on any machine that can reach Enzyme over the network. The same program, with the same window, runs on the Mac and on Windows.
Before you start
- In Enzyme, check that OSC in is on and note its port: Machine › Bind and ports, OSC in (port 9000 unless changed).
- If Enzyme MIDI runs on the same machine, set OSC in's card to every interface. A program on the same machine reaches it at 127.0.0.1 only then; on one card, use that card's address instead.
- Plug in the surface. It needs no driver on the Mac for most surfaces.
The window
Open Enzyme MIDI.app in the build folder. It opens the mapping file you used last, or a new one using the first MIDI input it finds.
| Part | What it is |
|---|---|
| New, Open…, Save, Save as… | The mapping file. A dot after its name means unsaved changes. |
| Engine | Enzyme's address and OSC port, as 127.0.0.1:9000. For a backup pair, both, with a comma. The dot is green while Enzyme's status arrives. |
| Status in, port | Where Enzyme's status comes back to. 0 picks a free port. |
| Enzyme control and key | Enzyme's control port (its address with port 9200), for the show's other devices (chapter 7). Type the control key and press Enter if Enzyme asks for one. |
| Devices | Each surface: a name, its input, and its output for lights and faders, picked from the ports there now. open in green when both are open. |
| Mappings | One row for each control: what it is, where it goes, what it sends, its range, how it sends and its feedback. |
| The monitor | At the bottom: MIDI in, OSC out, Status in and the Log. Pause holds it still to read. |
The mapping file runs as you edit it, with nothing to apply. A row that is wrong turns red and says why, and the rest run without it; the top of the window says so too.
Your first mapping
- Under Devices, pick the surface as Input, and as Output if it has lights or motor faders.
- Press + Mapping. The new row is already learning: move a fader. Its Control shows what it is, such as cc 7 ch 1. To learn again, click the Control.
- Under Sends, type the message: /layer/1/opacity $v. $v is the control's value. As you type, a list offers the addresses Enzyme takes for your show (each layer, timeline, region and the rest): click one, or move with ↓ and ↑ and press Tab or Return, to fill it in, with $v after it for a fader. Esc closes the list.
- Set the Range the value runs over: 0 to 1 for opacity, a position in pixels, a level.
- In Enzyme, set layer 1's owner to Manual. Move the fader: layer 1 fades with it.
- Save. The file opens again the next time.
Faders, keys and encoders
How says how a control sends:
| How | For |
|---|---|
| fader or knob | A control that sends where it is. A knob without a motor waits until it passes Enzyme's own value before it takes over, so moving it never makes a layer jump. Picking it, an encoder, toggle or press and release puts $v at the end of a message that has none. |
| on press, on release | A key: the top of the range, or a message with no $v such as /transport/go. A note is always a key. |
| press and release | The top of the range while held, the bottom when let go. |
| toggle | Each press switches between the bottom and the top. |
| encoder | An endless knob, in the coding its surface uses: two's complement, sign, or offset 64. Try each until turning it right adds. |
Click a row's number for more: the control set by hand (note, controller, 14-bit controller, NRPN, pitch bend, program change, and its channel), Invert, a square curve for more travel at the bottom of a fade, and Whole steps for folders, files and cue numbers.
Lights and motor faders
With the surface's output open, Enzyme MIDI lights it and moves its motor faders. Feedback on each row says from what:
| Feedback | Means |
|---|---|
| engine | Enzyme reports it: a layer's opacity, the transport, the current cue, blackout, a layer's owner. The light or fader shows what is on screen, whoever changed it: a timeline, a desk, the shell, another surface. |
| echo | Enzyme does not report it, so the surface shows the last value it sent itself. It is wrong if something else moves the same thing. |
| none | Nothing to show: a one-off command such as Go. |
A fader being moved is never driven, and is left alone for a moment after. If Enzyme stops answering, the lights flash on surfaces that can, so a stale picture is not trusted.
The show's other devices
A row's To picks where its message goes: Enzyme, one of the show's OSC destinations (set under Control, OSC, in Enzyme), or one of its outboard devices (Control, Devices). Enzyme MIDI reads them from Enzyme through Enzyme control; its dot is green, with how many it found.
- An OSC destination, such as a desk or QLab: type the message the device expects, as /gma3/Page1/Fader201 $v. For a grandMA3, Hog, Eos, QLab, Companion or Resolume destination, a list offers that console's starter commands (the same as Enzyme's cue library) as you type; for a fader, the command's value becomes $v. Enzyme MIDI sends it straight to the device, value and all. It keeps the destinations' addresses in the mapping file, so the surface still reaches the desk with Enzyme closed.
- An outboard device, such as a matrix: pick one of its commands under Sends. Enzyme sends it, since it holds the device's connection, so this needs Enzyme running. A device command is a key.
Feedback for these is echo or none, since Enzyme reports only its own state. Renaming a destination or a device in the show leaves rows that name the old name unsent, with a line in the Log.
Mapping files
A mapping file is the engines, the devices and the mappings, saved as JSON. Keep one for each surface and show, and open them with Open…. The window edits the common settings. A few rarer ones live in the file only: a feedback address of your own, a fader's touch note, the values that light a pad, an encoder's step. The window keeps them when it saves. docs/midi.md in the build folder lists every key.
Closing the window with unsaved changes says so at the top; close again to lose them, or Save.
Messages worth knowing
Every address is in the OSC appendix of the full User Guide. These cover most surfaces:
| Sends | For |
|---|---|
| /transport/go | Go, as the Go button. /transport/stop, /transport/pause likewise. |
| /cue/go $v | Fire a cue by number. With a program change set to any, a program fires the cue of its number. |
| /layer/1/opacity $v | A layer's fader, 0 to 1, while the layer is Manual. |
| /layer/1/owner manual | Take layer 1 by hand. |
| /layer/1/media 4 $v | Pick a clip in bank 4 by its tile number. |
| /show/master $v | The master level, 0 to 1. |
| /show/blackout 1 | Blackout on; 0 off. |
| /recall/3/12 | Fire manual recall 12 in bank 3. An OSC script recall runs its messages, to Enzyme or to other devices. |
| /setlist/next | The next row of the set list. |
Without a window
On a machine that only bridges, Enzyme MIDI runs from a saved file with no window, until stopped:
"Enzyme MIDI.app/Contents/MacOS/enzyme-midi" --headless my-surface.json
--control HOST:PORT names Enzyme's control port when it is not the engine's own host on 9200, and the key goes in the environment variable ENZYME_KEY. --list prints the MIDI ports, --monitor prints what a control sends, and --check FILE says what each mapping does.
When something is wrong
| You see | Look at |
|---|---|
| The Engine dot is red | Enzyme running, OSC in on, the address and port. On the same machine, OSC in's card set to every interface (chapter 2). |
| A fader moves nothing | The row's note: the layer is not Manual. Then OSC out in the monitor, to see what was sent. |
| A device says not found | The surface plugged in, and its name under Input. It is found again within two seconds of being plugged back in. |
| Lights do not follow | The device's Output picked, and the row's Feedback. Echo shows only the surface's own moves. |
| A desk receives nothing | Enzyme control's dot, the destination's address in the To list, and whether this machine can reach that network. |
| A device command is refused | Enzyme running and connected under Enzyme control. The Log says why. |