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:

  1. Create a conference.
  2. Create an endpoint per participant: POST /api/conferences/{conferenceId}/endpoints.
  3. Exchange the SDP offer and answer through the endpoint API.
  4. 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