Start a shared session
1
The host opens a room
The host page calls
create() with shared: { role: 'host' }. The SDK asks the platform for a ticket that names the host’s room.host.ts
The host page goes through the usual states and reaches
streaming. host.streamerId has the form <id>_<projectId>.2
Give the room ID to the viewers
The SDK does not carry the room ID to other people: that is your page’s job. Send it through your own backend, or put it in a link. This is a pattern, not an SDK feature:
host.ts
3
Each viewer joins the room
A viewer page calls
create() with shared: { role: 'viewer', hostStreamerId }. hostStreamerId is the host’s stream.streamerId, unchanged.viewer.ts
The viewer sees the same picture as the host. Mouse, keyboard and touch do nothing on the viewer’s page.
create(). See Errors and disconnects.
Options
Omit it for a private session of one viewer (the default).
Host only, optional: rejoin a room you opened earlier in the same page. Pass the previous
stream.streamerId. See Rejoin the previous room.create() works as usual for the host. For a viewer, some are ignored: see How host and viewer differ.
Rooms and the host role
The host’sstream.streamerId is the room.
Rejoin the previous room
To come back to the previous room on purpose from the same page, for example from a “Start again” button, pass its ID:How host and viewer differ
When things go wrong
A shared session recovers differently from a normal one, because a fresh app would restart the room under everyone.
Show a viewer what it is waiting for:
viewer.ts
Leaving
The host and each viewer end their own page’s session withstream.disconnect() or stream.destroy().
Limits
- A shared session cannot be combined with Test locally:
devtogether withsharedis refused with aTypeError. - A room has one host. A second host for the same room is refused with
shared-room-taken. - Viewers cannot control the app, cannot change the resolution and cannot send their microphone or camera to the app.
- The host gets no automatic fresh session when the video stops. Offer a “Start again” button on the host page, and rejoin the previous room if you want viewers to stay.
- How hosts and viewers count towards your plan is described in Meeting rooms.
Chat in a shared session
Voice and text chat work the same for hosts and viewers. See Voice chat.Your app only
On a project set to Your app only (not available yet), your server requests the tickets, so your server must ask for the host role itself. Add ansfu field to the body of the ticket request:
- Your server
- Your page
ticket-server.ts
- The response carries
sfu: { role: 'host', roomId, hostKey }. The SDK connects as thatroomId, andstream.streamerIdis that ID: give it to viewers ashostStreamerId. - Use the form the SDK uses for its own room IDs:
<your room id>_<projectId>, with letters, digits,_and-only. - Every participant needs a ticket of its own: the host, each viewer, and a new one for every
create().
Troubleshooting
Viewers do not see the host's stream
Viewers do not see the host's stream
Check the ID the viewer passes as
hostStreamerId. It must be the host’s stream.streamerId, unchanged, with the _<projectId> part. Check that host and viewer use the same appId. Check that the host is streaming: a viewer that opens before the host waits.The host gets a new room on every reload
The host gets a new room on every reload
The room ID is kept in the tab’s
sessionStorage. A new tab starts a new room, and so does a page whose browser storage is blocked, for example inside a third-party frame. A second create() in the same page also opens a new room: in React, pass an AbortSignal so that StrictMode’s first effect starts nothing.A viewer stays in reconnecting
A viewer stays in reconnecting
The viewer is waiting for the host:
waitingForHost is true. It waits for up to 10 minutes, then the session ends with code 4007. The platform may end it sooner.The host's session ended with 4102 and the viewers are waiting
The host's session ended with 4102 and the viewers are waiting
The host’s video stopped, and a host gets no fresh session. Start the host again. To keep the same room, pass
advanced: { streamerId } with the previous stream.streamerId.Next steps
Voice chat
Let host and viewers talk and type.
Reliability
One level up: the reconnect windows and what the SDK does when the video stops.
Options
Reference:
shared, advanced.streamerId and everything else create() accepts.Meeting rooms
The same feature with share links, without code.