Skip to main content

Build a hybrid WebRTC stage and HLS audience

Use a small realtime stage for active speakers and a separate HLS program for a larger passive audience. The canonical reference keeps those surfaces and authorities separate, so an audience viewer does not accidentally receive room controls or contributor-floor audio.

Build this: follow the live guest queue tutorial. View the live pattern: open the hybrid stage and audience showcase. Compare it with maintained repositories in the Starter Projects catalog. There is no maintained standalone repository for this pattern yet.

The journey​

  1. The host opens a bounded stage room through an authenticated backend.
  2. Contributors redeem role-bound links and join the WebRTC stage; a passive viewer redeems a directory grant for the broadcast surface.
  3. The host selects active stage members, publishes the requested member HLS sources, and coordinates the audience playback intent.
  4. Speakers remain conversational over WebRTC while viewers follow the HLS live edge and its bounded clock controls.
  5. The host ends the stage and broadcast. Viewers stop at the ended state after the backend confirms cleanup.

Invitation and authority​

The backend creates contributor and viewer grants with explicit roles. A viewer grant is limited to the broadcast directory and never contains a room secret; the server can rotate or revoke directory access. The application owns role presentation and playback intent. MediaSFU owns WebRTC room tracks and events; the server-owned HLS boundary owns broadcast resources.

Room lifecycle​

Keep stage closed, joining, ready, active, starting, and ended separate from audience preparing, playable, paused, and ended. Start a member broadcast only when a current stage member with audio or video can be resolved. Stop each broadcast, leave/end the stage, clear controller authority, and report success only after confirmed upstream teardown.

Media identity​

Resolve stage members by stable member identity before producer lookup. A local camera, remote camera, screen, and member HLS source are distinct identities. The active stage chooses screen, identified remote camera, then local camera as primary, with participant mini cards beside it. HLS audience playback is a program surface, not a stage participant.

Primary and mini media​

The WebRTC stage keeps the selected source primary and the other speakers in a mini rail. The HLS audience receives the program and no contributor-floor audio unless your backend explicitly admits that viewer to the room. Never infer that a member is live from a prepared card or directory entry alone.

Remote audio​

Mount contributor room audio independently from stage video. Passive HLS viewers remain outside that floor-audio path unless the backend explicitly admits them.

Responsive layout​

Keep the active speaker stage and playback status in one bounded container. On narrow screens, move the speaker rail and audience controls below the stage without merging their audio paths. Give HLS playback its own measured surface, autoplay handling, and ended-state controls.

Failure states​

Treat a missing member source, delayed HLS manifest, autoplay refusal, expired directory grant, reconnect, and ended broadcast as visible audience states. A stage error should not masquerade as an HLS error; show a retry or leave action for the affected surface and preserve the other surface when possible.

Cleanup​

Stop member HLS compositions, stop playback, remove directory and room listeners, leave/end the stage, and clear host controller authority. Make host cleanup idempotent on explicit end, page exit, and unmount. A viewer stops playback and clears its grant when the broadcast enters ended state.

Product evolution​

An earlier hybrid flow could ask the audience to play before a manifest existed and could confuse a stage member source with the passive program. The stable lesson is server-authorized directory rotation, manifest readiness before playability, and a strict separation between WebRTC stage media and HLS audience delivery.

Choose and test your platform​

Use the React showcase for stage/audience roles, playback protocol, directory grants, HLS source handling, and cleanup. The Watch Together repository offers related WebRTC/HLS examples for Vue, Angular, Expo Web, React Native, Flutter, Kotlin Android, and Unity, but it is not a drop-in port of this stage layout. Test HLS, audio, autoplay, reconnect, and teardown on the target platform.

Release checklist​

Use an authenticated backend, test one host, one contributor, and one passive viewer, verify stage audio, member HLS readiness, autoplay recovery, directory expiry, narrow layout, and ended playback, and define how your product handles clock drift and audience retention.