CB AV MINISTRY

SHARED REF / BITFOCUS COMPANION CROSS-ROOM REFERENCE

Bitfocus Companion Cross-Room Reference

Operational reference for the Bitfocus Companion control plane — architecture, surfaces, page map, dependencies, failure modes, relay paths, change workflow, and successor-facing handoff notes across all rooms.

Room: SHAREDType: BITFOCUS-COMPANION-CROSS-ROOM-REFERENCERev: May 27, 2026

Document Control

Why This Document Exists

Bitfocus Companion is one of the most important control systems in the ministry. It is not just a convenience layer for Stream Deck buttons. It is the shared control plane that ties together livestream switching, camera presets, stream scheduling, projector control, ATEM actions, lighting presets, and some room-level utility actions across multiple rooms.

This document exists so a future AV leader can understand how Companion is deployed, what rooms depend on it, what external services it talks to, what is current versus legacy in the configuration, and what breaks if it stops working. Volunteer role guides explain how to use the controls; this document explains how the Companion system itself is structured and how it supports the wider ministry.

What Companion Owns in This Ministry

Companion is currently responsible for:

  1. Presenting room-specific control surfaces to operators
  2. Sending direct control commands to vMix, ATEM switchers, PTZ cameras, the Livestream Audio Wing, projectors, Lightkey, the Thompson Chapel audio console, the Thompson Chapel TV, VLC, and UniFi PoE control
  3. Calling the custom Stream Scheduler service to create livestreams, refresh platform auth, and perform relay-related control actions
  4. Hosting both physical Stream Deck surfaces and browser-based emulator surfaces from one shared configuration
  5. Running ministry-wide automations such as scheduled power actions, stream-key updates, and periodic service polling

Companion is a control layer. It does not carry the actual video or audio feeds, but it does decide and trigger many of the actions that determine how those feeds are switched, started, routed, and presented.

Current Production Topology

High-level control architecture

flowchart LR
subgraph church["Church building"]
ASTR["Auditorium livestream Stream Deck"]
APROJ["Auditorium projection Stream Deck"]
FHQR["Fellowship Hall phone emulator"]
TCQR["Thompson Chapel phone emulator"]
HBIQR["HBI room phone emulator"]
end

subgraph school["HCS building"]
GYMQR["Gym phone emulator"]
HV["Hyper-V Windows server"]
UB["Ubuntu VM"]
COMP["Bitfocus Companion"]
SCHED["Stream Scheduler service"]
HV --> UB
UB --> COMP
UB --> SCHED
end

subgraph controlled["Controlled systems"]
VMIX["Auditorium vMix"]
AUDSYS["Auditorium ATEM, PTZ cameras, projectors, Lightkey, Wing"]
FHSYS["Fellowship Hall ATEM, camera, lights"]
TCSYS["Thompson Chapel ATEM, camera, console, TV, VLC"]
GYMSYS["Gym ATEM and camera"]
HBISYS["HBI camera and UniFi PoE"]
end

subgraph cloud["Cloud and remote services"]
RELAY["LivestreamRelay Azure VM"]
PLAT["YouTube / Facebook / SermonAudio"]
end

ASTR --> COMP
APROJ --> COMP
FHQR --> COMP
TCQR --> COMP
GYMQR --> COMP
HBIQR --> COMP

COMP --> VMIX
COMP --> AUDSYS
COMP --> FHSYS
COMP --> TCSYS
COMP --> GYMSYS
COMP --> HBISYS
COMP --> SCHED

SCHED --> RELAY
VMIX --> RELAY
FHSYS --> RELAY
TCSYS --> RELAY
RELAY --> PLAT

Stream-path summary

Source room / feed Stream path Notes
Auditorium main program vMix -> LivestreamRelay -> YouTube / Facebook / SermonAudio Main English livestream path
Auditorium ASL feed vMix -> YouTube Separate ASL stream
Fellowship Hall ATEM Mini Pro -> LivestreamRelay Relay-backed room
Thompson Chapel main English stream ATEM Mini Pro -> LivestreamRelay Relay-backed room
Thompson Chapel IBC / Spanish stream ATEM Mini Pro -> YouTube Direct-to-YouTube path
Gym ATEM Mini Pro -> YouTube Direct-to-YouTube path
HBI room No livestream documented in current Companion config Camera control only

Current production summary

Item Current state
Companion deployment model One central Companion instance
Companion host location Ubuntu VM running on a Hyper-V Windows server in the HCS server room
Companion packaging Docker container
Companion version seen in reviewed export 4.2.5+8815-stable-8821dfa519
Separate scheduling service Yes; separate Docker container on the same Ubuntu host
Total pages in reviewed config 99
Surfaces in reviewed config 11
Active integrations / instances in reviewed config 27 enabled
Trigger count in reviewed config 27
Rooms with normal physical Companion surfaces Auditorium only
Rooms with normal phone-based emulator use Fellowship Hall, Thompson Chapel, Gym, HBI room
Single point of failure Yes; all current room control depends on the central Companion instance

Operator Access Model

Normal operator surfaces

Room / role Normal access method Companion surface name Startup page Notes
Auditorium livestream video Physical Stream Deck XL at the livestream video position CBC-VideoRecord 1 - CAM1 Main operating surface for Auditorium livestream video
Auditorium projection Physical Stream Deck MK.2 at the ProPresenter position CBC-ProPresenter 6 - PAGE Projection-facing surface
Fellowship Hall Phone emulator opened by QR code Fellowship Hall 12 - Fellowship Hall Normal room workflow
Thompson Chapel Phone emulator opened by QR code Thompson chapel 19 - Thompson Chapel Main Thompson Chapel operator surface
Gym Phone emulator opened by QR code Gym 14 - Gym Normal room workflow
HBI room Phone emulator opened by QR code HBI 13 - HBI Camera control only

Special-use or admin-facing surfaces

Surface name Startup page Normal audience Purpose
Auditorium 1 - CAM1 Not the normal Auditorium operating surface Browser emulator copy of the Auditorium livestream pages
Aud Cam PTZ Control 35 - Manual Auditorium Camera Controls Special use by Auditorium livestream operator or admin Manual PTZ and gain control when operating remotely without the Canon controller
Lights 15 - Lights Admin only Auditorium lighting admin/control page
Projectors 7 - Projectors Admin only Auditorium projection admin/control page
ThompsonChapelPP 21 - PAGE Admin only Thompson Chapel ProPresenter helper page

Current navigation model

The reviewed config does not currently rely on Companion’s surface page restriction feature for the room surfaces. Instead, the setup relies mainly on:

  1. A room-specific startup page for each surface
  2. The buttons present on that page to control what other pages an operator can reach

This means page design and page links matter a great deal. It also means a page-number change can break multiple rooms at once.

Current Page Inventory

Pages Current use Main audience
1-4 Auditorium camera pages CAM1 through CAM4 Auditorium livestream video
5 Auditorium Utilities page Auditorium livestream video
6-7 Auditorium projection pages Auditorium projection
11 Older Fellowship Hall page Legacy; ignore
12 Fellowship Hall main page Fellowship Hall operators
13 HBI main page HBI operators
14 Gym main page Gym operators
15 Lights admin page Admin only
19-20 Thompson Chapel main and audio-control pages Thompson Chapel operators
21 Thompson Chapel ProPresenter helper page Admin only
31-34 Auditorium extra camera preset pages Auditorium livestream video / admin
35 Manual Auditorium camera control page Special-use fallback / remote operation

Page naming cautions

  • Some page names are descriptive (CAM1, Fellowship Hall, Gym), but some are generic (PAGE), so the page number and surface context matter.
  • Some button labels preserve older naming. Example: the Fellowship Hall schedule button is still labeled New Chapel Stream and uses HCS Chapel naming in the scheduling call even though it belongs to Fellowship Hall.
  • The current config contains both current and legacy items. A future cleanup should be deliberate, not casual.

Room-by-Room Control Summary

Auditorium livestream video

Current Auditorium livestream video pages control:

  • vMix preview and program workflow
  • Camera preset recall for Cameras 1-4
  • Manual camera utility functions including temporary presets and extra preset pages
  • Lower thirds and other graphics-related actions tied to ProPresenter and vMix overlays
  • Stream scheduling for the main CBC stream and the ASL stream
  • Start / stop of stream and recording functions
  • Camera power and exposure actions
  • FOH Source Mode control on the Livestream Audio Wing
  • Pre-service and post-service utility actions
  • LivestreamRelay Azure VM start / stop utility action
  • Deaf signer camera utility actions

The reviewed page map is:

Pages Purpose
1-4 Camera-focused operating pages; selecting a camera both changes page and places that camera in preview
5 Utilities page for scheduling, stream / record controls, camera power, exposure modes, FOH Audio toggle, and relay utility actions
31-34 Extra camera preset pages
35 Manual PTZ / gain control for all four main Auditorium cameras

Auditorium projection

Current Auditorium projection pages control:

  • ATEM routing and aux behavior used for Auditorium projection workflows
  • ProPresenter looks and some stage-display-related actions
  • Projector on / off actions
  • Lower-thirds and overlay-related projection actions
  • Solo / narration layout macros and related special cases

The reviewed page map is:

Pages Purpose
6 Core projection page with ProPresenter look actions and projector power
7 Projector and special-layout page used for more advanced projection switching patterns

Fellowship Hall

Current Fellowship Hall page controls:

  • ATEM Mini Pro program switching
  • Picture-in-picture / overlay style ATEM actions
  • Stream start / stop
  • Record start / stop
  • Livestream scheduling through the Stream Scheduler service
  • Canon PTZ pan / tilt / zoom / focus
  • PTZ preset recall
  • Camera exposure and power
  • Lighting presets through the LuminetDMX integration

Notable successor note: the button label and scheduling naming still refer to Chapel / HCS Chapel even though the page is the current Fellowship Hall page. Treat this as historical naming drift, not as proof that the page belongs to another room.

Thompson Chapel

Current Thompson Chapel pages control:

  • ATEM Mini Pro program switching
  • Audio mute / unmute at the ATEM level
  • Main English stream scheduling
  • IBC / Spanish stream scheduling
  • Stream start / stop
  • Record start / stop
  • PTZ camera control and preset recall
  • Thompson Chapel TV power
  • Preservice music helper actions
  • Thompson Chapel CQ console mute and level adjustments on a secondary page

The reviewed page map is:

Pages Purpose
19 Main Thompson Chapel control page
20 Audio-control page for the Thompson Chapel console
21 Admin-only ProPresenter helper page

Gym

Current Gym page controls:

  • PTZOptics camera pan / tilt / zoom / focus
  • Preset recall including left / center / right and score-related positions
  • ATEM Mini Pro source selection between live camera and pre-game / logo states
  • ATEM audio on / off
  • Stream start / stop
  • Record start / stop

HBI room

Current HBI page controls:

  • PTZ camera pan / tilt / zoom / focus
  • Preset recall
  • Camera power on / off
  • Camera reboot via UniFi PoE cycle

Current Active Integrations

Cross-room and shared services

Companion label Module type Current purpose
StreamScheduler generic-http Custom scheduling, auth refresh, relay control, and related service-backed actions
Companion label Module type Current purpose
AuditoriumATEM bmd-atem Auditorium routing, projection, and related video actions
vmix studiocoast-vmix Main Auditorium livestream switching and recording
Camera1 canon-ptz Auditorium Canon camera 1
Camera2 canon-ptz Auditorium Canon camera 2
Camera3 canon-ptz Auditorium Canon camera 3
Camera4 canon-ptz Auditorium Canon camera 4
DeafSignerCamera ptzoptics-visca Deaf signer camera control
Livestream-Wing behringer-wing FOH Source Mode and related livestream audio control
LeftProjector generic-tcp-udp Left projector power / control
RightProjector generic-tcp-udp Right projector power / control
Lightkey monospace-lightkey Auditorium lighting control
Auditorium-Propresenter renewedvision-propresenter-api Active ProPresenter API integration for Auditorium

Fellowship Hall integrations

Companion label Module type Current purpose
FellowshipHallATEM bmd-atem Fellowship Hall video switching, stream, and record control
FellowshipHallCanonPTZ canon-ptz Current Fellowship Hall Canon PTZ camera
LuminetDMX generic-http Fellowship Hall lighting preset control

Thompson Chapel integrations

Companion label Module type Current purpose
ThompsonChapelATEM bmd-atem Thompson Chapel video switching, stream, and record control
ThompsonChapelPTZ ptzoptics-visca Thompson Chapel PTZ camera control
ThompsonChapelConsole allenheath-cq Thompson Chapel audio console mutes and level changes
ThompsonChapel-ProPresenter renewedvision-propresenter-api Thompson Chapel ProPresenter API actions
ThompsonChapelVLC videolan-vlc Thompson Chapel preservice media helper actions
smartcast vizio-smartcast Thompson Chapel TV power control
scriptlauncher josephadams-scriptlauncher Thompson Chapel script-launch helper actions

Gym and HBI integrations

Companion label Module type Current purpose
GymATEM bmd-atem Gym stream, record, and source control
GymPTZ ptzoptics-visca Gym PTZ camera control
HBI-CAMERA sony-visca HBI camera control
unifi ubiquiti-unifi HBI PoE-cycle reboot action

Service-Backed Behavior and Automation

What is direct vs indirect

Most Companion actions in this ministry are direct device-control actions. Examples include:

  • vMix preview / transition commands
  • PTZ moves and preset recalls
  • ATEM program and stream commands
  • Wing mute-state changes for FOH Source Mode
  • Projector power commands
  • Lightkey cue triggers

The main indirect / service-backed behaviors are:

Behavior Backing service or dependency Why it matters
Stream scheduling Stream Scheduler service Companion does not create stream events by itself
YouTube auth refresh Stream Scheduler service Needed before scheduling certain stream types
Facebook stream-key retrieval / update Stream Scheduler service plus Companion trigger logic Used for relay-backed rooms and some current workflows
LivestreamRelay VM start / stop Stream Scheduler service calling Azure endpoints Auditorium utilities page exposes this control
Relay-backed stream delivery LivestreamRelay Azure VM Main Auditorium, Fellowship Hall, and Thompson main English stream paths depend on it

Current automation categories seen in the reviewed export

The reviewed export shows Companion triggers handling several categories of automation:

  1. Scheduled power actions for Auditorium cameras
  2. Scheduled projector power actions
  3. Periodic scheduler/auth refresh behavior
  4. Variable-driven updates that change ATEM stream destinations or keys when new scheduling data is returned
  5. Some internal button-press automations tied to timed events

The live Triggers tab in Companion should be treated as the source of truth for exact current schedules. This document captures the existence and purpose of those automations, not a guarantee that every trigger time will remain unchanged.

Successor caution on automations

Some automations are obvious from the button labels. Others are hidden in:

  • Triggers
  • Custom variables
  • Internal action groups
  • Service calls routed through the Stream Scheduler service

A successor should never assume that a button label tells the whole story. The Auditorium Utilities page is a good example: its visible buttons include scheduling, FOH Source Mode, stream / record, pre-service, post-service, and relay-related actions that touch multiple systems behind the scenes.

Change Workflow and Backup Practice

Current governance

  • Only the AV Director is allowed to modify the Companion configuration
  • Automatic backups are enabled in Companion
  • Occasional manual exports of the full config are created and saved separately

Minimum safe change process

If a future AV leader needs to modify Companion, the safest baseline workflow is:

  1. Export the full Companion configuration before making any changes
  2. Record what room, page, button, trigger, or integration is being changed
  3. Test the affected workflow in the room that uses it
  4. Test any other room that shares the same service or integration
  5. Save a new exported snapshot after the change
  6. Update the relevant room docs and this cross-room reference if the architectural behavior changed

Why page numbers matter

This config relies heavily on explicit page numbers and explicit set_page actions. Companion does not automatically make a page reordering safe. If pages are inserted, deleted, or renumbered carelessly, button navigation can break across multiple surfaces.

Treat page refactoring as a high-risk change.

Failure Modes and Fallback

Failure Impact Known fallback Notes
Central Companion instance unavailable Most room control surfaces stop working Auditorium only has a meaningful manual fallback This is the largest current operational risk
Auditorium livestream Stream Deck unavailable Livestream video workflow becomes slower or harder vMix can be operated directly by mouse; Canon RC-IP100 can control cameras Companion emulator and page 35 can help in some remote cases
Stream Scheduler service unavailable New stream scheduling, auth refresh, and relay-related service actions fail No equivalent Companion-only fallback documented Room operators may still have direct controls for already-configured devices
LivestreamRelay unavailable Relay-backed stream paths fail or become incomplete None documented for normal services Affects Auditorium main, Fellowship Hall, and Thompson Chapel main English stream
Auditorium camera controller unavailable during remote operation Manual PTZ becomes difficult Use the Aud Cam PTZ Control emulator page This matters especially if operating by remote desktop
Non-Auditorium Companion outage Fellowship Hall, Thompson Chapel, Gym, and HBI lose practical operator control No fallback documented Current system design assumes Companion availability

Current fallback reality

Only the Auditorium has a clearly documented manual fallback path:

  • vMix can still be operated directly with mouse and keyboard
  • The Canon RC-IP100 can control the Auditorium PTZ cameras manually

For the other currently documented rooms, there is no practical fallback documented if Companion is unavailable.

Current Legacy / Ignore List

The reviewed export contains items that should currently be treated as legacy, disabled, or stale:

Item Current status How to treat it
Page 11 Older Fellowship Hall page Ignore
ProPresenter integration Old module replaced by Auditorium-Propresenter Ignore for current operation
Avantis integration Not in current use Ignore
FelllowshipHallPTZ integration Old Fellowship Hall camera Ignore
YT integration Not in current use Ignore
Windows PowerShell UploadMediaToAtems.ps1 triggers Stale leftovers from an older deployment Ignore for current architecture; do not document as active behavior
Thompson IBC Facebook scheduling call in export Stale leftover config Do not treat it as current intentional workflow

Configuration drift that a successor should expect

The config shows signs of normal long-term operational drift:

  • Some page names are generic
  • Some labels preserve old naming
  • Some disabled modules remain in the file
  • Some stale triggers remain in the file

That does not mean the config is broken. It does mean a successor should verify intent before cleaning anything up.

What a Successor Should Learn First

If a future AV leader inherits this system, the recommended order of understanding is:

  1. Read AV Ministry for the documentation map
  2. Read this document to understand the Companion architecture and dependencies
  3. Read the Auditorium Room Overview because the Auditorium is currently the most detailed pilot room
  4. Review the live Companion pages, surfaces, triggers, and integrations in the web UI
  5. Review the latest saved Companion export before making any changes
  6. Confirm access to the Companion host, Stream Scheduler service, LivestreamRelay management path, and the QR-code surfaces used by the rooms

Successor Handoff Checklist

When handing this system to a future AV leader, make sure the following are transferred:

  1. Access to the Companion web UI
  2. Access to the Companion host environment and Docker management path
  3. Access to the Stream Scheduler service and knowledge of what it does
  4. Access to the LivestreamRelay management path
  5. The latest known-good Companion export
  6. Knowledge of which room pages are current, which are admin-only, and which are legacy
  7. Knowledge that page-number changes are risky
  8. Knowledge that Companion is currently a single point of failure for most rooms

Relationship to Room Documentation

This document should stay focused on:

  • Shared Companion architecture
  • Room-to-room control patterns
  • Service dependencies
  • Governance, change workflow, and failure modes
  • Successor-facing operational knowledge

Room-specific operating instructions should remain in each room’s Room Overview and Volunteer Role Guides. This document supports those guides; it does not replace them.