Communications · Convex component

convex-livekit

Sync LiveKit rooms, participants, tracks, egress, and ingress into Convex reactively, and manage them directly from Convex functions.

npm GitHub Convex directory Ask about it

npm install convex-livekit

27downloads last week

1,329downloads last 12 months

v0.0.9latest, Sep 18, 2026

9releases since Sep 13, 2026

Downloads

Download history

Loading download history…

Build this

Build with convex-livekit

The install and setup steps from the package documentation.

1
Install
sh
```
npm install convex-livekit
```

Quick Start

1. Add the component

// convex/convex.config.ts
import { defineApp } from "convex/server";
import convexLivekit from "convex-livekit/convex.config";

const app = defineApp();
app.use(convexLivekit);

export default app;

2. Set environment variables

npx convex env set LIVEKIT_API_KEY APIxxxxxxxx
npx convex env set LIVEKIT_API_SECRET your-api-secret
npx convex env set LIVEKIT_HOST https://your-project.livekit.cloud

These come from your LiveKit Cloud project settings (or your self-hosted server's configured key/secret pair).

3. Mount the webhook handler

// convex/http.ts
import { httpRouter } from "convex/server";
import { components } from "./_generated/api";
import { LiveKit } from "convex-livekit";

const livekit = new LiveKit(components.convexLivekit, {
  apiKey: process.env.LIVEKIT_API_KEY!,
  apiSecret: process.env.LIVEKIT_API_SECRET!,
  host: process.env.LIVEKIT_HOST!,
});

const http = httpRouter();

http.route({
  path: "/webhooks/livekit",
  method: "POST",
  handler: livekit.webhookHandler,
});

export default http;

4. Register the webhook in your LiveKit project

In your LiveKit Cloud project settings (or your self-hosted server's webhook config), set the webhook URL to https://<your-deployment>.convex.site/webhooks/livekit. LiveKit signs every webhook with your project's own API key/secret pair — there's no separate webhook secret to configure.

5. Initialize the client

// convex/example.ts
import { action, query } from "./_generated/server";
import { components } from "./_generated/api";
import { LiveKit } from "convex-livekit";
import { v } from "convex/values";

const livekit = new LiveKit(components.convexLivekit, {
  apiKey: process.env.LIVEKIT_API_KEY!,
  apiSecret: process.env.LIVEKIT_API_SECRET!,
  host: process.env.LIVEKIT_HOST!,
});

export const listRooms = query({
  args: {},
  handler: async (ctx) => {
    return await livekit.listRooms(ctx, {});
  },
});

3
Setup
The component needs no schema changes in your app — its tables (rooms, participants, tracks, egress, webhookEvents) live entirely inside the component's own isolated schema. All you need is the webhook mounted (step 3) and a LiveKit client instance wherever you call its methods.

Unlike the other components in this series, convex-livekit never stores a long-lived credential in a header — every server API call and every room-join token is a fresh, short-lived JWT this component signs itself with your API key/secret, following the same convention as LiveKit's own server SDKs.

Usage

Create a room

export const openRoom = action({
  args: { name: v.string(), maxParticipants: v.optional(v.number()) },
  handler: async (ctx, args) => {
    return await livekit.createRoom(ctx, args);
  },
});

Returns { sid, name } and immediately records the room in Convex — you don't have to wait for the room_started webhook to see it in a query.

Mint a join token for a client

export const getJoinToken = action({
  args: { roomName: v.string(), identity: v.string() },
  handler: async (ctx, args) => {
    return await livekit.createRoomToken(args);
  },
});

createRoomToken touches no database — it's a plain signing operation, so it also works from a query if you'd rather not spend an action round-trip. The returned { token } is what you pass to a LiveKit client SDK (room.connect(url, token)).

Remove a participant

export const kick = action({
  args: { roomName: v.string(), identity: v.string() },
  handler: async (ctx, args) => {
    await livekit.removeParticipant(ctx, args);
    return null;
  },
});

Update a participant, or mute their track

export const setAgentState = action({
  args: { roomName: v.string(), identity: v.string(), state: v.string() },
  handler: async (ctx, args) => {
    await livekit.updateParticipant(ctx, {
      roomName: args.roomName,
      identity: args.identity,
      attributes: { "lk.agent.state": args.state },
    });
    return null;
  },
});

export const muteMic = action({
  args: { roomName: v.string(), identity: v.string(), trackSid: v.string() },
  handler: async (ctx, args) => {
    await livekit.mutePublishedTrack(ctx, { ...args, muted: true });
    return null;
  },
});

Both call LiveKit's server API first, then patch the corresponding Convex row so the change is visible in queries immediately — no round trip through a webhook required.

Record or stream a room (egress)

export const startRecording = action({
  args: { roomName: v.string() },
  handler: async (ctx, args) => {
    return await livekit.startRoomCompositeEgress(ctx, {
      roomName: args.roomName,
      filepath: `recordings/${args.roomName}-{time}.mp4`,
    });
  },
});

export const stopRecording = action({
  args: { egressId: v.string() },
  handler: async (ctx, args) => {
    return await livekit.stopEgress(ctx, args);
  },
});

startRoomCompositeEgress records or livestreams the whole room (mixed audio/video of every participant) to a file, one or more RTMP(S) URLs, or both. It uses LiveKit's StartRoomCompositeEgress RPC — the file/stream actually lands wherever your LiveKit server's own storage config (S3/GCP/Azure/local) sends it. Both calls patch the egress row immediately, same pattern as the room/participant/track actions above.

Bring an external stream into a room (ingress)

export const createStreamKey = action({
  args: { roomName: v.string(), identity: v.string() },
  handler: async (ctx, args) => {
    return await livekit.createIngress(ctx, {
      inputType: "rtmp",
      name: `${args.roomName}-obs`,
      roomName: args.roomName,
      participantIdentity: args.identity,
      participantName: args.identity,
    });
  },
});

Returns { ingressId, url, streamKey } — hand url/streamKey to OBS or any RTMP encoder, and it joins the room as a regular participant. updateIngress changes a reusable (RTMP/WHIP) ingress's target room or identity; deleteIngress removes it permanently (unlike the other tables, the row is actually deleted, not kept as history — see ).

Read rooms, participants, tracks, egress, and ingress reactively

tsx

const rooms = useQuery(api.example.listRooms, {});
const participants = useQuery(api.example.listParticipantsByRoom, {
  roomName: "standup",
});
const tracks = useQuery(api.example.listTracksByRoom, { roomName: "standup" });
const ingress = useQuery(api.example.listIngressByRoom, { roomName: "standup" });

Every room_started/room_finished, participant_joined/participant_left/participant_connection_aborted, track_published/track_unpublished, egress_started/egress_updated/egress_ended, and ingress_started/ingress_ended webhook event patches or inserts a row, so these queries re-render live — no polling.

Releases

Version history

Notes come from the changelog.

v0.0.9latestSep 18, 2026
- Fix the Convex directory badge image URL, which still pointed at badge/sholajegede/convex-livekit after the link URL was corrected in a previous release; both now use the plain badge/convex-livekit path.
v0.0.8Sep 17, 2026
- Drop the username scope from the Convex directory badge link in README, matching the directory's updated URL format
v0.0.7Sep 15, 2026
- Correct the 0.0.6 changelog and code comments, which claimed LiveKit's webhook payloads use snake_case field names (event.egress_info, event.ingress_info) the same way Twirp API responses do. Verified against real received webhook events: they're plain camelCase (event.egressInfo, event.ingressInfo, room.numParticipants), so the egress_started/egress_ended/ingress_started/ingress_ended webhook branches were never actually broken. The normalization still runs on webhook payloads — harmless, since it's a no-op on data that's already camelCase — but only Twirp API responses genuinely needed it. No runtime behavior changes.
v0.0.6Sep 14, 2026
- Fix every Twirp API response and webhook payload being read as if LiveKit's server returned camelCase JSON (egressId, roomName, numParticipants). It actually returns the original protobuf field names — snake_case (egress_id, room_name, num_participants) — confirmed against a live StartRoomCompositeEgress response. This broke two ways: a required field like EgressInfo.egress_id came back undefined and startRoomCompositeEgress/createIngress/stopEgress/updateIngress threw ArgumentValidationError on every call, while an optional field like Room.num_participants or Room.max_participants was silently dropped instead of erroring. The egress_started/egress_ended/ingress_started/ingress_ended webhook branches were affected worst of all: LiveKit sends event.egress_info/event.ingress_info, not event.egressInfo/event.ingressInfo, so those branches' && egressInfo/&& ingressInfo guards were always false and silently never ran. Every Twirp response and webhook payload is now normalized from snake_case to camelCase (shallow — one level of keys at a time, so it never touches the caller-defined keys inside a map like ParticipantInfo.attributes) before any field on it is read.
v0.0.5Sep 14, 2026
- Fix every action method on LiveKit (createRoom, startRoomCompositeEgress, createIngress, and the rest) being typed as ctx: GenericActionCtx<GenericDataModel>, which only type-checks when the calling app's schema is empty. Any real app with its own tables — which is every real app — got a compile error on every one of these calls. They now accept a minimal structural ctx type instead, matching the pattern query methods already used.
v0.0.4Sep 14, 2026
- Add egress control: startRoomCompositeEgress and stopEgress, wrapping LiveKit's StartRoomCompositeEgress/StopEgress RPCs and patching the egress row immediately.
- Add ingress support: a new ingress table plus createIngress, updateIngress, deleteIngress, getIngress, and listIngressByRoom, with ingress_started/ingress_ended webhooks keeping live endpoint state in sync.
- Add retry with exponential backoff and jitter to every outbound LiveKit server API call, on 429/5xx responses and network failures, honoring Retry-After when present.
- Fix mutePublishedTrack's request body to use trackSid instead of track_sid, matching the camelCase convention every other request body already used.
v0.0.3Sep 14, 2026
- Handle participant_connection_aborted webhook events the same as participant_left, so an aborted connection no longer leaves a participant stuck at state "joined".
- Add track state: a tracks table plus getTrack, listTracksByRoom, and listTracksByParticipant queries, kept in sync from track_published and track_unpublished webhook events.
- Add participant attributes (for LiveKit Agents state such as lk.agent.state), and updateParticipant / mutePublishedTrack methods to change them and a track's mute state directly.
- Add HTTP-level test coverage for the webhook handler itself (signature verification, idempotency, participant and track lifecycle), not just its underlying mutations.
v0.0.2Sep 13, 2026
- Add demo screenshot to README

convexcomponentlivekitwebrtcvideoroomswebhooksrealtime

License: Apache-2.0