Mockingbird

LiveKit

@crvouga/mockingbird-service-livekit

Stateful LiveKit emulator with Twirp room APIs, JWT grants, participants, data, SIP/egress controls, and signed webhooks.

Parity: Rooms, grants, and webhooksCommunication6 of 6 operationsIn-process fetchNode servermockingbird-livekit
$
npm install -D @crvouga/mockingbird-service-livekit
Source npm MarkdownAgent discoverySUPPORT.md

Playground

Requests go to the real emulator running in this tab. State persists across requests, and the journal shows what it received. A green dot marks operations whose sample succeeds as-is; others need ids from earlier responses.

Loads the real @crvouga/mockingbird-service-livekit into this tab on first send
https://example.livekit.cloud

Send a request to see the emulator's response.

Operations

6 of 6 operations in the vendored contract are emulated.

MethodPathOperationStatus
POST/twirp/livekit.AgentDispatchService/CreateDispatchCreateDispatchAgent dispatch with a signed roomAdmin JWT; protobuf JSON names accept snake_case or camelCase.
POST/twirp/livekit.AgentDispatchService/ListDispatchListDispatchAgent dispatch with a signed roomAdmin JWT; protobuf JSON names accept snake_case or camelCase.
POST/twirp/livekit.AgentDispatchService/DeleteDispatchDeleteDispatchAgent dispatch with a signed roomAdmin JWT; protobuf JSON names accept snake_case or camelCase.
POST/twirp/livekit.RoomService/{method}RoomService
POST/twirp/livekit.Egress/{method}EgressService
POST/twirp/livekit.SIP/{method}SipService

Documentation

The package README, the same file that ships in the npm tarball.Edit on GitHub

Local emulators. Real API contracts. Part of Mockingbird.

Stateful LiveKit emulator for livekit-server-sdk. It serves Twirp JSON room and agent-dispatch APIs, validates genuine HS256 LiveKit grants, models participant/track/data state, exposes deterministic SIP and egress controls, and emits correctly signed lifecycle webhooks.

Install

Shell
npm install -D @crvouga/mockingbird-service-livekit

ESM only. Node 22+ or Bun 1.2+.

Usage

TypeScript
import { RoomServiceClient } from "livekit-server-sdk"
import { createServer } from "@crvouga/mockingbird-service-livekit/server"

// Test setup: the emulator, with the API key and secret the application signs with.
const emulator = await createServer({
  keys: { fixture: "fixture-secret-that-is-at-least-32-chars" },
})

// The application's client. Only the host changes.
const rooms = new RoomServiceClient(emulator.url, "fixture", "fixture-secret-that-is-at-least-32-chars")
const room = await rooms.createRoom({ name: "consult", emptyTimeout: 60, maxParticipants: 4 })
const listed = await rooms.listRooms() // [room]

await emulator.close()

Point RoomServiceClient at emulator.url. Supported RoomService calls include CreateRoom, ListRooms, DeleteRoom, UpdateRoomMetadata, ListParticipants, GetParticipant, RemoveParticipant, UpdateParticipant, MutePublishedTrack, and SendData. Room creation is idempotent by name and participant identity is unique within a room.

AgentDispatchClient uses the same URL and genuine roomAdmin JWTs for createDispatch, listDispatch, getDispatch, and deleteDispatch. Both snake_case and camelCase request fields work. A dispatch creates a missing room, starts with no assigned jobs, and preserves its agent name and opaque metadata. Lists read shared room dispatch state, with an optional dispatch-id filter; deleting a dispatch removes its membership. Deleting or expiring a room removes its dispatches. Dispatch/job timestamps are emulator-clock Unix seconds encoded as protobuf JSON strings (the SDK exposes bigint values). Tests exercise the existing 2.19.1 SDK and the reporter's exact 2.19.0 over HTTP.

Controls

  • POST /__admin/rooms/:room/participants joins a synthetic participant.
  • DELETE /__admin/rooms/:room/participants/:identity disconnects it.
  • POST /__admin/rooms/:room/participants/:identity/tracks publishes a track.
  • GET /__admin/rooms/:room/participants/:identity/inbox inspects targeted data.
  • GET /__admin/resources and POST /__admin/resources/:id/transition inspect and advance SIP/egress state.
  • POST /__admin/dispatches/:id/jobs scripts one room job with {status?: "JS_PENDING"|"JS_RUNNING"|"JS_SUCCESS"|"JS_FAILED", workerId?, agentId?, participantIdentity?, error?}. First assignment creates a stable job id; later calls update it and stamp its start/end/update times. The default status is running.
  • Dispatches and jobs participate in namespaces, reset, snapshots, Timeline and fault recovery alongside room state.
  • Fault presets include rate limiting, network loss, and webhook duplicate/reorder/drop delivery.

Webhooks cover room, participant, track, egress, and SIP transitions. Each raw body is signed by a short-lived LiveKit access token whose sha256 claim is accepted by the official WebhookReceiver.

API

  • LiveKitAPI, LiveKitAPIOptions, LiveKitEvent: handler and event contract.
  • LiveKitRoom, LiveKitParticipant, LiveKitTrack, DataMessage, AsyncResource, AgentDispatch, AgentJob, JobStatus: durable state.
  • createRuntime, LiveKitRuntime, LiveKitRuntimeOptions: full runtime and webhook hub.
  • LIVEKIT_NAMESPACE, LIVEKIT_PRESETS: constants and fault controls.
  • document, operationIds, supportedOperationIds: generated OpenAPI metadata.
  • createServer, LiveKitServerOptions, DEFAULT_PORT, serveTarget from ./server: Node adapter and CLI integration.

Deliberately not modelled

Real agent worker registration, job execution, publisher dispatch, restart/deployment policies, WebRTC media transport, signaling sockets, transcoding, PSTN calls, production scaling, billing, and dashboards are not modelled. The deterministic server API and lifecycle contract is the initial fidelity boundary.

Official oracles: LiveKit RoomService API and AgentDispatchService API.

↑↓ to navigate↵ to open