Live guests and co-hosting
Invite or approve viewers for a controlled RTC stage without granting operator access.
On this page
A guest stage lets selected viewers publish RTC media into a room-source broadcast. HLS viewers remain outside the room until accepted and explicitly joined. Playback access does not grant stage or moderator authority.
Prepare the stage
Create a dedicated room with two to four total seats, a stream sourced from that room, and a running broadcast. Reserve one seat for the host and at most three for guests. Room capacity limits RTC participants, not HLS viewers.
Enable the stage before inviting guests. These backend helpers must run as an authorized host/operator; derive recipientSubject from your application's user records.
import { relay } from './relay.js'
export async function createStage(streamId: string, broadcastId: string) {
return relay.streams.guests.configureStage(streamId, broadcastId, {
enabled: true,
version: 0,
maxGuests: 3,
layout: 'grid',
})
}
export async function inviteAudioGuest(
streamId: string, broadcastId: string, recipientSubject: string,
) {
return relay.streams.guests.invite(streamId, broadcastId, {
recipientSubject,
media: { audio: true, video: false, screen: false },
ttlSeconds: 300,
})
}Use version zero only for initial stage configuration; subsequent changes need the current version from getStage. RTMP/WHIP streams need a separate room-based stage workflow; enabling guests does not convert an encoder into an RTC room.
Bind identity and delegate narrowly
Your backend authenticates a user and binds a stable application subject to this stream/run. Never trust a browser-supplied subject, role or delegation without checking it against the signed-in session.
Use createAudienceGrant for narrow audience credentials. Management issuance requires streams:write, streams:publish and tokens:create. Keep management keys on the backend and proxy authorized guest actions through application endpoints.
| Role | Authority |
|---|---|
| Host | Stage controls |
| Co-host or moderator | Only explicitly delegated invite, approve or moderation controls |
| Guest or viewer | Their own requests, invitation decisions and leave action |
Changing audience roles revokes old audience credentials. It does not replace an accepted guest's separate RTC grant; use removal or server moderation to change their publication authority.
Accept and join
The invited user accepts or declines their invitation. A requesting viewer waits for host approval. Acceptance/approval reserves a seat; a join grant carries only the approved audio, video and screen permissions.
Use StreamGuestClient and React guest state to follow the decision and obtain a scoped RTC join grant. Join with devices off, then let the user explicitly enable permitted media. Denying camera access must not prevent permitted microphone-only participation.
While on stage, stop delayed HLS/DVR playback and listen through RTC. This prevents duplicate audio and delayed microphone feedback. After leaving, return to separately authorized viewing.
Moderate and revoke
Server mute changes publication permission and disconnects the old RTC participant. The guest must explicitly rejoin with devices off before enabling media again. Granting permission never activates a device. This differs from a participant's local mute/unmute control.
Removal, leave, expiry, stage disablement, run completion and owning-resource retirement revoke stage authority. After final RTC departure, joining again requires a new request or invitation. A transient disconnect can recover within the existing RTC recovery window while its grant remains valid.
Program behavior and limits
Room-source stages compose participants into the existing program. Ordinary membership/layout changes preserve its output encoder; missing media falls back to black/silence. The host leaving does not automatically end healthy guests or promote a replacement host.
The basic stage uses the mixer canvas and supports grid, single or picture-in-picture; picture-in-picture permits one guest. An advanced mixer can consume the stage as its aggregate primary input.
Defaults allow three reserved guests, one open request/invitation per subject and run, and bounded invitation/join-grant rates. Concurrent approvals still respect room capacity. On conflicts or expired reservations, reload state rather than retrying blindly.
Signed guest lifecycle webhooks complement authenticated status polling. Deduplicate event IDs, reload the roster and avoid logging tokens. RTC session/media accounting is reused rather than duplicating a guest interval. See guest REST APIs and Node controls.