Companion integration

Bitfocus Companion is free software that lets physical button controllers — like a Stream Deck — trigger actions in other software over a network. With the CueProX module, you can run your show entirely from hardware buttons and display live cue names, timers, and Q&A state directly on the button labels.

---

What you can do

• Advance and step back through cues from a Stream Deck or compatible controller
• Push alerts to output screens with a single button press
• Open and close Q&A from the button box without touching the director view
• Show the active cue name, timer, and Q&A status live on button labels
• Forward streaming state from OBS, vMix, or ATEM into the CueProX broadcast pill

---

What you need

• A computer running Bitfocus Companion 4.x (free — Windows, Mac, or Linux)
• A Stream Deck or other Companion-supported hardware (optional — Companion also works with virtual on-screen buttons)
• A CueProX account with at least one room

---

Step 1 — Install the CueProX module

The CueProX module is available at github.com/willemvds8/companion-module-cueprox. Listing in the Bitfocus module store is pending; until then, install it manually:

1. Clone or download the repository.
2. Run npm install then npm run build inside the folder.
3. In Companion: open Settings → Developer modules path and point it to the parent folder containing companion-module-cueprox.
4. Restart Companion — the module appears in the connection list as CueProX.

See the module README for detailed build instructions and system requirements.

---

Step 2 — Create an API token in CueProX

Go to Dashboard → Settings → API Tokens and click Create token.

Give the token a name you'll recognise (e.g. "Companion – Stream Deck"), then choose a scope:

• Account-wide — the token can control every room in your account.
• Specific rooms — the token is restricted to the rooms you select. Recommended for production setups where different operators manage different rooms.

After confirming, copy the token value immediately. It starts with cprx_ and is shown only once — if you close the dialog without copying it, revoke the token and create a new one.

---

Step 3 — Connect Companion to CueProX

1. In Companion, open Connections → Add connection and search for CueProX.
2. Fill in the connection settings:
   • Server URL — https://app.cueprox.com (or your dev URL)
   • API token — paste the cprx_... value
3. The connection status turns green once the token is validated.
4. Select the Room you want to control from the dropdown that appears after the connection is established.

---

Step 4 — Make your first button

1. Go to Buttons and click an empty slot.
2. Under Press actions, add CueProX → Next cue.
3. Save and press the button on your controller — CueProX advances to the next cue.

That's the full loop. From here, add more actions or create multi-step buttons that push an alert and advance a cue in a single press.

---

Step 5 — Show live state on button labels

Edit any button's label and type a variable reference to pull in live data. Useful variables:

Variable	Shows
$(CueProX:current_cue_name)	Active cue title
$(CueProX:current_cue_number)	Active cue position number
$(CueProX:next_cue_name)	Next cue title
$(CueProX:cue_time_remaining)	Timer countdown (mm:ss)
$(CueProX:active_alert_text)	Text of the active alert, or empty
$(CueProX:qa_open)	true / false

The full variable list is in the module README.

---

Step 6 — Forward broadcast state to CueProX (optional)

CueProX can show a live broadcast pill in the director view when you're streaming or recording. This data comes from Companion bridging your broadcast software.

1. Add the OBS, vMix, or ATEM module to Companion if you haven't already.
2. Create a trigger: OBS → Streaming started → CueProX: Update broadcast state with streaming = on, source = obs, scene = $(obs:current_scene).
3. Create the inverse trigger for Streaming stopped with streaming = off.

The broadcast pill in your CueProX director view turns green when streaming starts and goes grey when it stops.

---

Troubleshooting

Connection shows "Unauthorized" The token was created on a different environment (e.g. dev vs prod). Make sure the token matches the Server URL you entered — create a new token from the correct environment and update the connection.

Button label shows $NA The variable reference uses the wrong instance label. In Companion, the instance label must exactly match what appears in your Connections list (it is case-sensitive). Check Connections, find the CueProX entry, and use that label in your variable — e.g. $(CueProX:current_cue_name) not $(cueprox:current_cue_name).

Action runs but nothing changes in CueProX The token's scope does not include the room you're targeting. Go to Dashboard → Settings → API Tokens, revoke the token, and create a new one with the correct room scope selected.

---

Learn more

• CueProX module on GitHub — full action and variable reference, developer setup
• Bitfocus Companion — download, hardware compatibility, and community support