Persona

@laplace.live/persona-sdk is the official TypeScript and JavaScript client library for the LAPLACE Persona Plugin API, and serves as the single source of truth for its wire protocol schema. This page provides a complete type and API reference. For server configuration, API key management, and WebSocket RPC method specifications, see the Plugin API documentation.

The SDK runs across Node.js 22+, Bun, modern web browsers, and OBS browser sources. Its only runtime dependency is zod, which defines and validates all wire schemas.

npm install @laplace.live/persona-sdk

What You Can BuildCopy Anchor Link

The Persona Console is the official reference implementation built on this SDK. It provides a complete web-based control console in a single browser tab, letting creators manage scenes, layers, asset libraries, expressions, motions, parameter bindings, hotkeys, tracking sources, and global settings, with an interface optimized for mobile touch devices during live broadcasts.

The console contains no proprietary desktop code. It interacts with Persona exclusively through the Plugin API, demonstrating that third-party integrations can achieve equivalent control using the same SDK.

When building client applications, follow these recommended design patterns:

• Gate on capabilities, not on model formats or version numbers: Query InstanceRuntime.capabilities before exposing controls, disabling unsupported features dynamically rather than catching unsupported-for-format errors;
• Treat reconnections as cache invalidations: Broadcast events missed while disconnected are not replayed; cached data may diverge from the host. Flush local caches and re-query state snapshots upon reconnecting;
• Handle terminal close codes appropriately: Status codes 4001 (key revoked) and 4002 (session disconnected by user) represent terminal closures and should stop reconnection loops; other disconnects should trigger exponential backoff retries;
• Rely on SDK subscription management: Listeners registered via persona.on(…) are restored automatically upon reconnecting, eliminating manual subscription bookkeeping.

LLM PromptCopy Anchor Link

Provide the following prompt to an LLM or include it in your project's CLAUDE.md or AGENTS.md rules file to supply complete contextual guidance for developing Persona plugins:

You are helping me build a plugin for LAPLACE Persona, a desktop VTuber app
(https://laplace.live/persona). Persona exposes a local WebSocket server called the
Plugin API, and `@laplace.live/persona-sdk` is its typed client.

Before writing any code, fetch the reference documents listed at the end — they are
the single source of truth for method names, events, error codes and types. Do not
rely on memory and do not invent names.

## Setup

- Install `@laplace.live/persona-sdk`. Isomorphic: Node 22+, Bun, browsers and OBS
  browser sources. Its only runtime dependency is zod.
- The user enables the server in Persona under Settings → Plugin API and creates an
  API key there. Tokens look like `sk-lp-v1-…`. Default endpoint: `ws://127.0.0.1:25034`.
- Everything — values and types — is exported from the package root; there is no
  other entry point.

## Client

```ts
import { PersonaClient } from "@laplace.live/persona-sdk";

const persona = new PersonaClient({
  token: "sk-lp-v1-…", // required; everything else is optional
  clientInfo: { name: "My Plugin", version: "1.0.0" }, // display-only identity
});
await persona.connect();

const { scenes, activeSceneId } = await persona.call("scene.list");
await persona.call("scene.patch", {
  background: { mode: "color", color: "#00ff00", imageAssetId: null },
});
persona.on("motion.started", (m) => console.log("playing", m.group));

const mouth = persona.driveParameter("MouthOpen", 0.8); // parameter lease
mouth.set(0.3);
mouth.release();
```

`call(method, params?)` is fully typed — the method name determines the request and
response shapes.

Methods cover scenes, model instances, stage objects, expressions, motions, speech,
hotkeys, automations, model and asset registration, settings, tracking and pose
input, per-key storage and parameter injection. Events notify you of scene,
selection, expression, motion, speech, tracking and registry changes.

The exact method and event names, parameter shapes, error codes and limits live in
the reference below — look them up instead of guessing. Gate features on the
capabilities reported by `app.info` and `instance.list`, never on version strings.

## Reference

Fetch these before writing code. The documentation is served as raw Markdown —
append `.mdx` to any page URL (`.en.mdx` for English):

- https://laplace.live/persona/plugin-api.en.mdx — server setup, API keys, and every
  method, event, error code and limit
- https://laplace.live/persona/sdk.en.mdx — the SDK client: options, auth modes and
  every exported type

Client ReferenceCopy Anchor Link

import { PersonaClient } from "@laplace.live/persona-sdk";

const persona = new PersonaClient({ token: "sk-lp-v1-…" });
await persona.connect();

const { scenes, activeSceneId } = await persona.call("scene.list");
await persona.call("scene.patch", {
  background: { mode: "color", color: "#00ff00", imageAssetId: null },
});
persona.on("motion.started", (m) => console.log("playing", m.group));

Instantiate PersonaClient using the options below. Only token is required:

ClientInfoCopy Anchor Link

clientInfo declares the client identity displayed in the desktop application under Settings → Plugin API → Connected Clients. It is optional, self-declared display metadata and does not affect access permissions. The SDK re-announces this payload upon every reconnection.

const persona = new PersonaClient({
  token,
  clientInfo: { name: "My Overlay", version: "1.2.0", developer: "You" },
});

AuthenticationCopy Anchor Link

In browser environments, the API token is passed via the ?token= query parameter due to browser WebSocket API constraints. In Node.js or Bun environments, you can supply a custom createWebSocket hook that passes the token as an Authorization: Bearer header using ws:

import WebSocket from "ws";

const persona = new PersonaClient({
  token,
  auth: "header",
  createWebSocket: (url, headers) => new WebSocket(url, { headers }),
});

WebSocketLike defines the structural interface required by createWebSocket. Both global browser WebSocket instances and the Node.js ws client satisfy this contract without type assertions.

In Node.js 22+, the global WebSocket accepts handshake headers through its WebSocketInit extension. The SDK's createNodeClient helper builds a client on top of it:

• Sets auth: 'header'
• Uses Node's global WebSocket
• Sets a 5-second connection timeout
• Sends SDK warnings and terminal close notices (key revoked or force-disconnected) to the log function you pass

import { createNodeClient } from "@laplace.live/persona-sdk";

const persona = createNodeClient({
  token: "sk-lp-v1-…",
  log: console.warn,
});
await persona.connect();

Parameter LeasesCopy Anchor Link

driveParameter writes a continuous value to a model parameter and returns an InjectionHandle. The SDK maintains lease heartbeats automatically. The lease expires approximately one second after the last write, restoring default parameter behavior safely if the client process terminates unexpectedly.

const mouth = persona.driveParameter("MouthOpen", 0.8);
mouth.set(0.3);
mouth.release();

A parameter can be leased by only one active session at a time; concurrent attempts return a conflict error.

The method accepts an optional weight multiplier and an onError callback invoked if heartbeat renewal fails in the background, removing the need to await individual updates.

Connection Close HandlingCopy Anchor Link

onClose reports disconnects that come from the server or the network. The callback receives the raw socket close code, the reason string, and a terminal flag that says whether reconnect retries have stopped.

• It fires after the SDK has finished its internal cleanup, so calling close() inside the handler is safe.
• A clean close() initiated by the client does not trigger onClose.
• Once onClose is set, terminal disconnects are reported there instead of through onWarning.

PersonaClientState and Client ErrorsCopy Anchor Link

type PersonaClientState = "closed" | "connecting" | "open" | "reconnecting";
type ClientErrorReason =
  | "connect-timeout"
  | "connection-closed"
  | "client-closed"
  | "not-connected"
  | "request-timeout";

When the client or its transport fails connect() or call(), the promise rejects with a PersonaClientError carrying reason: ClientErrorReason (one of CLIENT_ERROR_REASONS). Server error frames reject call() with PersonaApiError (code: ApiErrorCode). See Plugin API: Error Codes.

ConstantsCopy Anchor Link

The SDK also exports these value lists and helpers:

• API_ERROR_CODES, CLIENT_ERROR_REASONS, EVENT_NAMES, INPUT_NAMES, TIME_INPUT_NAMES, RANDOM_PULSE_INPUT_NAMES, MODIFIER_TOKENS, APP_CAPABILITIES, FPS_LIMIT_PRESETS, EFFECTS_QUALITY_LEVELS: as const arrays, so a UI picker can list every valid value
• isApiErrorCode, isEventName, isAppCapability, isTimeInputName, isRandomPulseInputName: the matching TypeScript type guards
• injectTargetKey: builds a normalized injection target string
• personaWsUrl: builds a WebSocket URL from { host, port, secure } (PersonaAddress, where host must be a plain host name or IP address) or from an address string the user typed (bare hostnames, host:port, IPv4/IPv6 literals, and full ws:// or wss:// URLs); PersonaClient appends the token when connecting
• parseHost, parsePort, isValidPort: validate a plain host name or IP address (accepting bare or bracketed IPv6 and returning null for schemes, ports, paths, or zone IDs) and a port number
• requestTimeoutMs(method, fallbackMs): resolves the timeout for a request method (scene.activate and asset.import use their extended defaults)

Models and AssetsCopy Anchor Link

Models and general assets share a unified metadata structure. kind defines the asset classification, while origin identifies its source: bundled for built-in samples and content downloaded on demand from the Persona catalog, and user for locally registered files, accompanied by author attribution metadata.

type ModelFormat = "live2d" | "vrm";
type ContentOrigin = "bundled" | "user";
type AssetKind =
  | "image"
  | "video"
  | "audio"
  | "prop"
  | "ibl"
  | "lut"
  | "animation"
  | "cameraMotion"
  | "lyrics";
type InventoryKind = ModelFormat | AssetKind | "effect" | "addon";

effect represents a virtual asset type without a backing disk file, used by the asset library to enumerate built-in effects; addon represents an optional application add-on (such as the Webcam Tracking Add-On) that extends the app rather than adding a scene layer.

model.list returns an array of ModelRef objects and asset.list returns an array of AssetRef objects. Both extend ContentRef with kind narrowed to ModelFormat and AssetKind respectively.

Both also carry a boolean exists flag. On an AssetRef it says whether the asset file is still on disk; a ModelRef sets it to false when the model's entry file is missing.

CatalogItemCopy Anchor Link

CatalogItem defines transport-agnostic metadata used by asset pickers. Both local registry items and remote catalog listings normalize to this type. It removes the installation-specific origin field from ContentRef and adds localized description (LocalizedText) and catalog metadata. download (CatalogDownload) describes retrieval parameters for remote items; if absent, the item exists locally.

Catalog and localization helpers:

• CATALOG_FORMAT, MARKETPLACE_ITEMS_PATH, CATALOG_KINDS: catalog manifest format version, the public catalog endpoint path (/api/items), and the supported catalog item kinds
• isCatalogId, healCatalog, healCatalogItem, healCatalogRows, healSha256: validate and sanitize remote or local catalog manifests
• payloadEntryPath, payloadEntryKey, catalogMediaFile (takes a CatalogMediaRole): resolve the extracted entry path of a catalog payload and the dot-prefixed file names for a source's rendered thumbnail and preview video (.thumbnail.avif and .preview.webm)
• pickLocalized(text, locale), healLocalizedText: pick the display string for a UI locale from a LocalizedText object and sanitize localized text maps

PlacementCopy Anchor Link

2D screen space is measured in pixels from the stage center (+y down). 3D world space is measured in meters. All rotations in the wire schema use radians (converted to degrees in user interfaces).

Place2D and Place3D represent placement definitions for scene objects, sharing identical position fields with an added opacity channel.

Scene ItemsCopy Anchor Link

The items array in a scene orders models and objects together according to their Z-order:

type SceneItem = SceneModelItem | SceneObjectItem;

ObjectContentCopy Anchor Link

The payload of a scene object is determined by its kind field. Except for capture (display capture), all object types can be created directly in the desktop interface, as described in Layer Management.

type ObjectContent =
  | { kind: "image"; assetId: string }
  | {
      kind: "video";
      assetId: string;
      loop: boolean;
      muted: boolean;
      volume: number;
    }
  | { kind: "prop"; assetId: string }
  | {
      kind: "web";
      url: string;
      width: number;
      height: number;
      fps: number;
      transparent: boolean;
      css: string;
      layer: WebLayer;
      shutdownWhenHidden: boolean;
    }
  | { kind: "capture"; source: CaptureKind; sourceId: string; label: string };

type ObjectSpace = "2d" | "3d";
type WebLayer = "behind" | "front";
type CaptureKind = "display" | "window";

AttachmentCopy Anchor Link

AttachAnchorCopy Anchor Link

type AttachAnchor =
  | { kind: "root" }
  | { kind: "bone"; bone: string }
  | {
      kind: "artMesh";
      id: string;
      verts: [number, number, number];
      weights: [number, number, number];
    };

object.anchors returns available attachment anchors provided by a parent model as AnchorOption records, pairing anchor identifiers with human-readable labels. VRM models provide the root transform and humanoid bones; Live2D models provide the root transform and individual ArtMeshes with an order draw-order index.

AttachDepthCopy Anchor Link

type AttachDepth =
  { kind: "front" } | { kind: "behind" } | { kind: "artMesh"; id: string };

depth controls the internal layering of Live2D props attached to a parent Live2D model, positioning the item behind the model, in front of the model, or directly above a specified ArtMesh. Configured via instance.attach.

Attachment helpers:

• depthStops(meshes): the available depth stops from back to front (behind the model, above each ArtMesh in draw order, then in front)
• depthStopIndex(meshes, depth): which stop a depth sits at; an ArtMesh the model no longer has counts as the frontmost
• pinRiders(items, instanceId): every item attached to instanceId, directly or through other items, so circular attachments can be prevented
• pinnableParents(models, items, instanceId): the candidate parents, with invalid ones marked ridesThis
• defaultAttach(parentInstanceId, screenSpace?): a fresh attachment (root anchor, in front, unsplit, no physics tuning). With screenSpace set (a Live2D model or 2D object), the item also follows the host's head at the default response

ScenesCopy Anchor Link

BackgroundCopy Anchor Link

type BackgroundMode = "color" | "image";

CameraCopy Anchor Link

cameraDistanceLimits(environment, radius) computes how close and how far the orbit camera may go. The defaults are DISTANCE_MIN (0.35 m) and DISTANCE_MAX (20 m); when a 3D environment's bounding radius differs a lot from a standard room (~10 m), the limits scale with it. radius is the bounding radius that scene.inspect returns under environment.radius; when it is null, the default limits apply.

LightingCopy Anchor Link

type SceneLightType = "directional" | "point" | "ambient" | "area" | "spot";
type ShadowQuality = "off" | "low" | "medium" | "high" | "ultra";
type ShadowFilter = "pcf" | "pcss";

SCENE_LIGHT_TYPES, SHADOW_QUALITY_LEVELS, and SHADOW_FILTERS are as const arrays defining supported light types, shadow qualities, and filter modes matching interface order.

Three SceneLight fields make a light follow the camera:

• followCamera: binds the light's position and orientation to the camera view
• followCameraOptions: which degrees of freedom follow the camera's motion; DEFAULT_LIGHT_FOLLOW_CAMERA_OPTIONS enables all of them
• followCameraReference: the frozen reference transform for the axes that don't follow

To turn following on or off without moving the light, call scene.setLightFollowCamera instead of editing these fields; see Lighting.

iblAssetId and modelAssetId set the image-based lighting (IBL) map and the 3D stage environment. Releases with the environment-map-model capability accept both at once.

• Use environmentWithAsset() to change either one: it sets the new asset, keeps the other, and resets light overrides tied to the old model.
• Selecting an IBL texture turns bakeFromModel off. Baking defaults to on only when a 3D model is loaded into an empty environment.
• environmentClearPatch(environment, slot) builds a patch that clears 'model' or 'map', or both when slot is null.
• applyEnvironmentLighting() and applyEnvironmentLook() back the panel's quick actions: they apply the environment lighting preset and an EnvironmentLook profile.

Volumetric lighting is enabled per light through SceneLight.volumetric. Related helpers:

• SCENE_VOLUMETRIC_LIGHTING_SPECS: the numeric ranges of the volumetric fog sliders
• defaultSceneVolumetricLighting(): the default fog settings
• healSceneVolumetricLighting(): clamps out-of-range values
• sceneLightCanHaze(type): whether a light type supports volumetric scattering
• sceneLightHazes(light): whether a light is emitting volumetric light right now

EffectsCopy Anchor Link

SceneEffects uses a flat schema: every toggleable post-processing effect is exposed as a top-level property, enabling generic reflection and iteration. Visual grouping in user interfaces is a presentation concern independent of the wire schema.

Effect ordering in the Layer List is tracked separately in environment.effectLayers (an array of ToggleEffectKey strings). This list is orthogonal to the enabled flag: enabled activates rendering, while effectLayers controls layer item presentation. Enabling an effect automatically appends it to the layer list.

type SceneToneMapping = "none" | "neutral" | "aces" | "agx";

Gradient provides 24 blend modes defined in EffectBlendMode, enumerated in EFFECT_BLEND_MODES.

rain and snow share standard effect structures but operate as 3D geometric particle systems rather than 2D screen-space post-processing passes; see Rain and Snow.

Model and object layers have their own effect pipelines. effects and effectLayers on SceneModelItem and SceneObjectItem run before the scene-wide effects and are set with instance.setEffects.

• Layer effects support the subset in LayerEffectKey: color, levels, colorWheels, colorShift, selectColors, gradient, blur, bloom, diffusion, sketch, rim, outline, and dropShadow.
• Bloom color selection works only at the layer level; see Layer Effects.

TransitionsCopy Anchor Link

transition configures the visual transition when activating a scene; see Scene Transitions (requires scene-transitions capability). SCENE_TRANSITION_TYPES lists valid transition styles, defaultSceneTransition() returns standard cuts, and healSceneTransition() validates configurations.

environment.itemTransition governs entrance and exit animations for models, props, and spawned items; see Showing and Hiding. ITEM_TRANSITION_STYLES enumerates supported styles, defaultItemTransition() defaults to a 300 ms glitch effect, and ITEM_TRANSITION_MAX_MS imposes a 5000 ms ceiling.

Scene PresetsCopy Anchor Link

presets lists the scene's saved scene presets in display order; builds without the scene-presets capability omit it. Manage the active scene's presets with preset.create, preset.update, preset.rename, preset.setTransition, preset.delete, and preset.apply; see Plugin API: Scene Presets.

• SCENE_PRESET_TRANSITIONS: every preset transition
• scenePresetIsCurrent(): whether the stage's current layout matches a preset; the desktop and Web Console use it to highlight that preset
• capturePresetItems(): captures a layer layout
• presetStep(): computes each layer's change when a preset is applied

Runtime StateCopy Anchor Link

instance.list reports dynamic capabilities for active stage items, allowing clients to disable unsupported controls without triggering RPC errors:

type InstanceCapability =
  | "motions"
  | "expressions"
  | "placement-2d"
  | "placement-3d"
  | "mtoon"
  | "idle-clips"
  | "idle-motions"
  | "pose"
  | "breath"
  | "expression-weights"
  | "live2d-params"
  | "speech"
  | "post-fx";