LiveKit Client SDK

Common errors

• ReferenceError: require is not defined

  cause Attempting to use CommonJS `require()` syntax in an ECMAScript Module (ESM) context (e.g., in a modern React or Vue project without a proper build setup for CJS).
  fix Replace `const livekit = require('livekit-client');` with `import * as livekit from 'livekit-client';` or use named imports like `import { Room } from 'livekit-client';`.

• Failed to connect to room: Invalid token

  cause The LiveKit access token provided is expired, malformed, or does not grant the necessary permissions for the requested room and participant identity.
  fix Ensure your token generation logic is correct, the token includes the required `RoomJoin` grant, and the token has not expired. Regenerate the token and verify server-side configuration.

• DOMException: Permission denied

  cause The browser has denied access to the user's camera or microphone. This can be due to user choice, insecure context (non-HTTPS), or system-level permissions.
  fix Ensure your application is served over HTTPS. Prompt the user for media permissions and provide UI guidance. Check browser and operating system privacy settings for camera/microphone access.

• TypeError: livekit.Room is not a constructor

  cause When using `require('livekit-client')` in CommonJS, if the module's export structure doesn't expose `Room` directly as a property, or if the global `LivekitClient` object is not available in a script tag setup.
  fix If using CommonJS, ensure you are accessing `Room` correctly (e.g., `const livekit = require('livekit-client'); const room = new livekit.Room();`). If using a script tag, ensure the global `LivekitClient` object is loaded and use `new LivekitClient.Room()`.

Warnings

• breaking Migrating from v1.x to v2.x involves breaking changes. Consult the official migration guide for a detailed overview of what has changed.
  Fix: Review the LiveKit client SDK v1 to v2 migration guide at https://docs.livekit.io/recipes/migrate-from-v1/ and update your code accordingly.
• breaking The log context field `pID` was renamed to `participantID` for consistency and clarity in logging. This affects how participant identifiers appear in internal logs.
  Fix: Update any custom log parsers or monitoring tools that specifically look for `pID` in LiveKit client logs to use `participantID` instead.
• gotcha Calling `room.prepareConnection(url, token)` as early as possible (e.g., when the page loads) can significantly speed up the actual `room.connect()` time by pre-warming WebRTC resources.
  Fix: Always call `room.prepareConnection(url, token)` proactively to optimize connection latency, even if the user hasn't initiated the call yet.
• gotcha End-to-End Encryption (E2EE) requires careful setup, including key management and server-side configuration, to ensure secure communication. Misconfiguration can lead to failed connections or unencrypted streams.
  Fix: Refer to the LiveKit E2EE documentation for proper setup, ensuring correct key provisioning and compatible server-side configurations. Test thoroughly in your target environment.
• gotcha LiveKit client v2.17.0 introduced a new default RTC path that uses a single peer connection mode, falling back to the legacy dual peer connection mode if necessary. This change aims to improve performance but might alter network behavior for some setups.
  Fix: Monitor network performance and behavior after updating to ensure compatibility. If issues arise, review LiveKit documentation on WebRTC connection paths and configuration options.

Install

• npm install livekit-client npm
• yarn add livekit-client yarn
• pnpm add livekit-client pnpm

Imports

• Room
  wrong:

  const Room = require('livekit-client').Room;

  correct:

  import { Room } from 'livekit-client';

  The primary class for managing real-time connections. While named import is standard for ESM, CommonJS environments typically use `const livekit = require('livekit-client'); const room = new livekit.Room();`.
• RoomEvent
  wrong:

  const RoomEvent = require('livekit-client').RoomEvent;

  correct:

  import { RoomEvent } from 'livekit-client';

  An enum defining all events dispatched by the `Room` object. For CommonJS, access via `livekit.RoomEvent` after `const livekit = require('livekit-client');`.
• VideoPresets
  wrong:

  const VideoPresets = require('livekit-client').VideoPresets;

  correct:

  import { VideoPresets } from 'livekit-client';

  A utility object containing predefined video resolutions and settings. Use named imports for ESM. For CommonJS, access as `livekit.VideoPresets`.

Quickstart

This quickstart demonstrates how to connect to a LiveKit room, handle remote participant track subscriptions, publish local camera and microphone, and manage room events, suitable for browser-based applications.

import {
  LocalParticipant,
  LocalTrackPublication,
  Participant,
  RemoteParticipant,
  RemoteTrack,
  RemoteTrackPublication,
  Room,
  RoomEvent,
  Track,
  VideoPresets,
} from 'livekit-client';

async function setupLiveKitRoom() {
  const url = process.env.LIVEKIT_URL ?? 'ws://localhost:7800'; // Replace with your LiveKit server URL
  const token = process.env.LIVEKIT_TOKEN ?? 'YOUR_LIVEKIT_TOKEN'; // Replace with your LiveKit access token

  if (token === 'YOUR_LIVEKIT_TOKEN') {
    console.error('Please provide a LiveKit access token. You can generate one from your LiveKit server or dashboard.');
    return;
  }

  const room = new Room({
    adaptiveStream: true,
    dynacast: true,
    videoCaptureDefaults: {
      resolution: VideoPresets.h720.resolution,
    },
  });

  // Ensure a parent element exists to attach video/audio streams
  const parentElement = document.getElementById('livekit-container') || document.body;

  room.on(RoomEvent.TrackSubscribed, (track: RemoteTrack, publication: RemoteTrackPublication, participant: RemoteParticipant) => {
    if (track.kind === Track.Kind.Video || track.kind === Track.Kind.Audio) {
      const element = track.attach();
      parentElement.appendChild(element);
      console.log(`Track subscribed: ${track.kind} from ${participant.identity}`);
    }
  });

  room.on(RoomEvent.TrackUnsubscribed, (track: RemoteTrack, publication: RemoteTrackPublication, participant: RemoteParticipant) => {
    const element = track.detach();
    element.remove();
    console.log(`Track unsubscribed: ${track.kind} from ${participant.identity}`);
  });

  room.on(RoomEvent.ActiveSpeakersChanged, (speakers: Participant[]) => {
    console.log('Active speakers:', speakers.map(s => s.identity));
  });

  room.on(RoomEvent.Disconnected, (reason: string | undefined) => {
    console.log('Disconnected from room:', reason);
  });

  room.on(RoomEvent.LocalTrackUnpublished, (publication: LocalTrackPublication, participant: LocalParticipant) => {
    console.log('Local track unpublished:', publication.trackSid);
  });

  console.log('Preparing connection...');
  room.prepareConnection(url, token);

  try {
    await room.connect(url, token);
    console.log('Connected to room:', room.name);
    await room.localParticipant.enableCameraAndMicrophone();
    console.log('Published local camera and microphone.');
  } catch (error) {
    console.error('Failed to connect to LiveKit room:', error);
  }
}

// Call the setup function when the DOM is ready in a browser environment
if (typeof document !== 'undefined') {
  document.addEventListener('DOMContentLoaded', setupLiveKitRoom);
} else {
  // Fallback for non-browser environments or immediate execution
  setupLiveKitRoom();
}