LiveKit JavaScript/TypeScript Client SDK

LiveKit RPC allows participants to call predefined methods on other participants. This is useful for triggering actions in a client application from an Agent or another user.

1. Register a method: Use room.localParticipant.registerRpcMethod(name, handler) to define a method that can be called remotely. The handler receives RpcInvocationData (including payload and callerIdentity) and should return a response.
2. Perform a request: Use room.localParticipant.performRpc({ destinationIdentity, method, payload }) to invoke a method on a specific participant.

Errors: If a handler throws an RpcError, the message is passed to the caller. Other errors arrive as a generic 1500 ("Application Error").

// 1. Registering a method
room.localParticipant?.registerRpcMethod(
  'greet',
  async (data: RpcInvocationData) => {
    return `Hello, ${data.callerIdentity}!`;
  }
);

// 2. Performing the call
try {
  const response = await room.localParticipant!.performRpc({
    destinationIdentity: 'recipient-identity',
    method: 'greet',
    payload: 'Hello!',
  });
  console.log(response);
} catch (error) {
  console.error('RPC call failed:', error);
}

A TokenSource is an abstraction for fetching server URLs and participant tokens. There are several types:

• Fixed (TokenSource.literal): Returns static credentials or uses a function to compute them without external input.
• Configurable (TokenSource.endpoint): Makes a POST (or other method) request to a URL. The request body follows the standard LiveKit token endpoint schema.
• Configurable (TokenSource.developmentTokenServer): Uses a LiveKit-hosted sandbox token server (for prototyping only).
• Configurable (TokenSource.custom): Allows you to implement your own logic for fetching tokens, which are then cached until they expire or options change.

// Example: Using an endpoint token source
const endpoint = TokenSource.endpoint("http://example.com/credentials-endpoint", {
  method: "PUT",
  headers: { "X-Custom-Header": "value" }
});
const response = await endpoint.fetch({ agentName: "my-agent" });
await room.connect(response.serverUrl, response.participantToken);

The Data Tracks Demo demonstrates multi-participant real-time data transmission. One participant (the publisher) sends ASCII-encoded integers via a slider, while another participant (the subscriber) receives these values and renders them on a real-time chart.

To run the demo locally, follow these steps:

1. Configure Environment Variables: Create a .env.local file in the project root containing your LiveKit credentials:
   • LIVEKIT_API_KEY
   • LIVEKIT_API_SECRET
   • LIVEKIT_URL
2. Install Dependencies: Use pnpm to install the required packages.
3. Start the Development Server: Run the dev command.
4. Access the App: Open your browser to the local URL (usually http://localhost:5173).
5. Test Data Transmission: Connect two participants, ensure a data track is published, and use the slider to send data.

# 1. Setup .env.local
LIVEKIT_API_KEY=your_key
LIVEKIT_API_SECRET=your_secret
LIVEKIT_URL=your_url

# 2. Install
pnpm install

# 3. Run
pnpm dev

To start a LiveKit session, create a Room instance, optionally pre-warm the connection with prepareConnection, and then call connect. Once connected, you can publish tracks using localParticipant.enableCameraAndMicrophone() or by manually publishing MediaStreamTrack objects. Use RoomEvent listeners to handle remote tracks being subscribed or unsubscribed to attach them to HTML elements.

import {
  Room,
  RoomEvent,
  Track,
} from 'livekit-client';

const room = new Room({
  adaptiveStream: true,
  dynacast: true,
});

const url = "ws://localhost:7800";
const token = "...";

// Pre-warm connection
room.prepareConnection(url, token);

// Set up event listeners
room.on(RoomEvent.TrackSubscribed, (track, publication, participant) => {
  if (track.kind === Track.Kind.Video || track.kind === Track.Kind.Audio) {
    const element = track.attach();
    parentElement.appendChild(element);
  }
});

// Connect
await room.connect(url, token);

// Publish tracks
await room.localParticipant.enableCameraAndMicrophone();