Service: Sofie Open Live Gateway - EyevinnOSC/community GitHub Wiki
Sofie Open Live Gateway
Sofie Open Live Gateway (sofie-tsr-open-live, serviceId eyevinn-sofie-tsr-open-live, service page) is a TSR plugin gateway for Sofie Automation that lets Sofie drive an Open Live production over Open Live's controller WebSocket, using the 1.x automation control contract. In Eyevinn Open Source Cloud (OSC) it is a long-running service instance under the MIT license. Source: Eyevinn/sofie-tsr-open-live.
What it can do
- Translate Sofie timeline objects into Open Live commands: program and preview switching, DSK and graphics toggling, audio level and mute changes (with optional ramps), clip cue/play/pause/stop, on-air control and fade-to-black.
- After a reconnect, wait for the HELLO/SNAPSHOT sequence, reset to the state Open Live reports and send only the differences, with keep-alives and command ACK/NACK tracking so Sofie can show command errors.
- Connect outbound to both Sofie Core and Open Live, so no inbound ports are required.
- Authenticate to Open Live in
oscmode (a PAT is exchanged for a short-lived access token sent in theosc.bearersubprotocol) orapiKeymode (self-hosted Open Live, sent as anAuthorization: Bearerheader).
The Open Live URL, production ID and token or auth mode are configured in the Open Live device settings in Sofie, not on the OSC instance.
Creating an instance
Create a Sofie Core instance first and confirm it is running. Use describe-service-instance on it to read its cluster-internal endpoint: use this internal host as CoreHost, not the public URL, because the public URL is behind the OSC auth gate and the gateway cannot send the OSC auth token. The catalog notes that Core listens on port 8080 on the internal endpoint, so set CorePort accordingly rather than relying on the default 3000.
Create service secrets with create-service-secret on serviceId eyevinn-sofie-tsr-open-live:
sofiedevicetoken: any stable value the gateway uses to register with Sofie Core. Keep it the same across restarts.openlivepat(optional): an OSC Personal Access Token, foroscauth mode.openliveapikey(optional): an API key, forapiKeyauth mode with a self-hosted Open Live.
Then call create-service-instance with serviceId: "eyevinn-sofie-tsr-open-live":
{
"name": "mygateway",
"CoreHost": "<internal-core-host>",
"CorePort": "8080",
"DeviceToken": "{{secrets.sofiedevicetoken}}",
"OpenLiveOscPat": "{{secrets.openlivepat}}"
}
Wait for the instance to be running (wait-for-service-ready) and check get-logs-for-instance to see it register with Core. The gateway then registers itself in Core under its device ID. In the Sofie UI, assign it to the studio (Settings, Studio, Peripheral devices) and add an Open Live device with the Open Live URL, production ID and auth mode.
CLI equivalent:
osc create eyevinn-sofie-tsr-open-live mygateway \
-o CoreHost="<internal-core-host>" \
-o CorePort="3000" \
-o DeviceToken="{{secrets.sofiedevicetoken}}"
Options
| Option | Required | Type | Meaning |
|---|---|---|---|
| name | Yes | string | Name of the instance. Alphanumeric, at most 20 characters. |
| CoreHost | Yes | string | Hostname of the Sofie Core the gateway connects to. On OSC use Core's cluster-internal host from the Core instance details. Sets CORE_HOST. |
| CorePort | No | string | Port of Sofie Core, for example 3000. Defaults to 3000 if empty. On Core's cluster-internal endpoint on OSC the port is 8080. Sets CORE_PORT. |
| DeviceId | No | string | Stable ID this gateway registers with in Sofie Core. If empty, the first label of the instance hostname is used. Sets DEVICE_ID. |
| DeviceToken | Yes | string, sensitive | Secret the gateway uses to register with Sofie Core, together with the device ID. Any stable value works; keep it the same across restarts. Sets DEVICE_TOKEN. |
| LogLevel | No | string | Log level of the gateway, for example debug, info, warn or error. Defaults to info in this image. Sets LOG_LEVEL. |
| OpenLiveOscPat | No | string, sensitive | OSC Personal Access Token the gateway uses to log in to Open Live when the Open Live device in Sofie is in osc auth mode. Keeps the token out of Sofie's device settings, where the gateway logs it at startup. A token set in Sofie's device settings still takes precedence. Sets OPEN_LIVE_OSC_PAT. |
| OpenLiveApiKey | No | string, sensitive | API key the gateway sends to a self-hosted Open Live when the Open Live device in Sofie is in apiKey auth mode. Keeps the key out of Sofie's device settings. A key set in Sofie still takes precedence. Sets OPEN_LIVE_API_KEY. |
Sensitive options (DeviceToken, OpenLiveOscPat, OpenLiveApiKey) should be service secrets passed as {{secrets.NAME}} as the whole field value. Changing a secret later does not restart a running instance.