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 livekit-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 re-establish the connection behind the scenes. It'll fire off a Reconnecting event so your client could display additional UI to inform the user. If the reconnection is successful, you will receive a Reconnected callback to let you know that things are back to normal. Otherwise, it'll disconnect you from the room.

During the reconnection, the video/audio tracks may stop sending/receiving data for a few seconds. When the connection is re-established, the tracks will then "unfreeze". This process is called a ICE restart.

In certain cases where an ICE restart isn't possible (or has failed). LiveKit will automatically perform a full reconnection. 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.