Service: Join Live - EyevinnOSC/community GitHub Wiki
Join Live
Join Live (serviceId eyevinn-join-live) is an open source web application that lets participants join live broadcasts directly from their browser using WebRTC. It is a long-running service instance. It connects to a Symphony Media Bridge (SMB) deployment through a WHIP gateway (ingest) and a WHEP gateway (egress). This page also covers the two gateway services it depends on: eyevinn-smb-whip-bridge and eyevinn-wrtc-egress.
What it can do
- Let participants join a broadcast from a browser (desktop or mobile) after a moderator accepts them.
- Give editors/moderators an interface to accept or reject join requests, manage up to two simultaneous video feeds side by side, and review chat messages before they are displayed.
- Provide a WHEP stream URL in the editor view that can be used as a media source in OBS Studio for recording or re-streaming.
Creating an instance
Join Live needs a WHIP gateway and a WHEP gateway. Both in turn need a Symphony Media Bridge SFU instance (serviceId eyevinn-docker-wrtc-sfu, see the Symphony Media Bridge page). Create the dependencies first and confirm each is running:
- Symphony Media Bridge (
eyevinn-docker-wrtc-sfu), if you do not already have one. - WHEP gateway
eyevinn-wrtc-egress, withSmbUrlset to the SFU URL. See the WHEP Gateway page. - WHIP gateway
eyevinn-smb-whip-bridge, withSmbUrlset to the SFU URL and optionallyWhepEndpointUrlset to the WHEP gateway. See the WHIP Gateway page. - Read the URL of each gateway with
describe-service-instance. - Create Join Live with
create-service-instanceusingserviceId: "eyevinn-join-live". The instance name must be alphanumeric and at most 20 characters.
{
"name": "mybroadcast",
"WhipGatewayUrl": "https://<whip-gateway-instance-url>",
"WhepGatewayUrl": "https://<whep-gateway-instance-url>",
"WhipAuthKey": "{{secrets.whipkey}}"
}
WhipAuthKey is optional. Wait for the instance with wait-for-service-ready, then get its URL with describe-service-instance.
With the OSC CLI:
osc create eyevinn-join-live mybroadcast \
-o WhipGatewayUrl="https://<whip-instance>.svc.prod.osaas.io" \
-o WhepGatewayUrl="https://<whep-instance>.svc.prod.osaas.io"
Options
| Option | Required | Type | Meaning |
|---|---|---|---|
| name | Yes | string | Name of the instance. Alphanumeric, at most 20 characters. |
| WhipGatewayUrl | Yes | string | Base URL of the WHIP gateway instance (eyevinn-smb-whip-bridge) that receives participants' streams. Give only the base URL; the /api/v2/whip/sfu-broadcaster path is added automatically. |
| WhepGatewayUrl | Yes | string | URL of the WHEP gateway instance (eyevinn-wrtc-egress) used for playback of the streams. |
| WhipAuthKey | No | string, sensitive | Authentication key for the WHIP gateway, when the gateway requires one. Store it as a secret and pass {{secrets.NAME}}. |
Symphony Media Bridge WHIP Gateway options
Service eyevinn-smb-whip-bridge (MIT, long-running instance). It provides a WHIP endpoint for a Symphony Media Bridge SFU, so any WHIP-compatible client can push a media stream to it. The WHIP endpoint is at /api/v2/whip/sfu-broadcaster on the instance.
| Option | Required | Type | Meaning |
|---|---|---|---|
| name | Yes | string | Name of the instance. Alphanumeric, at most 20 characters. |
| SmbUrl | Yes | string | URL of the Symphony Media Bridge SFU instance (eyevinn-docker-wrtc-sfu). |
| SmbApiKey | No | string, sensitive | API key for the Symphony Media Bridge API. Store it as a secret. |
| WhepEndpointUrl | No | string | URL of a WHEP endpoint service (eyevinn-wrtc-egress). When set, ingested streams are registered there so they can be played back with WHEP. |
| WhipApiKey | No | string, sensitive | API key the WHIP endpoint requires from clients that push to it. Store it as a secret. Corresponds to WhipAuthKey in Join Live. |
Symphony Media Bridge WHEP Gateway options
Service eyevinn-wrtc-egress (MIT, long-running instance). It is an egress endpoint for standardized WebRTC playback using WHEP (and WHPP) with Symphony Media Bridge as SFU. Channels are managed through an HTTP API (/api/docs has the online API docs).
| Option | Required | Type | Meaning |
|---|---|---|---|
| name | Yes | string | Name of the instance. Alphanumeric, at most 20 characters. |
| SmbUrl | Yes | string | URL of the Symphony Media Bridge SFU instance (eyevinn-docker-wrtc-sfu). |
| SmbApiKey | No | string, sensitive | API key for the Symphony Media Bridge API. Store it as a secret. |
Secrets: WhipAuthKey, WhipApiKey and SmbApiKey are sensitive. A {{secrets.NAME}} reference must be the whole field value, and changing a secret later does not restart a running instance.
Using the instance
- Participants: open the Join Live URL in a browser and select Join to request access to the broadcast. Allow camera and microphone access when prompted.
- Editors/moderators: the editor interface shows incoming join requests, lets you accept or reject participants, manage up to two simultaneous video feeds side by side, and review chat messages before they are displayed.
- OBS Studio: the editor view includes a WHEP stream URL that can be used as a media source in OBS Studio.