Use Backstage as a Companion Satellite Surface

Last updated 21 August 2026

Backstage can register with a Bitfocus Companion instance as a Satellite surface. Companion streams the button graphics of whichever page it assigns to that surface, and the buttons render as a clickable grid inside a CompanionSurface node in the Node Editor. Clicking a button runs its Companion action list. Presses also fire graph pins, so the rest of your node graph can react.

This is the opposite direction to the Brainsalt Backstage Companion module. That module lets Companion control Backstage (sequencers, steppers, mixers). This page covers Backstage acting as a surface that Companion drives — the connection goes from Backstage to Companion, not the other way round.

Before you start

  • Bitfocus Companion is running and reachable from the Backstage machine over TCP on port 16622 (Companion's Satellite API port)
  • You know the IP address or hostname of the machine running Companion
  • A Backstage project is open

Steps

1. Add a CompanionSurface node

In the Node Editor, right-click the canvas, open the UI category and select CompanionSurface.

2. Point it at your Companion instance

Select the node — its options appear in the Inspector. Set Host: to the IP address or hostname of the machine running Companion. Set Port: to 16622 (the default). The node connects automatically.

3. Set the grid to match your Companion page

Set Rows: and Columns: to the same grid size as the Companion page you intend to assign. For example, a 3×3 page needs Rows: 3, Columns: 3.

The surface declares its grid size to Companion, and Companion maps the assigned page onto it. If the sizes do not match, Companion warns "You have some surfaces which overflow the current grid bounds" and keys outside the grid map to nothing. Always match the grid to the page.

4. Assign a page to the surface in Companion

In Companion's Surfaces settings, find the surface (it registers as Backstage by default, with the machine name appended). Assign a button page to it. The button graphics appear in the node immediately.

5. Click a button or wire the output pins

Click any button in the node's grid to run that button's Companion action list. Each press also fires graph pins:

  • Key (Int) — the index of the key that was pressed.

  • Pressed (Int) — fires on press. Read Key on this edge to know which button.

  • Per-key pins — one output pin per key, named by the key index. Under the default Emit: Bang each fires a bang on press. Switch to Emit: Int to get 1 on press and 0 on release.

There are also per-key input pins. Sending a bang into a key's input pin presses that button on the Companion side, exactly as if a user had clicked it.

6. (Optional) Name the surface

Set Name: in the node options to give this surface a distinct identity. The default name is Backstage. Multiple nodes with the same name share the same surface — they all show the same page, and a press on any of them fires.

7. (Optional) Expose the surface on a Web Console page

A labelled CompanionSurface node appears as a draggable block in the Web Console page editor. Set Label: in the node options to any descriptive name. Once labelled, the surface block is available in the editor's palette and can be placed on a served Web Console page, where visitors can click the buttons from a browser.

A node without a Label: does not appear in the Web Console palette. This is the convention for all node-category Web Console blocks.

Common Mistakes

  • Grid size does not match the Companion page — Declaring a 4×2 surface for a 3×3 page leaves the extra column mapping to nothing, and Companion warns about overflowing grid bounds. Set Rows: and Columns: to match the page in Companion.

  • Surface not visible in Companion — Check that Companion is reachable on port 16622 and that the Host: field in the node points at the right machine. Also confirm Enabled is checked in the node options.

  • No page assigned — buttons are blank — The surface registers with Companion, but Companion does not assign a page automatically. Open Companion's Surfaces settings and assign a button page to this surface.

  • Changing Emit style drops per-key pin links — Switching between Bang and Int rebuilds the per-key pins. Choose the emit style before wiring the graph.

  • Two projects sharing a surface name — Two different projects on the same machine that both use the default name share one surface in Companion. Give each project's surface a unique Name: if they should be independent.

Tips

  • Companion can reserve keys for page navigation (Page Up / Page Down) based on the surface's grid. This is a per-surface setting in Companion, not in Backstage.

  • Use the Key and Pressed output pins when you want one wire for all keys rather than a separate connection per button.

  • If Companion is unreachable, the node reconnects automatically. The delay backs off from 1 second to a maximum of 15 seconds.

  • Multiple nodes with the same Name: share one surface. This is intentional — copying a node keeps it on the same surface rather than creating a second one in Companion.

  • Changing Rows: or Columns: on one node moves every node sharing that surface, because the grid geometry belongs to the surface, not to individual nodes.

Control Backstage with the Bitfocus Companion Module — The opposite direction: using the Companion module to control Backstage's sequencers, steppers, and mixers.

Build and Serve Web Pages with the Web Console — Exposing node-based controls (including this surface) on a served web page.

Remote Control — All routes for driving Backstage from outside.

Nodes: UI — Node reference for all UI-category nodes, including CompanionSurface.