open-live

Open Live is an open source, browser-based live production suite: vision mixer, audio mixer and multiviewer for remote and cloud production, with SRT and WHIP contribution. This repository is the API server; the production controller is open-live-studio and the media engine is Strom.

The quickest way to try it is the managed version on Open Source Cloud at openlive.apps.osaas.io. Plans and included production hours are listed in the pricing section on that page. You can also self-host it: see the self-hosting guide.

For dedicated GPU capacity, see the Hosted GPU add-on in the same pricing section.

The in-app Create New Open Live flow provisions CouchDB for you and generates its admin password automatically. You do not choose or handle that password yourself on this path. The COUCHDB_URL environment variable documented under Configuration below is only for a self-hosted deployment where you run CouchDB yourself; it does not apply to the managed OSC flow above.

Before you start, one thing that is not obvious from the pricing section: if you connect your own ("BYO") Strom instance, its URL must be publicly reachable. A plain local-network or loopback address is rejected, and so is any address that is not reachable from OSC, including a plain Tailscale or other mesh-VPN address in the 100.64.0.0/10 range even though it clears the initial check. To expose a locally hosted Strom instance without port-forwarding, use a public ingress feature such as Tailscale Funnel (opt-in, off by default; also implemented by self-hosted Headscale), which gives the instance a genuinely public ts.net hostname.

• Vision mixing — cuts, auto transitions, DSK layers, picture-in-picture, graphics overlays, and fade-to-black
• Graphics — HTML/image overlays keyed onto the programme via DSK, including OGraf (EBU HTML-graphics spec) templates; see the graphics guide
• Audio mixer — per-channel faders with EBU R128 loudness metering
• Multiviewer — sub-500ms WebRTC glass-to-glass latency
• Stream Deck control — hardware button panel integration
• Up to 16 sources per production
• REMI / remote production — crews work from anywhere via browser; eliminates travel and equipment shipping
• Self-hostable on any Kubernetes cluster, zero vendor lock-in

This repository is the API server. On its own it exposes a REST API and a WebSocket channel — to actually cut a show you also need the two pieces below.

What you need

• Node.js 22 and pnpm 10.33+
• A CouchDB instance (local or remote) — all productions, sources and config live here
• A Strom instance — the GStreamer engine that does the real work: mixing video and audio, compositing graphics, and encoding the programme and multiview outputs. Open Live drives it over its REST and WebSocket APIs and never touches media itself. Run one locally with Docker, or point at an existing instance. See the Strom setup guide.
• open-live-studio — the browser UI. Without it you have an API and no controls.

Quickstart

pnpm install
cp .env.example .env

The minimum to get a server running locally:

COUCHDB_URL=http://admin:password@localhost:5984
STROM_URL=http://localhost:8080
API_KEY=$(openssl rand -base64 32)

Then start it, and point the studio at it:

pnpm dev                                  # this server, on http://localhost:3000
# in open-live-studio: OPEN_LIVE_URL=http://localhost:3000

Create the open-live database in CouchDB before first start. Everything else in Configuration is optional for local development — but read Operating in production before exposing this to a network.

Commands

pnpm dev          # development server with hot reload
pnpm typecheck    # type-check without emitting
pnpm build        # compile TypeScript to dist/
pnpm start        # run the compiled server

All configuration is via environment variables. Copy .env.example to .env and fill in the values:

Never commit .env — it is gitignored. Use .env.example as the reference.

The REST API is documented in docs/openapi.yaml and served as interactive Swagger UI at /documentation. That is the authoritative reference — the list below is a map of what exists, not a complete signature listing.

The WebSocket controller channel — its authentication, inbound message types, and outbound broadcasts — is documented separately in docs/controller-websocket.md.

Sources represent individual video/audio feeds. Each source has a streamType — srt, efp, whip, html, or the built-in test patterns test1 / test2 — and an address (SRT URI, WHIP endpoint URL, or page URL for html). The test-pattern types need no address and are useful for bringing a production up without any ingest.

SRT passphrases are embedded in the source address and encrypted at rest before being stored in CouchDB. For rotating a passphrase or responding to a suspected compromise, see the operator runbook in docs/srt-passphrase-rotation.md.

1. A production is given source assignments (POST /api/v1/productions/:id/sources), plus any outputs and graphics.
2. POST /api/v1/productions/:id/activate builds a Strom flow from the built-in topology in src/lib/default-flow.ts — vision mixer, audio mixer, encoders and WHEP endpoints sized to the production's config — patches each assigned source's address into the matching block, then creates and starts the flow in Strom. The stromFlowId is stored on the production.
3. POST /api/v1/productions/:id/deactivate stops and deletes the Strom flow and clears stromFlowId. If the production records and object storage is configured, it first uploads the recordings on Strom, including any that earlier sessions left there (see Segments left on Strom).

The flow topology is generated, not user-supplied: productions are configured through their sources, outputs, graphics and config values rather than by editing flow JSON.

Graphics are HTML or image overlays rendered by the pipeline and keyed onto the programme output through a downstream keyer (DSK). This supports standards-based HTML templates such as OGraf (the EBU spec, authored with the OGraf Template Editor). See the end-to-end Graphics in Open Live guide for authoring, registering, assigning to a DSK, and taking graphics on air — including an honest note on what is not yet integrated (e.g. the SPX graphics controller).

The defaults are tuned for local development. Before this service is reachable from a network, both of the following apply.

All /api/v1 routes, the WebSocket controller (/ws/), and the Swagger UI (/documentation) are protected by a static API key when API_KEY is set. Clients must send it as a bearer token:

Authorization: Bearer <API_KEY>

Browser WebSocket clients cannot set custom headers, so they carry the key through the Sec-WebSocket-Protocol header instead: offer the two sentinel subprotocols openlive.bearer and openlive.bearer.<API_KEY> via new WebSocket(url, protocols). The server extracts the key from the second (extractSubprotocolKey()) and echoes back only the plain openlive.bearer marker, keeping the secret out of the request URL and access logs. The ?key=<API_KEY> query parameter is not accepted — it was removed in #49 because it leaks the key into proxy/CDN/DevTools logs. See docs/controller-websocket.md for details.

API_KEY must be set for any network-accessible deployment. When API_KEY is unset, every API route is unauthenticated — any client that can reach the service can create, modify, delete, and activate productions. The server refuses to start when NODE_ENV=production and API_KEY is unset, unless TRUST_EXTERNAL_AUTH=true acknowledges that a trusted external auth layer (e.g. the OSC reverse proxy) is handling it instead — NODE_ENV reflects the deployment tier, not the auth architecture, so it can't be used as that signal by itself. Outside production it logs a prominent warning instead of refusing to start. The reference docker-compose.yml requires API_KEY to be set in your .env before the stack will start — generate a strong random value with openssl rand -base64 32.

Strom authentication is configured with STROM_AUTH_TOKEN and STROM_AUTH_MODE. (STROM_TOKEN is still read as a legacy fallback for STROM_AUTH_TOKEN, but new deployments should use STROM_AUTH_TOKEN.)

• STROM_AUTH_MODE=osc (the default) — for a Strom instance behind OSC authentication. Set STROM_AUTH_TOKEN to your OSC Personal Access Token; the server automatically exchanges it for a short-lived Service Access Token (SAT) and refreshes it before expiry. No extra steps needed. Note that an eyevinn-strom instance from the OSC catalogue is not a supported backend — see OSC deployment.
• STROM_AUTH_MODE=direct — for the shared Eyevinn instance and any self-hosted Strom. STROM_AUTH_TOKEN is sent directly as the Authorization: Bearer token with no exchange step.

Leave STROM_AUTH_TOKEN unset when running Strom locally without authentication.

Browsers get their ICE servers from Strom's STROM_SERVER_ICE_SERVERS: the studio through GET /api/v1/ice-servers, and guests in their join response. A guest whose browser cannot reach Strom's own candidates (Strom behind NAT, or in Kubernetes without host networking) connects only through a TURN server on that list. A browser takes a TURN server only with a username and credential (turn:user:pass@host in Strom's list); the guest page leaves out a TURN entry without them. With a TURN server on the list, the page waits up to 6s for ICE gathering, so a guest who cannot reach it goes live that much later.

A TURN server there with long-term credentials (turn:user:pass@host) hands those credentials to every guest who joins, and an invite link is a bearer token that travels through chat and email. Whoever holds a valid invite can use the TURN server to relay traffic, for as long as its credentials stay the same, after the invite has expired or been revoked. Limit that on the TURN server: let it relay only to Strom's addresses (coturn denied-peer-ip / allowed-peer-ip), cap allocations and bandwidth per user, and rotate the credentials. Strom cannot mint time-limited TURN credentials (the TURN REST API scheme, coturn use-auth-secret) yet.

The app is deployed on Open Source Cloud. Environment variables are injected at runtime via an OSC parameter store — no .env file is needed on the server.

Required services: CouchDB (apache-couchdb), parameter store (eyevinn-app-config-svc + valkey).

Strom is not deployed as an OSC service instance. STROM_URL points at a GPU host outside the OSC catalogue (the shared Eyevinn instance, or your own) — see Strom authentication above. The eyevinn-strom catalogue service is not a supported backend.