companion-module-presentationcommander-server
AI-assisted project. This codebase was created with Claude
(Anthropic), directed and reviewed by a human author — including implementation
and documentation. Check it over before you rely on it for a show.
A Bitfocus Companion module for
Presentation Commander.
It controls a running Master Server from a Stream Deck (or any other Companion surface), so
you can route outputs, recall scenes, black out, send stage notes, and drive
next/previous slide on the connected Client Nodes.
It talks to the Master Server's existing JSON-RPC automation API (:9700)
over plain HTTP, so there's nothing extra to install on the server end.
flowchart LR
Deck["Stream Deck / any<br/>Companion surface"] --> COMP["Bitfocus Companion"]
COMP --> MOD["This module"]
MOD -- "GET /state · POST /rpc<br/>JSON-RPC over HTTP :9700" --> SRV["Presentation Commander<br/>Master Server"]
Download
v1.1.4
This release contains:
All builds, checksums and release notes: github.com/stoatworks-labs/companion-module-presentationcommander-server/releases.
What it does
- Actions: Route Output, Blackout Output, Recall Scene to Output, Send
Note to Stage, Next Slide and Previous Slide. Every output/scene/source/client
dropdown is filled live from the Master Server's current state, so the list
always matches what's actually configured and you never type an id by hand.
- Feedbacks: Output is routed to a specific source/scene (light a button
when a given output is showing what you expect) and Client Node is online
(light it while a given presentation laptop is connected).
- Variables:
connection_status, client_count, and one
routed_<output-id> variable per output holding the name of whatever
it's routed to right now (or Unrouted).
- It polls the Master Server every 3 seconds, and the action/feedback/variable
choice lists and values refresh by themselves as outputs, scenes, sources or
clients change.
Documentation
| Doc | Contents |
|---|
| docs/USER-GUIDE.md | Building a surface, and where the feedbacks can mislead you |
| docs/API.md | Every action, feedback and variable, the config fields, and the poll loop |
| docs/DEVELOPING.md | The three-repo protocol, the module conventions, and the behaviours to preserve |
Setup
- Install and enable this module in Companion (see Installing below).
- Add a new connection using it, and set:
- Master Server host: the machine running Presentation Commander
Master Server (default
127.0.0.1, meaning Companion's on the same
machine as the Master Server).
- Automation API port: default
9700, which matches the Master
Server's built-in automation API.
- The connection should go green once it can reach
GET /state.
If Companion runs on a different machine
The Master Server's automation API only listens on 127.0.0.1, on purpose.
It runs routing and scene commands with no authentication at all, so putting it
on the network is something an operator has to choose to do, and Presentation
Commander won't do it for you. If your Stream Deck / Companion setup is on a
different machine from the Master Server, reach port 9700 through an SSH
tunnel or a reverse proxy that adds its own authentication, then point this
module's Master Server host/port fields at the tunnel or proxy rather
than the raw port.
Installing (not yet in the Companion module store)
From a packaged release
A GitHub Actions release workflow builds the
distributable .tgz with companion-module-build whenever a v* tag is pushed
(or when someone runs the workflow by hand from the Actions tab). Grab the
.tgz from the Releases page
and import it through Companion's module import
(Modules → Import module package in current Companion versions). You can
also build the same package yourself with npm install && npm run package.
As a local developer module
git clone https://github.com/stoatworks-labs/companion-module-presentationcommander-server.git
cd companion-module-presentationcommander-server
npm install
Then in Companion, go to Settings → Developer Modules (or wherever your
Companion version keeps it) and add this folder as a local module.
Relationship to the rest of Presentation Commander
- presentation-commander-server:
the Master Server this module controls. Its
src/main/services/automationApi.ts
is the HTTP surface this module talks to (GET /state, POST /rpc), and
it's shared with the in-app Control Surface panel, so both paths behave the
same.
- presentation-commander-client:
the Client Node app that runs on each presentation laptop. The
next-slide/
previous-slide actions here get passed on to whichever Client Node you
target.
Roadmap / TODO
What changed
1.1.4
Installed from the release package, the module crashed on load. Companion
showed Connection is not running, kept restarting it, and the log said
Cannot find module '../package.json'. The About block at the bottom of the
connection's config panel read package.json relative to its own source file,
which is fine in a checkout and wrong once the module's bundled for release.
Every packaged release since the About block arrived had it; a checkout on the
developer modules path didn't, which is how it went unnoticed. The About block
now finds what it needs either way and can't stop the module loading.
1.1.3
No change to what the module does. npm test no longer stubs
parseVariablesInString and parseVariablesInField, which
@companion-module/base 2.x doesn't have, so a call to either would now fail the
suite instead of passing it. This module never made one. Also in this release:
@companion-module/base 2.1.3 and @companion-module/tools 3.1.0.
1.1.2
Packaging only; the module's code didn't change.
- The release package couldn't be installed.
companion-module-presentationcommander-server-pkg.tgz was made by
re-tarring the build tool's staging folder, which put package.json one
folder down from where Companion looks. It's now a copy of the archive
companion-module-build makes, and both archives are checked for
package.json and companion/manifest.json at their root before a release
goes out.
- The help button has a page behind it: the module ships
companion/HELP.md.
1.1.1
Maintenance only: the release workflow's actions were updated. The module's
code didn't change.
1.1.0
New: presets, built from the Master Server's live outputs, sources, scenes
and clients. There's one section per output with a button for each routable
target and the tally already wired up, one section for the Client Nodes, and
stage notes.
Two details worth knowing about them:
- The blackout preset lights from the same routing feedback as the crosspoint
buttons, comparing against the empty target. The server represents "unrouted"
as a null
routedSourceId, so it didn't need a feedback of its own.
- Slide buttons light when the Client Node is online, not when the slide has
advanced. The server only forwards next/previous to a client if it's
connected, and otherwise steps its own counter and reports success anyway, so
online is the only signal you can trust.
New: npm test, which runs the module's actual code against a pretend
automation API on a real HTTP server. It covers the generated presets, the tally
feedbacks, and a rejected command being treated as a failure rather than a
success.
License
MIT
This project is built on other people's work — see ATTRIBUTIONS.md.
