Connecting to LiveKit

Overview

You connect to LiveKit through a Room object. A room is a core concept that represents an active LiveKit session. Your app joins a room—either one it creates or an existing one—as a participant.

Participants can be users, AI agents, devices, or other programs. There's no fixed limit on how many participants a room can have. Each participant can publish audio, video, and data, and can selectively subscribe to tracks published by others.

LiveKit SDKs provide a unified API for joining rooms, managing participants, and handling media tracks and data channels.

Install the LiveKit SDK

LiveKit includes open source SDKs for every major platform including JavaScript, Swift, Android, React Native, Flutter, and Unity.

npm install livekit-client @livekit/components-react @livekit/components-styles --save

<dict>
...
<key>NSCameraUsageDescription</key>
<string>$(PRODUCT_NAME) uses your camera</string>
<key>NSMicrophoneUsageDescription</key>
<string>$(PRODUCT_NAME) uses your microphone</string>
...
</dict>

dependencies {
  implementation "io.livekit:livekit-android:2.+"
  implementation "io.livekit:livekit-android-compose-components:1.+"
}

dependencyResolutionManagement {
    repositories {
        //...
        maven { url 'https://jitpack.io' }
    }
}

npm install @livekit/react-native @livekit/react-native-webrtc livekit-client

flutter pub add livekit_client livekit_components

If your SDK isn't listed above, check out the full list of platform-specific quickstarts and SDK reference docs for more details.

LiveKit also has SDKs for realtime backend apps in Python, Node.js, Go, Rust, Ruby, and Kotlin. These are designed to be used with the Agents framework for realtime AI applications. For a full list of these SDKs, see Server APIs.

Connect to a room

A room is created automatically when the first participant joins, and is automatically closed when the last participant leaves. Rooms are identified by name, which can be any unique string.

You must use a participant identity when you connect to a room. This identity can be any string, but must be unique to each participant.

Connecting to a room requires two parameters:

• wsUrl: The WebSocket URL of your LiveKit server.

  Find your project URL

  LiveKit Cloud users can find their Project URL on the Project Settings page.

  Self-hosted users who followed this guide can use ws://localhost:7880 during development.

• token: A unique access token which each participant must use to connect.

  The token encodes the room name, the participant's identity, and their permissions. For help generating tokens, see this guide.

const room = new Room();
await room.connect(wsUrl, token);

<LiveKitRoom audio={true} video={true} token={token} serverUrl={wsUrl}>
  <!-- your components here -->
</LiveKitRoom>

RoomScope(url: wsURL, token: token, connect: true, enableCamera: true) {
  // your components here
}

RoomScope(
  url = wsURL,
  token = token,
  audio = true,
  video = true,
  connect = true,
) {
  // your components here
}

<LiveKitRoom audio={true} video={true} token={token} serverUrl={wsUrl}>
  <!-- your components here -->
</LiveKitRoom>

final room = Room();
await room.connect(wsUrl, token);

After successfully connecting, the Room object contains two key attributes:

• localParticipant: An object that represents the current user.
• remoteParticipants: A map containing other participants in the room, keyed by their identity.

After a participant is connected, they can publish and subscribe to realtime media tracks, or exchange data with other participants.

LiveKit also emits a number of events on the Room object, such as when new participants join or tracks are published. For details, see Handling Events.

Disconnect from a room

Call Room.disconnect() to leave the room. If you terminate the application without calling disconnect(), your participant disappears after 15 seconds.

Automatic disconnection

Participants might get disconnected from a room due to server-initiated actions. This can happen if the room is closed using the DeleteRoom API or if a participant is removed with the RemoveParticipant API.

In such cases, a Disconnected event is emitted, providing a reason for the disconnection. Common disconnection reasons include:

• DUPLICATE_IDENTITY: Disconnected because another participant with the same identity joined the room.
• ROOM_DELETED: The room was closed via the DeleteRoom API.
• PARTICIPANT_REMOVED: Removed from the room using the RemoveParticipant API.
• JOIN_FAILURE: Failure to connect to the room, possibly due to network issues.
• ROOM_CLOSED: The room was closed because all participants left.

Connection reliability

LiveKit enables reliable connectivity in a wide variety of network conditions. It tries the following WebRTC connection types in descending order:

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

Network changes and reconnection

With WiFi and cellular networks, users might run into network changes that cause the connection to the server to be interrupted. This can include switching from WiFi to cellular or going through areas with poor connection.

When this happens, LiveKit attempts to resume the connection automatically. It reconnects to the signaling WebSocket and initiates an ICE restart for the WebRTC connection. This process usually results in minimal or no disruption for the user. However, if media delivery over the previous connection fails, users might notice a temporary pause in video, lasting a few seconds, until the new connection is established.

In scenarios where an ICE restart is not feasible or unsuccessful, LiveKit executes a full reconnection. Because full reconnections take more time and might be more disruptive, a Reconnecting event is triggered. This allows your application to respond, possibly by displaying a UI element, during the reconnection process.

This sequence executes as follows:

1. ParticipantDisconnected event is emitted for other participants in the room.
2. If there are tracks unpublished, a LocalTrackUnpublished event is emitted for them.
3. A Reconnecting event is emitted.
4. Performs a full reconnect.
5. A Reconnected event is emitted.
6. For everyone currently in the room, you receive a ParticipantConnected event.
7. Local tracks are republished, emitting LocalTrackPublished events.

A full reconnection sequence is identical to having everyone leave the room, then coming back (that is, rejoining the room).

Additional resources

The following topics provide more information on LiveKit rooms and connections.