Overview
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
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:
- Create a
Room
object, with options for the session (including default capture and publish settings) - Set up event listeners on the room
- 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.
Leaving a 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.
On some platforms (JavaScript and Swift), Room.disconnect is called automatically when the application exits
Connectivity
LiveKit configures WebRTC to enable connectivity from a wide variety of network conditions. It'll try the following in order of preference.
- ICE over UDP: ideal connection type, used in majority of conditions
- TURN with UDP (3478): used when ICE/UDP is unreachable
- ICE over TCP: used when network disallows UDP (i.e. over VPN or corporate firewalls)
- 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.
Network changes and reconnection
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:
ParticipantDisconnected
fired for other participants in the room- If there are tracks unpublished, you will receive
LocalTrackUnpublished
for them - Emits
Reconnecting
- Performs full reconnect
- Emits
Reconnected
- For everyone currently in the room, you will receive
ParticipantConnected
- 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.