@laplace.live/persona-sdk

TypeScript SDK and wire schema for the LAPLACE Persona plugin API — a token-authenticated WebSocket API for driving the avatar, scenes, expressions, motions, hotkeys, and tracking parameters from outside the app.

Isomorphic: runs in Node ≥24, Bun, browsers, and OBS browser sources on the global WebSocket. One runtime dependency (zod, backing the wire schemas).

Setup

Enable the API in Persona under Advanced → Plugin API, create a key, and copy the token.

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

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

// Typed request/response
const { scenes, activeSceneId } = await persona.call('scene.list')
await persona.call('expression.toggle', { name: 'Smile' })
await persona.call('scene.patch', {
  background: { mode: 'color', color: '#112233', imageAssetId: null },
})

// Events (subscriptions survive reconnects)
persona.on('motion.started', m => console.log('playing', m.group))

// Parameter leases: the value keeps applying until released; the SDK owns the
// heartbeat, and if your process dies the parameter reverts within ~1 s.
const mouth = persona.driveParameter('MouthOpen', 0.8)
mouth.set(0.3)
mouth.release()

By default the token travels as ?token= (works in browsers). From Node, createNodeClient sends it as an Authorization: Bearer header instead, over Node's global WebSocket, and logs the close that ends a session for good (the key revoked, or the session disconnected in Persona):

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

const persona = createNodeClient({ token, log: console.warn })
await persona.connect()

Any other socket that can set headers, such as the ws package, plugs into new PersonaClient({ token, auth: "header", createWebSocket }).

Identifying your app

Pass clientInfo so your app shows up by name under Connected Clients in Persona's settings (optional — unidentified clients work the same). The SDK re-declares it on every reconnect; it is self-declared and display-only, never authorization:

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

Two server close codes are terminal and stop the reconnect loop: CLOSE_KEY_REVOKED (4001, the key was revoked) and CLOSE_FORCE_DISCONNECTED (4002, the user disconnected the session in Persona). The client reports them via onWarning and goes closed.

Treat the token like a password: it grants control of the app, including loading registered models and web overlays. The server listens on loopback unless LAN access is enabled in Persona's settings.

Registry and catalog metadata

model.list / asset.list return refs with provenance and attribution: every ref carries origin ('bundled' for first-party content, shipped with the app or downloaded from the Persona catalog; 'user' for anything the user added) and may carry optional author / url credits.

CatalogItem is the transport-agnostic content-metadata shape behind pickers: a stable id (scene refs key off it), an InventoryKind, display name, and optional description, thumbnailUrl, previewUrl (a short looping video shown in the thumbnail's place), version, author, url, and download (a CatalogDownload: an https zip with its byte size and sha256). The Persona marketplace serves its catalog as { version, items } at https://marketplace.laplace.live + MARKETPLACE_ITEMS_PATH. healCatalog turns a parsed document into usable rows, dropping malformed ones, and pickLocalized(item.description, locale) reads a description in the reader's language, falling back to English.

healCatalogItem heals one row, and healCatalogRows(raw, healRow) a document through a row healer of your own, keeping the first of two ids equal ignoring case. A row needs an id that passes isCatalogId (one path-safe segment, since an id names an install folder), a non-blank name, and a kind from CATALOG_KINDS; CATALOG_FORMAT is the document's version. healSha256 reads a digest as 64 lowercase hex characters, and payloadEntryPath checks a payload zip's entry name, answering the relative POSIX path an extractor may write, or null; no two of a payload's entries may share a payloadEntryKey. healLocalizedText heals a LocalizedText (en required, the other shipped locales optional) and never promotes another locale to en.