Skip to content
Integration

BitFocus Companion module — network show control

Control Timers Studio from any BitFocus Companion surface — Stream Deck XL, X-keys, Loupedeck, a dedicated OSC console, or a bare web page. 30+ actions cover the full director workflow, paired over a single HTTP endpoint.

Module
timersstudio-api
Surfaces
Stream Deck XL · X-keys · Loupedeck
Actions
30+ actions · 6 variables
GitHub WebHID alternative Compatible Companion 3.2+

Last updated

BitFocus Companion module — network show control

BitFocus Companion is the open-source bridge between physical control surfaces (Elgato Stream Deck of every size, X-keys, Loupedeck, Infinitton, plain MIDI controllers) and network-addressable devices. Timers Studio ships an official Companion module that exposes the full director workflow as discrete actions and feedbacks, so any surface Companion understands can drive the show.

When to use Companion vs WebHID native

You want to…Pick
Pair one Stream Deck MK.2 on the operator’s laptopWebHID native
Run a Stream Deck XL, +, or PedalCompanion
Trigger cues from an X-keys or MIDI consoleCompanion
Share one deck between two operator machinesCompanion
Run the show from a dedicated hardware-only rig (no browser)Companion

The two stacks are not mutually exclusive — you can pair a MK.2 natively and have a Companion XL running on the same network for the technical director. Timers Studio dedupes the events.

Install the module

The module is published through Companion’s official module registry. In Companion 3.2+:

  1. Open Companion → Connections → Add a new connection.
  2. Search for timersstudio-api.
  3. Fill in:
    • Studio URL — the full URL of your Studio, e.g. https://timers.studio/id/42abcd.
    • API token — generated from the Studio’s Customize modal under Integrations → API tokens. Give it a human-readable label (“FOH desk Companion”) so you can revoke it from the audit log later.
  4. Save. The connection status flips to OK within a second. If it stays red, re-check the token — it must be a token, not a password, and it must be scoped to the same room.

For development builds of Companion, or to pin a specific module version, clone companion-module-timersstudio-api into your companion-module-…/ developer folder.

Actions (30+)

The module exposes three families of actions:

Transport

play, pause, toggle-play-pause, stop, reset, next-timer, previous-timer, goto-index, goto-id, add-seconds, remove-seconds, set-duration.

Messaging

send-message-slot-1…10, send-custom-message, flash-time-up, flash-custom, blackout-player, restore-player, clear-messages, qa-approve-next, qa-reject-next.

Modes and widgets

toggle-moderator-widget-<slug>, set-visual-alert-<color>, trigger-poll, close-poll, launch-raffle, open-raffle-winner-overlay.

Every action has a matching feedback so the Companion key can reflect state: a green border when the timer is playing, a red flash when TIME UP is active, a pulsing yellow when a poll is open.

Variables

Companion subscribes to a handful of variables that update in real time:

  • $(timersstudio:current_timer_remaining) — formatted mm:ss or hh:mm:ss.
  • $(timersstudio:current_timer_title) — the speaker’s slot title.
  • $(timersstudio:current_timer_speaker) — the speaker’s display name.
  • $(timersstudio:rundown_position) — “3 / 18”.
  • $(timersstudio:player_state) — RUNNING, PAUSED, STOPPED, FINISHED, BLACKOUT.
  • $(timersstudio:qa_pending_count) — integer.

Drop any of these into a button’s text or a display element for a live dashboard.

Troubleshooting

Connection red, error 401. The API token was revoked or mistyped. Regenerate one in the Studio and paste fresh.

Connection red, error timeout. Companion cannot reach the Studio URL. Check that the machine running Companion is on a network that can resolve timers.studio. On an air-gapped venue LAN you may need a proxy.

Actions fire but nothing happens. You paired the right Studio but the wrong room. The token is room-scoped — copy the URL from the Studio tab, not from an older bookmark.

Variables stay blank. The feedback channel is rate-limited at 2 Hz. If you refresh Companion too fast after boot the first frame may be empty; give it five seconds.

Source code

See also