How to Control Backstage with the Bitfocus Companion Module

How to Control Backstage with the Bitfocus Companion Module

The Brainsalt Backstage module for Bitfocus Companion lets you control a Backstage media server from a Stream Deck, touch screen, or any Companion-supported surface. It connects over Backstage's JSON show-control protocol on TCP and gives you live feedback, variables, and ready-made button presets for all show-control entities.

Before you start

• Backstage is running on the target server
• Bitfocus Companion 3.4 or later is installed on your control machine
• The control machine can reach the Backstage server over TCP (default port 7400)
• You know the Backstage server's IP address or hostname

Steps

1. Enable the show-control protocol in Backstage

Open Settings → Remote Control and check Enable Show-Control Protocol. Leave the Enable Bitfocus Companion sub-option checked (it is on by default). Click Apply / Restart Protocol Server to activate the listener.

The default TCP port is 7400. Change it here if your network requires a different port. If you have set an Auth Token, note it down — you will need it in Companion.

2. Install the module in Companion

In the Companion web UI, go to Connections. Click Add connection and search for Brainsalt: Backstage. The module is in the official store and installs automatically.

3. Configure the connection

After adding the connection, fill in three fields:

Once configured, the module connects and subscribes to live status updates. The connection indicator turns green when active.

4. Use the discovered actions, feedbacks, and presets

The module automatically discovers all show-control entities in your Backstage project. No additional configuration is required — every stepper, sequencer, broadcast scheduler, calibrator, audio output, matrix mixer, NDI input, and node endpoint appears as a target in the module's action and feedback dropdowns.

The module also generates ready-made button presets for every discovered entity. Open Presets in Companion and drag them onto your buttons to get working controls with feedback in seconds.

5. (Optional) Add CompanionIO nodes for custom typed controls

For show-specific controls beyond the built-in entities, add CompanionIO nodes to your Backstage node graph (found in the UI category). Each CompanionIO node appears in Companion as a typed control with a matching widget: trigger buttons for Bang, faders for Float/Int, toggles for Bool, choice selectors for Enum, text fields for String, and color pickers for Color.

CompanionIO nodes are optional. The module works with all show-control entities without any nodes in the graph.

What the module controls

The table below summarises the actions, feedbacks, and variables the module exposes for each Backstage entity type.

[USER-ACTION-REQUIRED: Attach a screenshot of the Companion connection page showing the Brainsalt: Backstage module configured and connected]

[USER-ACTION-REQUIRED: Attach a screenshot of Backstage Settings → Remote Control showing the Enable Show-Control Protocol and Enable Bitfocus Companion checkboxes]

Options explained

Common Mistakes

• Connection stays yellow / "Connecting" — The show-control protocol is disabled in Backstage. Open Settings → Remote Control, enable it, and click Apply / Restart Protocol Server.

• Connection fails with "disabled" — The Enable Bitfocus Companion sub-checkbox is unchecked. The module identifies itself to Backstage, and this switch gates Companion connections specifically. Re-enable it in Settings → Remote Control.

• No entities appear in action dropdowns — The Backstage project has no steppers, sequencers, or other show-control entities yet. Create a stepper or sequencer in Backstage; the module discovers new entities automatically.

• Auth token mismatch — If Backstage has an auth token configured but the Companion connection does not (or vice versa), the connection will be rejected. Make sure both sides use the same token, or clear both.

• Port/bind changes not taking effect — Changes to TCP port or bind address require clicking Apply / Restart Protocol Server in Backstage. The auth token and IP allowlist apply live without a restart.

Tips

• Drag presets from the Presets tab instead of building buttons from scratch. The module generates transport buttons with state feedback and status displays for every discovered entity.

• Use Adjust Volume and Adjust Tempo actions on encoder rotation events. They read the current value and add a step, making them ideal for hardware knobs.

• CompanionIO nodes respect min/max/step metadata. Set these on the node in Backstage and the Companion actions will clamp and step values accordingly.

• All entity names in Companion match their Backstage names exactly (case-sensitive). If you rename a stepper in Backstage, update your Companion buttons to match, or use the Allow custom option with a Companion variable.

• The module subscribes to live status events. Button feedbacks and variables update in real time without polling — typically within 100 ms of a state change.

Related

How to Control Backstage via the JSON Remote Control Protocol — Full reference for the underlying show-control protocol (message format, domains, actions, status fields).

Integrate with Backstage via the REST API — Alternative HTTP/REST integration for querying and controlling Backstage programmatically.

How to Use the Stepper Window — Create and manage steppers in Backstage, which are the primary show-control entity for multi-step sequences.