PV4 Documentation
PV4 Documentation
Breadcrumbs

Controller Companion/Stream Deck Integration

PLAY supports integration with Bitfocus Companion via OSC to provide users with an efficient and customizable interface for cue playback and control using Elgato Stream Deck devices.

Using Companion with PV4, users can configure Stream Deck buttons to:

  • Trigger cues directly on the Orchestrator without using the Controller UI.

  • Build buttons that fire multiple cues in sequence with custom delays.

  • Clear active cues or entire cue types.

  • Combine PV4 actions with external device commands for synchronized show control.

For more information on Companion, visit:
https://bitfocus.io/companion

Available Commands

TYPE

OSC PATH

ARGUMENTS

Play Cue

(Plays a Single Cue)

/play-cue

For Housekeeping Cue 10

HK 10 "{}"

Play Multi

(Plays a Multi Cue)

/play-cue

For Graphic Cue 1

GFX 1 multi "{}"

Play Sequence

(Plays a Sequence Cue)

/play-cue

For AThlete Cue 2

ATH 2 sequence "{}"

Clear Multi

(Clears a Multi)

(Multis are "Instance" based and require the instance to be specified i.e. GFX2.1, GFX2.2 etc)

/multi-clear


Clear Graphic Cue 2 (First Instance)

GFX.2.1

Clear Sequence

(Clear a Sequence)

(Sequences are "Instance" based and require the instance to be specified i.e. ATH2.1, ATH2.2 etc)

/sequence-clear


Clear Athlete Cue 2 (First Instance)

ATH.2.1

Clear Cue Type

(Clears all Cues of the same Type regardless of surface)

/clear-active

Clearing all Graphic (GFX) Cues

cueTypeCode=GFX

Clear Cue Number

(Clears all Cues of the same Number regardless of surface)

/clear-active


Clearing all Cues numbered 10

cueNumber=10

Clear all Cues on a Surface

/clear-active

surface=main_16x9

Surface name in all lower case, replace spaces with underscores

Clear Individual Cue

(Clears a specific Cue by utilising Cue Type and Number)

/clear-active

Clearing GFX Cue Number 10

cueTypeCode=GFX cueNumber=10

Configuring Bitfocus Companion for PV4

  1. Ensure that the hardware running Companion is connected to the same network as the Orchestrator application.

  2. Navigate to the Connections tab in the Companion UI.

  3. Click Add Connection from the right‑hand side of the interface.

  4. Search for Generic: OSC in the list of connection types.

  5. Click Add to create a new OSC connection.

  6. Label this connection PV4 for easy identification.

  7. Set the Target IP to the IP address of the PV4 Orchestrator machine.

  8. Set the Target Port to the OSC receive port used by PV4.

    1. The default OSC port for PV4 is 7117.

  9. Save or apply the connection settings to enable the OSC link.

  10. Confirm that the connection status indicator shows the OSC connection as active.

Building a button to trigger PV4

  1. Navigate to the Buttons tab.

  2. Select the page on which you want to create the new button.

  3. Click an empty button slot to begin configuring a new button.

  4. In the right-hand configuration panel, click Regular Button to create a standard action button.

  5. At the top of the configuration panel, set optional visual properties such as:

    1. Button Name

    2. Font Size

    3. Text Alignment

    4. Font Style

    5. Background Colour

    6. Text Colour

  6. Scroll down to the Press Actions section.

  7. Click Browse within the Press Actions panel.

  8. Select OSC from the action list.

  9. Choose Send message with multiple arguments and click Add.

  10. A new OSC action will now appear on your button with four key fields:

    1. Cue Position – used for ordering multiple actions on a single button.

    2. Delay (ms) – allows you to delay this action relative to others.

    3. OSC Path – the command you want to send to PV4.

    4. Arguments – the values required by the OSC command.

  11. Enter the required OSC Path for the PV4 action you want to trigger, based on the Available Commands table above.

  12. Enter the required Arguments based on the cue or function you want to control, based on the Available Commands table above.

    1. Example for playing Housekeeping Cue 10:

      1. OSC Path: /play-cue

      2. Arguments: HK 10 "{}"

    2. Example for clearing Housekeeping Cue 10:

      1. OSC Path: /clear-active

      2. Arguments: cueTypeCode=HK cueNumber=10

  13. If you are adding multiple actions to this button, assign a Cue Position and add a Delay (e.g., 10ms) so actions fire in the correct order.

  14. Press Save or click outside the configuration panel to apply your changes.

  15. Test the button by pressing it on the physical Stream Deck or by using the Companion Emulator.

  16. A complete table of PV4 OSC Actions, OSC Paths, and Arguments can be found on the "Stream Deck Integration" documentation page.