Companion Variable Reference

Full variable list for the Bitfocus Companion module described in the Companion module section of Chapter 5 — Control Methods.

Every variable here updates the moment the server reports a change — there's no polling delay.

Per-timer variables

Published for every timer currently known to the module, using the timer's API ID as the prefix: timer_{apiId}_*. For example, the timer with API ID 1 publishes timer_1_name, timer_1_time, timer_1_state, and so on.

Variable	Example value	Description
timer_{apiId}_name	Sermon	The timer's display name.
timer_{apiId}_time	12:34	Current time, formatted M:SS / H:MM:SS. Clock-mode timers format as a wall-clock time instead; SMPTE-mode timers show the incoming timecode. Blank for a countdown-to-time timer sitting in standby (not running or overrunning).
timer_{apiId}_state	running	Raw runtime state: stopped, running, paused, or overrun.
timer_{apiId}_state_icon	⏸	A single-character icon showing what a play/pause button would do next: ⏸ while running, ▶ while paused or stopped, ↩ while overrunning.
timer_{apiId}_mode	manual	Raw timer mode (manual, countdown_to_time, countup_from_time, clock, external, message, smpte, etc.).
timer_{apiId}_duration	45:00	The timer's configured initial duration, formatted the same way as _time.
timer_{apiId}_is_displayed	true	"true"/"false" — whether the timer is currently on any Clock Window's display stack.
timer_{apiId}_smpte_timecode	01:02:03:04	Raw incoming SMPTE timecode. Blank for non-SMPTE timers.
timer_{apiId}_show_label	true	"true"/"false" — whether this timer has its on-screen label enabled.
timer_{apiId}_label	Guitar	The resolved label text (timer name, or a custom label) when show_label is true. Blank when label display is off.
timer_{apiId}_warning_reached	false	"true"/"false" — true only while the timer is active (running or overrunning) and past its warning threshold but not yet past critical. Direction-aware (count-up timers compare >=, count-down timers <=).
timer_{apiId}_critical_reached	false	Same as above, for the critical threshold.
timer_{apiId}_is_overrunning	false	"true"/"false" — shorthand for state === "overrun".
timer_{apiId}_muted	false	"true"/"false" — whether this timer's audio cues/TTS are currently muted.
timer_{apiId}_active_clip_name	Slide 4	Name of the clip/slide/cue currently active on this timer's source (ProPresenter slide label, Resolume/PVP clip name, or QLab cue ID). Blank if the timer has no source or the source has nothing active.
timer_{apiId}_video_offset_seconds	12	Stored video-offset value (seconds) for the currently active clip, if one has been learned via the Learn Video Offset action. Blank if none.
timer_{apiId}_video_offset_label	Slide 4	Label of that stored video-offset entry. Blank if none.

Per-region variables

Published for every NDI clock region, twice: once by 1-based position in the region list, and once by the region's own name, sanitized to [A-Za-z0-9_-] (spaces and other punctuation become _). A region named "Left Screen" in position 1 publishes both clock_1_name and clock_Left_Screen_name with the same value — use whichever addressing scheme is more stable for your setup (position survives a rename; the name-based variant survives reordering).

Variable (by position)	Variable (by name)	Example value	Description
clock_{n}_name	clock_{SanitizedName}_name	Left Screen	The region's display name.
clock_{n}_displayed_timer_name	clock_{SanitizedName}_displayed_timer_name	Sermon	Name of the timer currently on top of this region's display stack. Blank if nothing is displayed.
clock_{n}_displayed_timer_api_id	clock_{SanitizedName}_displayed_timer_api_id	1	API ID of that timer. Blank if nothing is displayed.
clock_{n}_displayed_timer_mode	clock_{SanitizedName}_displayed_timer_mode	manual	Mode of that timer. Blank if nothing is displayed.
clock_{n}_displayed_timer_time	clock_{SanitizedName}_displayed_timer_time	12:34	Formatted current time of that timer (same formatting rules as the per-timer _time variable). Blank if nothing is displayed.
clock_{n}_displayed_timer_state	clock_{SanitizedName}_displayed_timer_state	running	Runtime state of that timer, or the literal string empty if nothing is currently displayed in this region.

Global variables

Variable	Example value	Description
connection_status	connected	connected or disconnected — whether the module's WebSocket connection to the ClockBridge server is currently up.
active_preset	Sunday Morning	Name of the currently active full Preset (Chapter 4). Blank if no Preset is currently loaded/active.
timer_count	6	Total number of timers the module currently knows about.