livekit-rtc

📹🎙️Node.js realtime SDK for LiveKit

Use this SDK to add realtime video, audio and data features to your Node app. By connecting to a self- or cloud-hosted LiveKit server, you can quickly build applications like interactive live streaming or video calls with just a few lines of code.

Warning

Avoid running this with hot reloads (ex. bun's hot reload). This is known to cause issues with WebRTC connectivity.

Using realtime SDK

Connecting to a room

import {
  RemoteParticipant,
  RemoteTrack,
  RemoteTrackPublication,
  Room,
  RoomEvent,
  dispose,
} from '@livekit/rtc-node';

const room = new Room();
await room.connect(url, token, { autoSubscribe: true, dynacast: true });
console.log('connected to room', room);

// add event listeners
room
  .on(RoomEvent.TrackSubscribed, handleTrackSubscribed)
  .on(RoomEvent.Disconnected, handleDisconnected)
  .on(RoomEvent.LocalTrackPublished, handleLocalTrackPublished);

process.on('SIGINT', () => {
  await room.disconnect();
  await dispose();
});

Publishing a track

import {
  AudioFrame,
  AudioSource,
  LocalAudioTrack,
  TrackPublishOptions,
  TrackSource,
} from '@livekit/rtc-node';
import { readFileSync } from 'node:fs';

// set up audio track
const source = new AudioSource(16000, 1);
const track = LocalAudioTrack.createAudioTrack('audio', source);
const options = new TrackPublishOptions();
options.source = TrackSource.SOURCE_MICROPHONE;

// note: if converting from Uint8Array to Int16Array, *do not* use buffer.slice!
// it is marked unstable by Node and can cause undefined behaviour, such as massive chunks of
// noise being added to the end.
// it is recommended to use buffer.subarray instead.
const sample = readFileSync(pathToFile);
var buffer = new Int16Array(sample.buffer);

await room.localParticipant.publishTrack(track, options);
await source.captureFrame(new AudioFrame(buffer, 16000, 1, buffer.byteLength / 2));

// cleanup resources
await track.close();

RPC

Perform your own predefined method calls from one participant to another.

This feature is especially powerful when used with Agents, for instance to forward LLM function calls to your client application.

Registering an RPC method

The participant who implements the method and will receive its calls must first register support:

room.localParticipant?.registerRpcMethod(
  // method name - can be any string that makes sense for your application
  'greet',

  // method handler - will be called when the method is invoked by a RemoteParticipant
  async (data: RpcInvocationData) => {
    console.log(`Received greeting from ${data.callerIdentity}: ${data.payload}`);
    return `Hello, ${data.callerIdentity}!`;
  },
);

In addition to the payload, your handler will also receive responseTimeout, which informs you the maximum time available to return a response. If you are unable to respond in time, the call will result in an error on the caller's side.

Performing an RPC request

The caller may then initiate an RPC call like so:

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

You may find it useful to adjust the responseTimeout parameter, which indicates the amount of time you will wait for a response. We recommend keeping this value as low as possible while still satisfying the constraints of your application.

Intercepting RPC calls

An RpcInterceptor wraps every RPC the local participant performs or handles, which is useful for logging, tracing, or attaching metadata to payloads. Each method receives the call and a next continuation; return what next returns. Interceptors run in the order they were added, the first being outermost, and errors from the remote side or from your handler flow through them unchanged. Implement only the direction you care about.

const timing: RpcInterceptor = {
  async interceptOutgoing(call, next) {
    const start = performance.now();
    try {
      return await next(call);
    } finally {
      console.log(
        `call ${call.method} -> ${call.destinationIdentity}: ${performance.now() - start}ms`,
      );
    }
  },
  async interceptIncoming(invocation, next) {
    const start = performance.now();
    try {
      return await next(invocation);
    } finally {
      console.log(
        `handled ${invocation.method} from ${invocation.callerIdentity}: ${performance.now() - start}ms`,
      );
    }
  },
};

room.localParticipant!.addRpcInterceptor(timing);

Errors

LiveKit is a dynamic realtime environment and calls can fail for various reasons.

You may throw errors of the type RpcError with a string message in an RPC method handler and they will be received on the caller's side with the message intact. Other errors will not be transmitted and will instead arrive to the caller as 1500 ("Application Error"). Other built-in errors are detailed in RpcError.

Examples

• publish-wav: connect to a room and publish a .wave file
• rpc: simple back-and-forth RPC interaction

Getting help / Contributing

Please join us on Slack to get help from our devs & community. We welcome your contributions and details can be discussed there.