Service: Symphony Media Bridge WHIP Gateway - EyevinnOSC/community GitHub Wiki

Symphony Media Bridge WHIP Gateway

Symphony Media Bridge WHIP Gateway (serviceId eyevinn-smb-whip-bridge) provides a WHIP (WebRTC HTTP Ingestion Protocol) endpoint for a Symphony Media Bridge (SMB) SFU. In Eyevinn Open Source Cloud (OSC) it is a long-running service instance. License: MIT. SMB is a media server that handles audio, video and screen sharing streams in an RTC conference system.

What it can do

  • Let any WHIP-compatible client push a media stream to a Symphony Media Bridge instance.
  • Expose the WHIP endpoint at /api/v2/whip/sfu-broadcaster on the instance URL.
  • Protect the WHIP endpoint with an API key (WhipApiKey).
  • Optionally register ingested streams with a WHEP playback endpoint (Service: Symphony Media Bridge WHEP Gateway and the eyevinn-wrtc-egress service) for playback.

Creating an instance

Create a Symphony Media Bridge instance first (eyevinn-docker-wrtc-sfu, see Service: Symphony Media Bridge) and confirm it is running. Then:

  1. Store values as service secrets with create-service-secret (serviceId eyevinn-smb-whip-bridge), for example smburl (https://my-smb.example.org/), smbapikey (the SMB API key) and apikey (the key WHIP clients must present).
  2. Create the gateway with create-service-instance, serviceId: "eyevinn-smb-whip-bridge". A {{secrets.NAME}} reference only works as the entire field value.
{
  "name": "guide",
  "SmbUrl": "{{secrets.smburl}}",
  "SmbApiKey": "{{secrets.smbapikey}}",
  "WhipApiKey": "{{secrets.apikey}}"
}

Use wait-for-service-ready or get-instance-status, then describe-service-instance for the instance URL.

Options

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 instance (feeds SMB_URL), for example https://my-smb.example.org/. A missing trailing slash or wrong instance causes request failures.
SmbApiKey No string, sensitive API key for the Symphony Media Bridge API (feeds SMB_API_KEY). Needed if your SMB instance requires one.
WhepEndpointUrl No string URL of a WHEP endpoint service (eyevinn-wrtc-egress, internal endpoint) used to register ingested streams for playback (feeds WHEP_ENDPOINT_URL).
WhipApiKey No string, sensitive API key that WHIP clients must present in the Authorization field (feeds API_KEY). If not set, the WHIP endpoint is not protected by a key.

Sensitive options should be stored as secrets and passed as {{secrets.NAME}}.

Dependency: Symphony Media Bridge options (eyevinn-docker-wrtc-sfu)

Option Required Type Meaning
name Yes string Name of the instance.
ApiKey No string, sensitive Key for access to the SFU's HTTP API. The default is eyevinn if not specified; OSC can generate one.
VideoCodec No string VP8 (default) or H264.
H264ProfileLevelId No string H264 profile-level-id, default 42001f; 42e01f (Constrained Baseline) is what WebRTC mandates and Safari expects.
H264PacketizationMode No string H264 packetization mode, default 1.
RctlInitialEstimate No string Initial bandwidth estimate in kbps, default 1200.
RctlFloor No string Rate control floor in kbps, default 300.
RctlCeiling No string Rate control ceiling in kbps, default 9000.

See Service: Symphony Media Bridge for details; these settings are read at start and cannot be changed on a running instance.

Using the instance

Use any WHIP-compatible client to send media. An example browser-based client is https://web.whip.eyevinn.technology/. Enter the WHIP URL

https://<tenant>-<instance-name>.eyevinn-smb-whip-bridge.auto.prod-se.osaas.io/api/v2/whip/sfu-broadcaster

(for an instance named guide in a tenant named demo: https://demo-guide.eyevinn-smb-whip-bridge.auto.prod-se.osaas.io/api/v2/whip/sfu-broadcaster) and put the WHIP API key (the WhipApiKey value) in the Authorization field. Press Camera; if everything works you receive a WHIP resource URL. Media is then flowing to Symphony Media Bridge and a new conference with an endpoint with id ingest is created.

For a combined WHIP-to-WHEP setup see Integration: WHIP to WHEP with SMB.

Resources

⚠️ **GitHub.com Fallback** ⚠️