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.
Connecting to a Room
To connect to LiveKit, create a
Room object, then call
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
wsUrlon the Project Settings page. Self-hosted users who followed this guide can use
tokenis 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.
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.
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.
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.
Room.disconnect is called automatically when the application exits.
LiveKit configures WebRTC to enable connectivity from a wide variety of network conditions. It tries 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
LiveKit Cloud supports all of the above connection types. TURN servers with TLS are provided and maintained by LiveKit Cloud.
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:
ParticipantDisconnectedfired for other participants in the room
- If there are tracks unpublished, you will receive
- Performs full reconnect
- For everyone currently in the room, you will receive
- Local tracks are republished, emitting
In essence, the full reconnection sequence is identical to everyone else having left the room, and came back.