Skip to main content

Connection and callbacks

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 the particular local participant. You can use the aformentioned guide to generate a token via CLI, or you can use our server SDK to create one.

TypeScript
import {
connect,
ParticipantEvent,
RoomEvent,
} from 'livekit-client'

const url = 'wss://your_host'
const token = 'jwt_token'

// after connection, you could set up listeners
connect(url, token).then(async (room) => {
// when a media track is subscribed to, ready for playback
room.on(RoomEvent.TrackSubscribed, (track, publication, participant) => {})

// when a media track has been unsubscribed
room.on(RoomEvent.TrackUnsubscribed, (track, publication, participant) => {})

room.on(RoomEvent.ParticipantConnected, (participant) => {
// set up any per-participant callbacks
participant.on(ParticipantEvent.TrackMuted, (publication) => {})
})
room.on(RoomEvent.ParticipantDisconnected, (participant) => {})

// teardown room
room.on(RoomEvent.Disconnected, () => {})
})

See listing of Room events and Participant 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 the LiveKit, it will continue to display the participant as being in the room for more than 20 seconds.

Connectivity

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 (443): used when firewall blocks all other UDP port other than 443
  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 automatically, 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 an 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".