Connecting to rooms

A room is the main construct in LiveKit. Upon successful connection, you're provided a room object to interact with. The two key properties on a room object are the LocalParticipant object, representing the current user, and RemoteParticipants, an array of other users in the room.

You can also listen for room events. Your callbacks will be invoked whenever various states of the room change.

For events happening to a specific participant, they will also be fired on the appropriate RemoteParticipant or LocalParticipant object.

Connecting to a room requires two parameters: a url and a token. The url points to your LiveKit server instance, which, if you followed this guide, is likely ws://localhost:7880.

The token is an access token representing each participant. Each token must include the room name it's authorized to connect to and an unique identify of the participant. If multiple participants connect with the same identity, the earlier participant will be disconnected from the room.

You can use the aformentioned guide to generate a token via CLI, or you can use our server SDK to create one.

The typical flow of events are:

1. Create a Room object, with options for the session (including default capture and publish settings)
2. Set up event listeners on the room
3. Call room.connect(connectOptions)

The main connection option that's relevant is autoSubscribe. When set to true (default), it'll automatically subscribe to all available tracks in the same room.

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'll try 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

ICE over UDP and TCP works out of the box, while TURN requires additional configurations and your own SSL certificate.

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.