client-sdk-js

livekit-client is the official browser SDK for LiveKit, a WebRTC platform for building realtime video, audio, and data applications. It wraps the complexities of WebRTC connection negotiation, adaptive bitrate streaming, simulcast, and end-to-end encryption behind a Room object and a small set of participant/track abstractions, so an app can join a call, publish a camera or microphone, and subscribe to remote tracks in a few lines of code.

The SDK targets production video/voice use cases beyond simple demos: adaptive streaming that adjusts subscribed video quality to viewport size, dynacast to skip encoding unwatched simulcast layers, end-to-end encryption via a dedicated worker, structured data channels (reliable and lossy) for chat or app state, and an RPC layer for calling methods across participants — the last of which is explicitly designed to forward LLM function calls in LiveKit Agents-based voice AI applications.

Under the hood it manages two peer connection transports (publisher and subscriber), a signaling client built on WebSocket with automatic reconnection and region failover, and a state machine (machina) driving connection lifecycle transitions. It ships as ESM and UMD bundles plus separate web worker bundles for E2EE and frame-metadata processing, and is transpiled via Babel against a defined browserslist target so it runs across Chrome, Firefox, Safari, and Edge on both desktop and mobile.

What You Get

• A Room class that manages the full connection lifecycle — signaling over WebSocket, publisher/subscriber peer connections, automatic reconnection, and region failover.
• LocalParticipant/RemoteParticipant and Track abstractions with one-line helpers like setCameraEnabled, setMicrophoneEnabled, and setScreenShareEnabled.
• Adaptive streaming and dynacast, which automatically adjust subscribed video quality and skip encoding unwatched simulcast layers to save bandwidth and CPU.
• Built-in end-to-end encryption via a dedicated E2EE web worker, plus a separate frame-metadata worker bundle.
• Reliable and lossy data channels for structured data streams (chat, cursors, app state) alongside media tracks.
• An RPC layer (registerRpcMethod / performRpc) for calling methods directly between participants, built for use with LiveKit Agents to forward LLM function calls to clients.
• A TokenSource abstraction (literal, endpoint, development token server, or fully custom) for fetching connection credentials in different auth setups.

Common Use Cases

• Adding live video/audio calling to a web app (multi-party rooms with camera, mic, and screen share).
• Building voice/video interfaces for AI agents, using LiveKit Agents plus the SDK’s RPC layer to forward function calls between an agent and the browser client.
• Live streaming and broadcast-style apps that need adaptive quality and bandwidth-efficient subscriber fan-out.
• Realtime collaborative apps that need both media tracks and structured data channels (e.g. shared cursors, chat) over one connection.
• Privacy-sensitive video apps requiring end-to-end encryption between participants rather than trusting the media server.

Under The Hood

Architecture The SDK is organized around Room (src/room/Room.ts, ~3,100 lines), which owns two RTCPeerConnection transports coordinated through PCTransportManager/PCTransport, a RTCEngine (src/room/RTCEngine.ts) that mediates between the signaling layer and the transports, and a machina-driven state machine tracking connection/reconnection state. Signaling itself is isolated in src/api/SignalClient.ts with its own state machine (SignalClientStateMachine.ts) and a WebSocketStream wrapper, keeping wire-protocol concerns separate from room/track logic. Participants (Participant, LocalParticipant ~2,200 lines, RemoteParticipant) and tracks (LocalTrack/RemoteTrack and their audio/video subclasses) form a clear class hierarchy, while cross-cutting features — E2EE (src/e2ee/), data streams (src/room/data-stream/), data channels (src/room/data-channel/), and RPC (src/room/rpc/, split into client/server) — live in their own directories with narrow responsibilities, so a change to, say, E2EE key rotation doesn’t ripple into track publishing code.

Tech Stack Written in TypeScript, built with Rollup into ESM/UMD bundles plus separate worker bundles for E2EE and frame-metadata (rollup.config.js/.worker.js/.fm-worker.js), then downleveled for older TS consumers via downlevel-dts. Core runtime dependencies are minimal and purpose-built: @livekit/protocol (generated protobuf types for the LiveKit signaling protocol), @livekit/mutex, machina (finite state machines), webrtc-adapter (cross-browser WebRTC shims), sdp-transform, jose (JWT handling for TokenSource), and loglevel for pluggable logging. Babel transpiles against an explicit .browserslistrc target for broad browser compatibility. Vite powers the example apps (examples/demo, examples/rpc, examples/state-machine).

Code Quality Tests are extensive and colocated (~50 *.test.ts files) using Vitest, including dedicated e2e specs (*.e2e.test.ts, vitest.e2e.config.mts) that spin up a real Chromium instance via Playwright against a Go mock signaling server, in addition to unit tests run in happy-dom. Errors are modeled explicitly through a LivekitError/LivekitReasonedError class hierarchy with numeric codes and named reasons (documented in the README’s error code table) rather than bare thrown strings. The project runs ESLint (with import, a11y-style, and machina-specific plugins), Prettier with import sorting, tsc --noEmit type-checking, and publint/size-limit checks, all wired into GitHub Actions workflows (test.yaml, e2e.yaml, size-limit.yaml, smoke.yaml) — a mature, CI-enforced quality bar.

API Design The public surface centers on a small number of well-named entry points — Room, RoomEvent, Track, createLocalTracks — with common flows (enable camera/mic, publish a track, attach to an element) requiring only one or two calls, while advanced capabilities (E2EE, RPC, custom token sources, data streams) are opt-in and namespaced away from the basic path. Extensive JSDoc comments annotate public classes and methods, and the README doubles as a structured usage guide covering device management, audio autoplay restrictions, logging hooks, and token generation patterns — keeping the getting-started curve shallow despite the underlying protocol complexity.