Skip to main content

Play a Stream with WHEP

Give a WebRTC player sub-second access to a live stream, such as a monitor, a producer view or a small interactive audience. For large audiences, use HLS instead: WHEP opens one connection per viewer.

Before you start​

  • A room with an active stream to play, for example from OBS over WHIP. You need its meetingID and the stream's sessionID.
  • A WHEP-capable player that sends a bearer token.

1. Create a playback​

From your server:

curl -X POST "https://mediasfu.com/v1/meetings/$MEETING_ID/playbacks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MEDIASFU_API_USERNAME:$MEDIASFU_API_KEY" \
  -d "{\"sourceSessionID\":\"$SESSION_ID\",\"tracks\":[\"audio\",\"video\"]}"

The response includes:

{
  "success": true,
  "playbackID": "…",
  "protocol": "whep",
  "state": "…",
  "endpointUrl": "https://…",
  "playbackToken": "…",
  "tokenExpiresAt": "…"
}

2. Connect the player​

Give endpointUrl and playbackToken to your WHEP player, using the player's own bearer-token setting. Don't put the token in a page URL.

MediaSFU aligns RTP payload types with the stream: a WHEP client first reads the endpoint's payload profile, then posts its receive-only offer. A 406 PAYLOAD_TYPE_MISMATCH response means the player's offer doesn't match the stream; fix the player configuration rather than retrying. The Familiar Calls app includes a working browser WHEP player to start from.

3. End playback​

curl -X DELETE "https://mediasfu.com/v1/meetings/$MEETING_ID/playbacks/$PLAYBACK_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MEDIASFU_API_USERNAME:$MEDIASFU_API_KEY" \
  -d '{"reason":"event_finished"}'

Delete playbacks before you delete the stream they play.

See the streaming HTTP reference for every field and route.