Service: Symphony Media Bridge - EyevinnOSC/community GitHub Wiki
Symphony Media Bridge
Symphony Media Bridge (serviceId eyevinn-docker-wrtc-sfu, catalog page) is an open source WebRTC Selective Forwarding Unit (SFU) that routes real-time media between participants without transcoding. It is a long-running service instance.
What it can do
- Forward streams selectively between WebRTC participants instead of mixing them, which reduces server CPU usage and lets each participant control which streams it receives.
- Support multi-participant video conferencing, live production workflows and WebRTC distribution applications.
- Be managed through an HTTP API protected by an API key.
- Work with the companion WHIP and WHEP gateways for ingest and egress.
Creating an instance
Call create-service-instance with serviceId: "eyevinn-docker-wrtc-sfu". There are no OSC service dependencies. Store the API key as a secret first (create-service-secret, serviceId: "eyevinn-docker-wrtc-sfu", name apikey).
{ "name": "mysfu", "ApiKey": "{{secrets.apikey}}" }
To use H264 instead of VP8:
{
"name": "mysfu",
"ApiKey": "{{secrets.apikey}}",
"VideoCodec": "H264",
"H264ProfileLevelId": "42e01f"
}
Verify with wait-for-service-ready or get-instance-status, then describe-service-instance for the URL. The health endpoint returns 200 OK when the bridge is ready:
curl https://<instance-url>/api/health
Options
| Option | Required | Type | Meaning |
|---|---|---|---|
| name | Yes | string | Name of the instance. Alphanumeric, at most 20 characters. |
| ApiKey | No | string, sensitive | Key that must be sent in the api-key header of HTTP API requests. The previous documentation gives the default as eyevinn; set your own for any production deployment. Pass a secret as {{secrets.NAME}}. |
| VideoCodec | No | string | Video codec used by the bridge: VP8 (default) or H264. Use H264 to bridge to H264-based tooling such as SRT/MPEG-TS gateways. |
| H264ProfileLevelId | No | string | H264 profile-level-id. Default 42001f. Use 42e01f (Constrained Baseline), which WebRTC mandates and Safari expects. |
| H264PacketizationMode | No | string | H264 packetization mode. Default 1. |
| RctlInitialEstimate | No | string | Initial bandwidth estimate in kbps. Default 1200. Consumers that do not send REMB (for example GStreamer webrtcbin) stay at this estimate. |
| RctlFloor | No | string | Rate control floor in kbps. Default 300. |
| RctlCeiling | No | string | Rate control ceiling in kbps. Default 9000. |
{{secrets.NAME}} must be the entire field value. Overwriting a secret does not restart a running instance. The codec and rate control options are read when the instance starts and cannot be changed on a running instance; to change them, delete and recreate the instance (do not rely on update-service-instance for them).
Using the instance
All management endpoints need the api-key header.
# List active conferences
curl https://<instance-url>/api/conferences -H "api-key: <your-api-key>"
# Create a conference
curl -X POST https://<instance-url>/api/conferences \
-H "Content-Type: application/json" \
-H "api-key: <your-api-key>" \
-d '{"last-n": 3}'
The response includes an id for the new conference. Typical flow for participants, who connect via WebRTC:
- Create a conference.
- Create an endpoint per participant:
POST /api/conferences/{conferenceId}/endpoints. - Exchange the SDP offer and answer through the endpoint API.
- The SFU forwards media between the endpoints.
See the Symphony Media Bridge documentation for the full signaling protocol.
Example with the OSC CLI:
osc create eyevinn-docker-wrtc-sfu mysfu -o ApiKey="{{secrets.apikey}}"
Resources
- Symphony Media Bridge on GitHub
- Symphony Media Bridge WHIP Gateway for WHIP ingest
- Symphony Media Bridge WHEP Gateway for WHEP egress
- Working with Secrets