Bitfocus Companion
Preferences → Control → Companion: variable polling, feedback, and the variable library.
ShowRevue has three independent Companion integrations:
| Feature | Direction | What it does |
|---|---|---|
| Companion Module | Companion → ShowRevue | Control transport, navigation, messaging from a Stream Deck or surface |
| Variable Feedback | Companion → ShowRevue | Pull live variable values from Companion and display them in overlay text |
| State Feedback | ShowRevue → Companion | Publish ShowRevue's live state (record, cue, timecode…) so Companion buttons show real feedback |
All Companion settings live in their own Preferences → Companion tab (new in 0.4 — previously under OSC Input).
ShowRevue has direct, purpose-built integrations for GrandMA3, GrandMA2, ETC Eos, and QLab. Use those for lighting cues and media cues — they are lower-latency and require no Companion in the chain.
Variable Feedback is the right tool when ShowRevue doesn't yet have a native integration for a piece of gear — for example, an ATEM switcher program input, a Disguise show variable, an MA3 custom attribute, or any other data your Companion setup already knows about. If ShowRevue adds a native integration for something you are currently piping through Companion, switch to the native path.
Ports
Three independent ports are involved — keep them straight:
| Port | Who listens | Direction | Used for |
|---|---|---|---|
| 8001 | ShowRevue | Companion → ShowRevue | OSC Control — commands (record, cues, messaging). Enable in Preferences → OSC Control. |
| 8002 | Companion (the module) | ShowRevue → Companion | State feedback — ShowRevue publishes /showrevue/state/*. |
| 8000 | Companion | ShowRevue → Companion | Variable polling — ShowRevue reads Companion's HTTP API. |
If Companion and ShowRevue run on the same Mac, the OSC Control listen port (8001) and the module's feedback listen port (8002) must be different — two processes can't bind the same UDP port. They can share a number only across different machines.
The module's last_command variable updates when the module sends the OSC packet — it does not confirm ShowRevue received it. If a command "sends" but nothing happens, check that OSC Control is enabled in ShowRevue (Preferences → OSC Control) on the port the module targets (default 8001).
Companion Module
The Companion module lets you control ShowRevue from Stream Decks and other Companion-compatible surfaces.
Install
Download the .tgz from the Companion/ folder in the source repo and install it from Companion → Modules → Install from file.
Configure the module
- Host — the Mac running ShowRevue
- Port —
8001, which is the default ShowRevue remote-control port
Available preset groups
- Transport — Record, Stop, Play, Pause
- Navigation — Next or previous cue, next or previous timecode segment, ±5 seconds, next or previous frame
- Loop — Set in or out, go to in or out, toggle, enable, disable, stop, clear
- Messaging — Mask on, off, toggle, clear message, and configured message presets
- NDI Output — Set source to Show Output or GUI Mirror (sends
/showrevue/ndi/source, see NDI Output)
See the Companion project README for the full action and variable reference.
Variable Feedback
ShowRevue can poll Companion's HTTP API to read live variable values and display them in overlay text widgets.
How it works
ShowRevue polls http://<companion-host>:<port>/api/variable/<connection>/<name>/value on a configurable interval. When a variable changes, the new value is substituted wherever $(connection:variable) appears in a text field.
Variable IDs use Companion's native format:
| Format | Example | Endpoint |
|---|---|---|
connection:variable | atem:pgm1_input | /api/variable/atem/pgm1_input/value |
custom:variable | custom:song_title | /api/custom-variable/song_title/value |
Setup
In ShowRevue:
- Open Preferences → Companion.
- Enable variable polling.
- Set Host to the machine running Companion (use
127.0.0.1if Companion is on the same Mac). - Set Port to Companion's HTTP API port — default is
8000. - Set Poll interval —
200 msis a good default; lower values increase responsiveness at a small CPU cost. - Confirm the status indicator shows Connected.
In Companion:
- Make sure HTTP API access is enabled (it is by default in Companion 3+).
- No other configuration is needed — ShowRevue reads variables directly via HTTP.
Variable discovery
You never have to add a variable to use it — typing $(connection:variable) into any text field registers and polls it automatically (see the tip above). The Variable Library is simply a place to browse, preview live values, and confirm IDs.
On first connect, ShowRevue seeds the Library with Companion's built-in internal:* variables (time, date, page, uptime) so they show in autocomplete immediately. Your module variables (ATEM, Disguise, custom variables, etc.) won't appear in the Library list until they're referenced or added — to add one for previewing:
- Open the Companion web UI → go to Connections → [your module] → Variables and copy the variable name exactly as shown (e.g.
atem:pgm1_input). - Paste it into the add field in Preferences → Companion → Variable Library and click Add. Both formats work:
atem:pgm1_inputand$(atem:pgm1_input).
Either way, once a variable is referenced (in a widget) or added (to the Library) it starts polling immediately and shows its live value.
The table shows each variable's current value and when it last changed. The variable count shown in the header reflects how many variables ShowRevue is currently tracking.
Some Companion builds expose a /api/variable-definitions endpoint that ShowRevue uses to import all variables at once. If your Companion version supports it, all variables will appear automatically on first connect without any manual setup.
Use variables in text fields
Type $( in any ShowRevue text field to open the autocomplete list of known variable IDs. Select one to insert it.
$(atem:pgm1_input)
$(custom:show_title)
$(companion:selected_page_name)
The live value is substituted in:
- Overlay custom text widgets — burned into the recorded video and visible on the live preview
- Live message presets — text shown on operator displays
If a variable is unknown or Companion is unreachable, the placeholder resolves to an empty string.
Variable Library table
Preferences → Companion → Variable Library shows all tracked variables:
| Column | Description |
|---|---|
| Variable ID | The connection:name identifier |
| Value | Current live value from Companion |
| Last Changed | How long ago the value last changed |
Use the search bar to filter by ID or value. Select one or more rows and click Remove Selected to stop tracking them.
You don't have to add a variable to the Library first. Paste $(connection:variable) directly into any Custom Text overlay widget — ShowRevue registers it automatically and resolves it live (in both the operator overlay and the recorded video). The Library is just for discovery and previewing values.
State Feedback (ShowRevue → Companion)
New in 0.4: ShowRevue can publish its own live state back to Companion over OSC, so your Stream Deck buttons show real feedback — a red RECORDING button, the live cue number on a button, the running timecode, and so on.
Setup
In ShowRevue:
- Open Preferences → Companion.
- Under Send Feedback to Companion, enable Publish ShowRevue state.
- Set Host to the machine running Companion (
127.0.0.1if it's the same Mac). - Set Port to the ShowRevue module's feedback listen port — default
8002.
In Companion, install ShowRevue module v0.2.0 or later, which adds the matching variables and a Recording boolean feedback (use it to colour a button red while recording).
How often it updates
State is pushed the instant a value changes — there's no manual "resend". Record state, cue, and show name update immediately; timecode and fps update once per second (they're sent as HH:MM:SS). Changing the host/port re-pushes the full current state automatically so Companion is never left stale.
Published values
Each value is sent as an OSC message /showrevue/state/<key>:
| OSC address | Module variable | Value |
|---|---|---|
/showrevue/state/recording | recording | 1 while recording, 0 when idle (drives the Recording feedback) |
/showrevue/state/timecode | timecode | Current timecode HH:MM:SS (or --:--:-- when no LTC lock) |
/showrevue/state/fps | fps | Detected frame rate, e.g. 25.00 |
/showrevue/state/ltc_status | ltc_status | LTC lock state — Locked / Weak / No signal |
/showrevue/state/cue_number | cue_number | Current lighting cue number |
/showrevue/state/cue_label | cue_label | Current lighting cue label |
/showrevue/state/time_since_cue | time_since_cue | Time since the last cue fired |
/showrevue/state/show_name | show_name | The current show name |
/showrevue/state/session_name | session_name | Session name, e.g. Show 1 |
/showrevue/state/session_type | session_type | Session type — Show / Tech / Dress … |
/showrevue/state/show_phase | show_phase | Show State phase — PRESHOW / ACT 1 / … |
/showrevue/state/show_timer | show_timer | Show State timer — counts up during acts, counts down during intervals |
/showrevue/state/curtain_countdown | curtain_countdown | Live countdown to the next curtain during preshow (− H:MM:SS) |
/showrevue/state/streaming | streaming | 1 while RTMP streaming |
/showrevue/state/ndi_sending | ndi_sending | 1 while NDI output is on |
/showrevue/state/note_count | note_count | Notes taken this session |
/showrevue/state/next_curtain | next_curtain | Next curtain time HH:MM |
/showrevue/state/source_health | source_health | Camera/source — ok / no signal / off |
/showrevue/state/disk_free | disk_free | Free space on the recording volume, in GB |
Feedbacks — Recording (button red while recording) and Source problem (button amber when the source is no signal / off). The Status preset group has ready-made read-out buttons for source health, free disk, note count, and a recording lamp.
Troubleshooting
| Symptom | Check |
|---|---|
| Status shows red / not connected | Confirm Companion is running and the host/port matches |
| Variable resolves to empty | Confirm the variable ID is spelled correctly — check Companion's variable list |
| Variable stopped working after Companion change | Connection was probably renamed in Companion. The variable ID prefix must match the connection label exactly. Remove the old ID from the Variable Library and re-add it with the new connection name. |
| Value is stale | Lower the poll interval; confirm the Mac and Companion machine are on the same network |
| Variables missing from autocomplete | Add them manually in the Variable Library, or reference $(connection:var) in a text field to trigger incremental discovery |
Only internal:* variables appear | Your module variables need to be added manually — find the IDs in Companion's web UI under Connections → [module] → Variables |