Connecting to Rooms

A Room is the main construct in LiveKit. Rooms are identified by their room name, which is simply a unique string. If a Room with the given name does not exist when a client attempts to connect to it, a new Room is created.

Users connected to a Room are represented by Participant objects. Each Participant has a unique identity (also a string), and may publish audio and video Tracks to the Room. Participants in the same room can subscribe to other Participants' published Tracks.

To connect to LiveKit, create a Room object, then call Room.connect():

const room = new Room();
await room.connect(wsUrl, token);

Room.connect() takes two required parameters:

• wsUrl (websocket URL), points to your LiveKit server. LiveKit Cloud users can find their wsUrl on the Project Settings page. Self-hosted users who followed this guide can use ws://localhost:7880 while developing.

• token is an access token each Participant uses to connect. Each token encodes the room name it's authorized to connect to and a unique identity of the Participant. If multiple Participants connect with the same identity, the earlier Participant will be disconnected from the room.

  Full apps should generate a token on your backend. In development, you can generate tokens using our CLI tool, or (if you're using LiveKit Cloud) on your Keys settings page.

Upon successful connection, the Room object has two key properties: the LocalParticipant object, representing the current user, and RemoteParticipants, an array of other users in the Room.

The Room constructor takes an optional RoomOptions object, which can be used to configure how media is captured and published. For details, see Publishing Tracks.

To handle state changes on the Room, such as when a new Participant joins the room or a new Track is published, see Handling Events.

When your client is leaving a room, you should notify LiveKit of leave events by calling Room.disconnect(). If the application is closed without notifying LiveKit, it will continue to display the participant as being in the Room for another 15 seconds.

LiveKit configures WebRTC to enable connectivity from a wide variety of network conditions. It tries the following in order of preference:

1. ICE over UDP: ideal connection type, used in majority of conditions
2. TURN with UDP (3478): used when ICE/UDP is unreachable
3. ICE over TCP: used when network disallows UDP (i.e. over VPN or corporate firewalls)
4. TURN with TLS: used when firewall only allows outbound TLS connections

With WiFi and cellular networks, users may sometimes run into network changes that cause the connection to the server to be interrupted. This could include switching from WiFi to cellular or going through spots with poor connection.

When this happens, LiveKit will attempt to resume the connection automatically. It reconnects to the signaling WebSocket and initiates an ICE restart for the WebRTC connection. This process usually results in minimal or no disruption for the user. However, if media delivery over the previous connection fails, users might notice a temporary pause in video, lasting a few seconds, until the new connection is established.

In scenarios where an ICE restart is not feasible or unsuccessful, LiveKit will execute a full reconnection. As full reconnections take more time and might be more disruptive, a Reconnecting event is triggered. This allows your application to respond, possibly by displaying a UI element, during the reconnection process.

This sequence goes like the following:

1. ParticipantDisconnected fired for other participants in the room
2. If there are tracks unpublished, you will receive LocalTrackUnpublished for them
3. Emits Reconnecting
4. Performs full reconnect
5. Emits Reconnected
6. For everyone currently in the room, you will receive ParticipantConnected
7. Local tracks are republished, emitting LocalTrackPublished events

In essence, the full reconnection sequence is identical to everyone else having left the room, and came back.

Participants may be disconnected from a room due to server-initiated actions. This can happen if the room is closed using the DeleteRoom API or if a participant is removed with the RemoveParticipant API.

In such cases, a Disconnected event is emitted, providing a reason for the disconnection. Common disconnection reasons include:

• DUPLICATE_IDENTITY: Disconnected because another client with the same identity joined the room.
• ROOM_DELETED: The room was closed via the DeleteRoom API.
• PARTICIPANT_REMOVED: Removed from the room using the RemoveParticipant API.
• JOIN_FAILURE: Failure to connect to the room, possibly due to network issues.
• ROOM_CLOSED: The room was closed because all Standard and Ingress participants have left.