Skip to main content

​
WHEP in-browser guest player

WHEP (WebRTC-HTTP Egress Protocol) is an open IETF draft that plays a live media stream over WebRTC — the browser POSTs an SDP offer to an HTTPS endpoint and the gateway answers in kind. For a broadcast, that means glass-to-glass latency of roughly one second, versus the multi-second playlist latency of HLS. Because the negotiation is plain WHEP, no Orbit vendor SDK is involved on either side: any stock browser (or an external WHEP client such as OBS or VLC) can reach the same endpoint. The dashboard route /voice/video/player/… is a dedicated page that plays one WHEP URL on its own — the kind of link you can hand to a guest viewer with no dashboard role, or embed in your own front-end without wiring up the video SDK. Use the guest player when a viewer needs to watch a live broadcast. Use the Orbit video SDK when the person must join a room as a participant — with their own camera and microphone publishes, room controls, and access-token claims. Watching does not need the SDK.

​
WHEP or HLS — which to hand a guest

The live viewer page defaults to HLS for maximum compatibility and offers WHEP as the low-latency option. Pick per viewer: When in doubt, start the guest on HLS and switch them to WHEP only if they ask for lower latency — the HLS player keeps playing the same broadcast, so nothing is lost by leading with the compatible option. A WHEP endpoint is minted per live broadcast: when a broadcast goes live, its room exposes one WHEP playback URL, and the dashboard surfaces it on the broadcast’s live viewer page (for example from Voice → Broadcasts, or the room’s live sessions view). The URL is valid for exactly that broadcast’s lifetime:
  • Broadcast ends → link goes stale. When the broadcast stops, the WHEP endpoint stops answering (or answers non-200). Any player holding the old link lands on the page’s error-with-retry state.
  • Returning viewer → mint a fresh link. A viewer rejoining a new broadcast needs the URL re-copied from that broadcast’s live viewer page — the link from last week’s broadcast will not play this week’s.
  • The link is capability-based. There is no bearer header and no extra authentication on this path: anyone holding the WHEP URL can watch the live broadcast. Treat it like any share link.
  • Revocation = broadcast stop. The way to cut off holders of a leaked or over-shared link is to stop the broadcast, which retires its WHEP endpoint. There is no per-link revoke: stop the broadcast, start a new one if needed, and share the fresh link only with intended viewers.
The route takes one path segment: the WHEP playback URL, percent-encoded. Construct deep-links with encodeURIComponent:
Copy-pasta a support agent can hand out (replace the two placeholders):
In practice you never build it by character: open the broadcast’s live viewer page and use the WHEP URL row — its Copy grabs the raw endpoint and its Play in browser action opens the finished player link in a new tab. Share either the raw WHEP URL (for external WHEP clients like OBS or VLC) or the player link that Play in browser opens (for a guest in a browser).

​
URL-construction edge cases

  • Malformed or non-HTTP decodes render the empty sheet. The page decodes the segment and only plays it when it resolves to an http(s) address; anything else renders a paste-a-URL hint instead of a blank screen or a thrown error, so a mangled link still tells the visitor what the shape should be.
  • Double-encoding breaks the link. The WHEP URL must pass through encodeURIComponent exactly once. If the value was already encoded (for example pasted out of an already-built player link) and gets encoded again, the page decodes one layer, sees the result is still percent-escapes rather than an http(s) address, and shows the empty sheet. Re-copy the raw endpoint from the WHEP URL row instead of extracting it from a built link.
  • Safe copy sources. Copy from the WHEP URL row on the live viewer page. Copying the finished address out of the browser’s address bar is the most common source of the double-encoding above.

​
Embed the player in your own page

The player route is a normal page, so a guest player embed is just an iframe pointed at the player link:
  • allow="autoplay; encrypted-media" — playback starts muted on load; without autoplay permission most browsers freeze the first frame until a click.
  • sandbox="allow-scripts allow-same-origin" — enough for the player to negotiate WHEP and render; deliberately excludes allow-popups and allow-top-navigation so the embed cannot navigate the host page.
  • Sizing — the video element is aspect-correct (aspect-video), so any 16:9 box renders without letterboxing.

​
Privacy — what this route does not report

The guest player is an anonymous, keyed-by-URL surface: it sends no “watching now” heartbeat and no view count. The authenticated broadcast viewers page is the surface that reports viewership — it is tied to a signed- in session and to the room, so it can heart-beat presence. The guest player is keyed by a raw WHEP URL rather than a room, so nothing a guest viewer does here shows up in the broadcast’s viewer count. If you need per-viewer attendance, hand guests the authenticated viewers page instead of the WHEP link.

​
The playback walk

  1. Join — open the link; the page immediately negotiates the WHEP connection and shows a connecting state.
  2. Live — when the first video track arrives, playback starts on the <video> element. Standard browser controls cover mute/unmute and volume for the audio leg.
  3. Leave — closing the tab or navigating away closes the peer connection against the SFU; nothing on the guest page lingers.
The page watches-one-way: it is a viewer surface, so it does not publish video or audio, and it does not report a “watching now” heartbeat the way the authenticated broadcast viewers page does.

​
Troubleshooting

Match the on-screen state to the cause:
  • Connection stalls in connecting — the ICE handshake timed out before a track arrived. Almost always the recipient’s network egress; use the matrix below.
  • Connection failed with a retry button — the WHEP endpoint answered non-200 or returned an unparsable SDP answer. The broadcast may have ended, or the URL is stale; re-copy the row from the current broadcast’s live viewer page (see link lifecycle above).
  • Negotiated but waiting-for-track — the handshake succeeded but no media is flowing yet (the broadcast publisher has not started, or is muted at the source). This is an explicit state, not a frozen frame; playback starts as soon as a track arrives.
  • Unsupported browser — WHEP depends on RTCPeerConnection with send/ receive SDP negotiation. Every current Chrome, Edge, Firefox, and Safari build supports it; very old or heavily locked-down browser builds that disable WebRTC cannot play and will hit the retry state.

​
Network-egress matrix

WHEP needs UDP to the media server, or a TURN relay when UDP is blocked. Read the viewer’s environment down to the state they will report: If the TURN fallback path is not provisioned for the deployment, WHEP has no recourse on UDP-hostile networks — route those guests to the HLS link, which the live viewer page keeps as the default for exactly this reason.

​
Adjacent guides