Skip to main content
Advanced For developers who want several people to watch one running app. After this page you can open a room as the host, let viewers join it, and handle reloads and reconnects on both sides. A shared session runs one instance of your Unreal app for several people. The host owns the session and the input. Viewers watch the same stream and cannot control it. This is the SDK side of Meeting rooms. The app sends its video once, to a . That server forwards it to the host and to every viewer. Only the host’s input reaches the app.

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.
Pass the room ID exactly as the host page read it. It has the form <id>_<projectId>. A bare ID without the project part does not reach the host, and create() rejects with a TypeError when the ID is missing or has other characters than letters, digits, _ and -.
Both examples leave out the error handling around create(). See Errors and disconnects.

Options

object
Omit it for a private session of one viewer (the default).
string
Host only, optional: rejoin a room you opened earlier in the same page. Pass the previous stream.streamerId. See Rejoin the previous room.
Every other option of 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’s stream.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
The timings behind this table are in Reliability.

Leaving

The host and each viewer end their own page’s session with stream.disconnect() or stream.destroy().

Limits

  • A shared session cannot be combined with Test locally: dev together with shared is refused with a TypeError.
  • 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

Not available yet. The “Your app only” access setting, and the host key described here, are not released on the platform. This section describes how they will work.
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 an sfu field to the body of the ticket request:
ticket-server.ts
  • The response carries sfu: { role: 'host', roomId, hostKey }. The SDK connects as that roomId, and stream.streamerId is that ID: give it to viewers as hostStreamerId.
  • 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

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 room already has a host. Another page opened it first, or this page lost the key for the room (a new tab, or blocked browser storage). Open a new room: call create() without advanced.streamerId.
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.
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 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.