After this chapter you'll be able to trigger app actions, mutes, level changes and whole scenes from a physical or software controller: a MIDI surface, a Stream Deck, TouchOSC on a tablet, or a lighting/show-control desk. You'll also know the ready-made recipes on the device page (up to thirteen), what each one does and when it is offered. Macros work whilst Omnissiah is connected to the device.
What it is, and what it isn't
Omnissiah receives control commands and routes them to your hardware. It doesn't drive a controller itself, and it doesn't ship a control surface. What sends the command is a separate piece of software or hardware; Omnissiah just has to be listening for it.
A macro is a named list of actions. A trigger is something that fires it. The two are separate things: a macro can have no triggers, one, or several, and you can change or remove a trigger without touching the actions underneath. Make as many macros as you like; there's no fixed number of them.
Two places hold macros. The Macros page (sidebar) is where you set up triggers and actions: a list of macros down the left, and the selected one's triggers and actions on the right. The Macros tab on each device's page shows that device's macros as pads you click to fire, and offers recipes: ready-made macros you add in one click (see "Recipes on the device page", below).
There's also a canonical address for every control in the app (mute, gain, delay, and so on) that you can send directly without setting up a macro at all. See Appendix E — OSC address reference for the full list. Macros are for the case where one button press should do more than one thing, or where you want a friendly name and an address of your own choosing instead of remembering a canonical one.
Recipes on the device page
Open a device and choose its Macros tab. The top section lists the macros that touch that device. The Recipes section underneath holds up to thirteen ready-made macros. Click Add on a recipe (for Apply a Correction, pick a correction from its list) and it becomes a macro with its steps already filled in. Most take the recipe's name; Save This State is named after the device, and Apply a Correction after the correction. The new macro appears as a pad above, and you can open it on the Macros page to add a trigger or change a step.
A recipe that sets a state sets it whatever state the outputs were in before. Pressing Speaker A twice leaves the same speakers playing, and a second press does not swap them back.
The pads
Each pad shows the macro's name, a one-line summary of what it does, and a chip for each trigger (or No trigger). Click a pad to fire the macro. The pad reads Running… while it runs and Fired for a moment afterwards. A macro that is switched off shows dimmed and doesn't fire from a click. The pad for a Correction On / Off macro also reads Correction is on or Correction is off.
To remove macros, click Delete at the top right of the section. The pads turn into delete targets: click a pad, then click it again to confirm. Click Done when you've finished. A + Macro tile at the end of the pads makes a new empty macro and opens it on the Macros page.
The recipes
| Recipe | What it does | When it is offered |
|---|---|---|
| Apply a Correction | Puts a saved correction back on this device's outputs. Pick one from the Add for… list. | Greyed out, and the list reads No corrections yet, until a correction on this device's outputs is in History. A correction that was last applied to different outputs than it measured is left out. |
| Save This State | Stores every setting on the device as one step, and puts them all back when the macro fires. | Always offered. |
| Correction On / Off | Switches room correction off if it is on, and on if it is off. Acts on every device, not only this one. | Always offered. |
| Mute Toggle | Flips the mute of each output: muted outputs play, playing outputs mute. Outputs that share a mute link group count as one, so the group flips once. | Greyed out when the device has no output with a mute. |
| Volume Up | Raises the master volume by 1.5 dB each time it fires. | Greyed out when the device has no master volume. |
| Volume Down | Lowers the master volume by 1.5 dB each time it fires. | Greyed out when the device has no master volume. |
| Speaker A | Unmutes outputs 1 and 2 and mutes output 3. | Shown on a Nexus only. Greyed out when the unit has fewer than three outputs with a mute. |
| Speaker B | Mutes outputs 1 and 2 and unmutes output 3. | Shown on a Nexus only. Greyed out when the unit has fewer than three outputs with a mute. |
| Input Analog, Input Client Aux, Input Digital | Plays only that input pair into the outputs and turns the other input pairs off. A pair that was fully off comes on at the level the other pair had. | One recipe per input pair, and only when the device's routing matrix carries more than one pair. |
| Sub On | Puts every crossover back in, then unmutes the sub. | Greyed out, with the note "Needs an output set up as a sub.", when no output is a sub. |
| Sub Off | Mutes the sub, then bypasses the crossover on the other speakers so they run full range. | Greyed out, with the note "Needs an output set up as a sub.", when no output is a sub. |
A sub, for these two recipes, is an output whose crossover is a low pass.
The Speaker A and Speaker B recipes mute the outgoing speakers first, so the two sets never play together. The Sub On recipe puts the crossovers back in before it unmutes the sub, and Sub Off mutes the sub before it bypasses the crossovers, so the room never gets a sub and unfiltered speakers together.
Each recipe adds one macro. Adding the same recipe again makes a second macro with a number on the end of its name.
Connecting a controller
Omnissiah listens on two inputs. Turn on whichever one your controller uses, in the bar at the top of the Macros page. Both are off until you turn them on.
MIDI
Any class-compliant MIDI controller plugged into the Mac works: pads, faders, buttons. Under MIDI, set MIDI listening to On. Hover over the MIDI label to see the inputs Omnissiah found, and the summary at the end of the bar counts them. Leave it Off if you don't use MIDI and don't want a controller unexpectedly firing macros.
Omnissiah also exposes a virtual "Omnissiah" MIDI destination, so software that sends MIDI (an Elgato Stream Deck MIDI plugin, a DAW, a show-control app) can reach it without a physical MIDI loopback cable.
OSC
Omnissiah runs an OSC listener over UDP, on port 9393 by default. Under OSC, set OSC listening to On first. By default it only accepts messages from this Mac: nothing on your network can reach it until you turn on network listening.
- 1Under OSC listening scope, choose Network. The two choices sit side by side and the one you are using is highlighted.
- 2The OSC port field lets you change the listening port if 9393 is already used by something else on your Mac.
OSC has no password or login. Turning on network listening means anything on your network can send it commands, including muting your system. Only turn it on on networks you trust.
Once network listening is on, Omnissiah advertises itself over Bonjour as "Omnissiah". In TouchOSC, tap Browse when adding a connection and it should show up with no IP address or port to type in.
Stream Deck
Omnissiah can't see or configure a Stream Deck directly. Elgato's software owns the deck, not us. What works:
- A Stream Deck MIDI plugin (for example the Trevliga "Midi" plugin) set to send to the virtual "Omnissiah" MIDI port. Use its Hold Button action if you want a Momentary macro (see below): that sends the note-on/note-off pair a momentary action needs.
- An OSC plugin, pointed at Omnissiah's IP and port, sending to a macro's address or a canonical address.
- Bitfocus Companion, which can drive a Stream Deck itself and send both MIDI and OSC, including press/release, which most single-shot Elgato OSC plugins can't do.
RME ARC USB
The RME ARC USB doesn't work with Omnissiah, or with anything other than RME TotalMix. It's a proprietary controller tied to RME's own software, not a class-compliant MIDI device. If you have one, it can't be repurposed here.
Making your first macro
- 1Open the Macros page and click New. A macro called Macro 1 appears in the list.
- 2Give it a name. Anything you like. It's only a label, and it's what the suggested OSC address below is built from.
- 3Under Triggered by, click + Add trigger. A trigger opens, set to OSC. Choose a Source: OSC: the Address is filled in for you as /omnissiah/macro/<name>. You can change it to anything you like as long as it starts /omnissiah/. Copy it into whatever is sending the command. MIDI: click Learn, then press or move the control on your controller. The next MIDI message in is bound, and the trigger shows what it learned (for example CC 7 ch 1). You can also set the Message (Control change or Note), Number and Channel by hand. Another macro: pick the macro under After macro. This one then fires whenever that one does.
- 4Under Sequence, click + Add action and pick a target from the App / Device / Output tree. Only combinations the hardware actually supports are offered: for example, Mute only appears for outputs that have one (see Loopback, below). Picking an action from the Macro section adds a Fire Macro step, and the Apply Correction section adds a step that applies one of your saved corrections.
- 5Click Fire to run the macro right there on the page, without needing the controller in hand.
Edits save automatically. There's no separate Save step, and the macro is live the moment you make the change.
If nothing happens when you trigger it, check the Activity list at the bottom of the page (see Troubleshooting, below).
Several triggers on one macro
Click + Add trigger again to give the same macro another way in. A mute macro can be a footswitch in the live room, a pad on the desk controller and an OSC address your show-control software sends to, all at once. They're independent: each has its own Enabled switch and its own Mode, and removing one leaves the others alone.
The switch beside the macro's name is the master: turn it off and none of its triggers fire it. Fire on the page still works, because that's you asking directly.
One macro firing another
There are two ways to make one macro cause another, and they are not the same thing.
- After macro (a trigger): "whenever that macro fires, so do I." The second macro reacts. Set this up on the macro that should follow.
- Fire Macro (an action): a step in the sequence, like any other action. It runs in its position, in order, as part of the first macro. Set this up on the macro that leads.
Use Fire Macro when order matters: mute, then recall the scene, then unmute. Use After macro when something should simply tag along whenever a macro runs, wherever it was fired from.
A macro can't fire itself directly, either way. A longer loop (A fires B, B fires A) is allowed: it will run, and Omnissiah holds each lap back so it can't spin. A banner on the Macros page names any loop it finds.
Capture: assign by doing
Rather than hunting through the action tree, you can build a macro by doing the thing once in the app:
- 1Select the macro and click Capture under Sequence. The button turns into Capturing…, and a panel headed Recording into the macro's name appears in the bottom-right corner reminding you it's armed.
- 2Go and do the thing: click Mute on an output, drag a fader, flip Crossover Bypass. Each step appears in the panel as it is recorded. Caught something by accident? Click the × next to it and it is gone. If the panel is in the way, the arrow in its corner shrinks it to a pill.
- 3Click Stop on the panel. It takes you back to the macro, with the steps you just captured in its sequence.
Capture records mute, gain, polarity, crossover bypass, master volume, and routing changes. It does not record delay: delay is only offered as a step (nudge) action, not an absolute value, so there's nothing for Capture to record it as. Starting a calibration switches Capture off, so the run's own writes never land in the macro.
Scenes: snapshot a device into a macro
There's no separate preset library. Instead, a macro can be a scene:
- 1Select the macro.
- 2Under Sequence, click Snapshot device… and choose a device.
- 3A single Recall Snapshot action is appended to the sequence. That one row holds every setting the device had at that moment, and says how many it captured.
Firing the macro afterwards puts all of those settings back. Build one macro per "scene" you want (movie night, party, quiet late-night listening) and fire it from a single button. The Save This State recipe does the same in one click from the device page.
Snapshot captures the settings you edit, not the EQ filter coefficients the app derives from them, so a snapshot stays valid and is recomputed on recall. The device has to be connected when you take the snapshot. Clicking the button twice adds two Recall Snapshot rows rather than replacing the first, so remove the old one if you meant to re-take it.
Applying a correction from a macro
The Apply Correction action puts a correction from History back on the outputs the run measured, and records it as the applied correction. The action does what Apply does on the Calibration tab, with no listening step first. Add it from the Apply Correction section of the action picker, which lists each correction in History by name, or use the Apply a Correction recipe. The section does not appear while History is empty.
A correction that a macro applies is kept in History. When History fills and the oldest runs are cleared, a run that a macro uses stays. You can still delete it by hand; the macro's step then shows the run's ID in place of a name and fails when it fires.
The action is refused while a calibration is in progress, while another correction is being auditioned, and for a correction that was last applied to different outputs than it measured. Apply that one from its results page instead.
Set, toggle and momentary
Every on/off action (mute, polarity, crossover bypass, bypass actions) can be bound one of four ways, chosen per action in the sequence with the step's Mode:
| Mode | What it does | Needs |
|---|---|---|
| Set on | Always turns it on | any trigger |
| Set off | Always turns it off | any trigger |
| Toggle | Flips whatever it currently is | any trigger |
| Momentary | Turns on while held, back to its previous state on release | a control that sends a press and a release |
Momentary is the one to reach for talkback-style controls: press and hold to mute, let go and it un-mutes by itself. It needs both halves of the gesture. A MIDI note button (note-on, then note-off) works. A single-shot OSC message doesn't: there's nothing to send on release, so momentary only makes sense on MIDI triggers, or an OSC controller sophisticated enough to send two messages.
Toggle is right for a single button that should just flip state each press, with no separate on/off button needed. Set on/Set off are right when the controller itself has a labelled on/off state, like two different buttons or a stepped OSC value. The Speaker A, Speaker B, Sub On and Sub Off recipes are built from Set on and Set off steps, which is why they leave the same state however often they fire. The Mute Toggle recipe is built from Toggle steps.
A trigger can override all of them. Each trigger has a Mode of its own: leave it on As each step and every action does whatever it was set to above, or choose Set, Toggle or Momentary to make the whole macro behave that way from that trigger. That's how the same mute macro can be a latching pad on one controller and a hold-to-talk footswitch on another.
Faders and knobs
A button says "now". A fader says "here". Omnissiah keeps the two apart by address, so it never has to guess which one you meant from the number.
| Send to | Carrying | Meaning |
|---|---|---|
| the macro's own address | nothing, or 1, or 0 | press, press, release |
| that address + /fader | 0.0 to 1.0 | where the fader sits |
| that address + /value | a number in the parameter's own units | set it to exactly this |
So a macro answering to /omnissiah/macro/monitors also answers to /omnissiah/macro/monitors/fader and /omnissiah/macro/monitors/value. You don't set those up; adding the address gets you all three.
A TouchOSC fader left on its default 0.0 to 1.0 range, pointed at the /fader address, sweeps the whole of whatever it is bound to. Point it at the bare macro address instead and you get a button press, not a move.
MIDI needs no such choice. Omnissiah works it out from the macro. A CC bound to a macro that holds something continuous, such as a gain or master volume, is read across its full 0 to 127 travel. A CC bound to a macro of switches behaves as a button: any value above 0 is a press and 0 is the release. A CC bound to a macro that holds several routing changes, such as an Input recipe, also behaves as a button, because each of its steps writes a stored value and none of them is a travel.
The curve
Gain and master volume do not travel evenly. A fader spreads the quiet end out and packs the loud end in, the way a console fader does, so unity lands three quarters of the way up and the last quarter of the throw carries the boost. Everything else moves in a straight line. Open the step and click Curve… beside Fader to change that. Fader response offers Console (gain and master volume only), Linear and Custom, where you drag the points to draw your own curve. Range sets the bottom and top of the fader, and narrows what the full throw covers.
Picking up where you left off
A physical fader has no idea what the software is doing. Recall a preset, switch which macro a fader is bound to, or use a second controller, and the fader and the parameter disagree. The first touch would jump the level.
Omnissiah holds the fader until it passes through the live value, then hands control over. Nothing moves while it is held, and the activity log says so (waiting for pickup). Sweep the fader once and it catches. When the fader disagrees on the step is where you change this: Pick up is the behaviour just described, and Jump moves to the fader straight away, which suits motorised and endless controls.
Once it has control it keeps it until something else moves the parameter, at which point it has to be picked up again.
While calibration or measurement is running
Macros are refused while a calibration run is playing and capturing its test signal, and while a measurement on the Measurements page is running, to stop a stray control command from interfering with a test signal in flight. The refusal shows in the Activity list as busy. Wait for the run to finish and fire the macro again. Canonical OSC addresses are refused in the same way, and Omnissiah stops echoing state changes to OSC clients while the run lasts.
The wait after the run's measuring ends, while the corrections are calculated, does not block macros. Nothing is written to the device in that time.
The block works in both directions. If a macro is mid-run when you press the button to start a calibration or measurement, the start is refused with "a macro is running — wait for it to finish, then try again", and you start it again a moment later.
A macro that's already running (a scene with many actions takes a moment to apply) ignores repeat triggers rather than queuing or restarting it, and the Activity list shows already running. The macro's pad on the device page reads Running…, and its card on the Macros page lights up.
Backups, export and import
Macros are saved as part of the app's normal config, so they're already included whenever you back up or restore. Nothing extra to do.
To move your macros to another machine, or ship a starter set to someone else, use the page-header buttons instead:
- Export…: saves every macro, and the triggers that fire them, to a file you choose.
- Import…: replaces every macro currently in the app with the ones from a file you choose. Confirm before it runs; there's no undo.
Both use the normal Finder save/open dialog, and neither can be triggered from a macro itself.
Loopback
The loopback processor is a valid macro target, but it only has gain, delay, polarity, and scenes. It has no mute, crossover, master volume or routing, because those controls don't exist on loopback, so the action picker simply doesn't offer them for it.
Troubleshooting
Nothing happens when I trigger the macro.
Check the Activity list at the bottom of the Macros page: every OSC message and MIDI event that reaches Omnissiah appears there, including ones that didn't match anything and ones that were refused, with a reason chip (for example busy, already running, unsupported, device offline, no applied correction). A rapid stream of the same unmatched MIDI message (a knob sweep bound to nothing, say) is throttled to one line every quarter-second, so briefly missing individual messages there doesn't mean they were dropped. If nothing from your controller shows up at all even after that, it never reached Omnissiah; check the items below.
A recipe is greyed out.
Each recipe has a condition, and the table under "Recipes on the device page" lists them. In short:
- Apply a Correction needs a correction in History on this device's outputs. Until then the list reads No corrections yet.
- Volume Up and Volume Down need a master volume on the device.
- Mute Toggle needs an output with a mute.
- Sub On and Sub Off need an output set up as a sub, which means an output whose crossover is a low pass. Set the crossover on the output first.
- Speaker A and Speaker B appear on a Nexus only, and need at least three outputs with a mute.
- The Input recipes appear only when the routing matrix carries more than one input pair. A device with a single input pair doesn't show them.
All the buttons grey out for a moment while a recipe is being added.
The macro's address is refused.
An address has to start /omnissiah/, and each part after that can only use lowercase letters, digits, _ and -. A few names are kept for the app's own canonical addresses and can't be used as the first part of yours: out, dev, app and subscribe. An address can't end in /fader or /value either, because those two are how Omnissiah tells a fader move from a button press.
OSC messages aren't arriving from another device.
- OSC listening may be off. Check that OSC listening is On.
- Network listening is probably off. Under OSC listening scope, check whether This Mac or Network is highlighted, and choose Network.
- macOS may be blocking it: if the bar reads "blocked by macOS", open System Settings → Privacy & Security → Local Network, turn Omnissiah on, then reopen the Macros page.
- Double-check the port. A red line reads "Couldn't listen on port …" if something else on your Mac already has it; either quit that other app or change Omnissiah's port.
MIDI Learn never captures anything.
Confirm MIDI listening is On and your controller is counted in the bar. Some controllers need their driver/utility running before macOS exposes them as a MIDI device. Learn gives up after 30 seconds with nothing received and shows "No MIDI received — try again."; click Learn again once the controller is ready.
A macro fires but the wrong thing happens, or nothing changes.
Open the macro and check its sequence still points at real hardware. If a target device or output isn't currently connected, the macro's card in the list shows a red mark, the Activity list shows device offline, and that step does nothing until the device comes back. The rest of the sequence still runs.
This manual is licensed to owners of Omnissiah for using the product. It may not be used to build competing software.