repository·main·Indexed 25 days ago
https://github.com/bitfocus/companionAn open-source control platform for managing professional AV hardware and software through a unified interface using modules. This documentation covers installation via Docker and Docker Compose, configuration via config.yaml, Prometheus and Grafana metrics integration, and developer guides for the React UI, shared-lib, and companion-launcher.
Bitfocus Companion is a free and open-source software platform designed to control a wide variety of hardware and software devices. It supports over 700 different types of devices, including audio mixers, video switchers, lighting systems, and streaming gear.
Companion operates through a system of modules and drivers that allow it to communicate with these devices. You can find the complete list of supported modules on the official Bitfocus website.
The Companion admin interface is organized into three primary areas:
On smaller screens, the main and secondary panels are combined into a single view using additional navigation controls to optimize space.
Note: If the Admin Password feature is enabled, a lock icon will appear in the top header to allow locking the interface.
The companion-launcher is the small window that appears when running the desktop version of Bitfocus Companion.
Since version 3.0, the launcher has been decoupled from the main Companion process. It operates as a standalone mini-application that runs Companion directly using a bundled version of Node.js. This architecture allows the Electron version (used for the UI) and the Node.js version (used for the Companion core) to be managed independently, preventing version conflicts and ensuring that the desktop experience remains consistent with headless builds.
Companion Satellite is a lightweight application designed to run on a separate machine to forward locally connected surfaces (like Stream Decks) to a central Companion instance over a network.
Use Companion Satellite if:
Certain module actions (such as queries or device value fetches) return a result. If an action provides a Store Action Result option, you can capture this value for use in button text, feedbacks, or other actions.
You can store results in two ways:
$(this:page)/$(this:row)/$(this:column) and provide a variable name.Once stored, the result behaves like any other variable in Companion.
Companion v3.4.0 introduced the ability to perform logical operations within feedbacks using new internal feedback types. Instead of standard option fields, these feedbacks allow you to compose logical conditions by adding other feedbacks as inputs.
Available internal logic feedbacks:
internal: Logic ANDinternal: Logic ORinternal: Logic XORIn multi-line expressions, you can store and update intermediate values using variables.
name = value): Sets a variable. If the variable doesn't exist, it is created in the current scope. If it exists in an outer scope, it updates that existing variable.let name = value): Explicitly creates a new variable in the current scope.const name = value): Creates a new variable that cannot be reassigned.Scopes are defined by blocks { ... } (e.g., inside if, for, while, or functions).
let or const inside a block creates a new variable that hides any outer variable with the same name within that block.if statement), declare it before the block using let or const, then update it inside using a bare assignment.Rule of thumb: Use let/const for fresh variables; use bare assignment name = ... to update existing variables in outer scopes (like accumulators).
// Updating an outer variable (Accumulator pattern)
let total = 0
for (const x of [1, 2, 3]) {
total = total + x // updates the outer `total`
}
total // 6
// Shadowing (Inner variable hides outer)
let name = 'outer'
if (true) {
let name = 'inner' // a separate variable
name // 'inner' here
}
name // still 'outer'In Companion 5.0, you may not need a feedback for every dynamic change. Every property on a graphics element can be an expression. Expressions can reference variables and perform calculations, causing the element to redraw automatically whenever the underlying variable changes.
Common use cases for expressions over feedbacks:
$(custom:armed)).blink(500) to make an element blink).To prevent infinite loops or excessive resource usage, Companion enforces execution limits on all expressions.
Every expression runs under a budget for:
If an expression exceeds this budget, it is aborted and treated as an invalid expression (similar to a syntax error). While the budget is generous for standard logic, keep expressions used in high-frequency areas (like field visibility checks) simple to avoid hitting limits.
In Companion 5.0, a feedback allows a button to change its appearance automatically based on device state or logic. Unlike previous versions that applied a single flat style to a button, 5.0 feedbacks work by overriding properties on specific graphics elements (such as Text, Image, or Background) while the feedback's condition is met.
Color or Text Size) to override.Variables are referenced using the standard $(connection:variable) syntax. Inside expressions, variables retain their original type (number, array, object, etc.).
$(custom:my_array)[0].$(custom:settings).timeout or $(custom:settings)['timeout'].?. to safely access properties that might be missing: $(custom:settings)?.timeout.?? to provide a fallback if a value is undefined: $(custom:name) ?? 'Unknown'.... to combine arrays or objects: [...$(list_a), ...$(list_b)].Note: Nested variable references like $(custom:$(custom:b)) are not supported. Use the parseVariables function instead.
$(custom:my_array)[0]
$(custom:settings).timeout
$(custom:settings)?.timeout ?? 1000
[...$(custom:list_a), ...$(custom:list_b)]