Persona

@laplace.live/persona-sdkはプラグインAPIの型付きクライアントであり、通信スキーマの正式な定義でもあります。このページは型のリファレンスです。サーバーの有効化、キー、メソッド一覧についてはプラグインAPIを参照してください

アイソモーフィックです——Node 22+、Bun、ブラウザ、OBSブラウザソースで動きます——実行時の依存はワイヤースキーマを支えるzodだけです

npm install @laplace.live/persona-sdk

何が作れるか

Persona Consoleは、このSDKで何ができるかを示す公式のリファレンス実装です。アプリ全体のリモコンで——シーン、レイヤーとそれを埋めるインベントリ、表情、モーション、パラメータのバインド、ホットキー、トラッキング、設定——それらがブラウザのタブ1枚に収まり、配信中にスマートフォンから操作する前提でレイアウトされています

注目すべきは、デスクトップ側のコードをまったく取り込んでいないことです。プラグインAPIがその契約のすべてであり、つまりコンソールにできることは、同じSDKで書いたものなら何にでもできます

真似する価値のあるパターンがいくつかあります：

• 形式ではなくケイパビリティで判定する。インスタンス単位の各セクションは、まず呼び出してunsupported-for-formatを処理するのではなく、InstanceRuntime.capabilitiesを読んで自ら無効化します
• 再接続はキャッシュの破棄として扱う。ソケットが切れている間に見逃したイベントは再送されないので、遅延取得したデータは「少し古い」のではなく無効です——再接続時に捨てて、必要なものを読み直してください
• 終端的なクローズコードを正しく扱う。4001と4002は再接続するなという意味です。それ以外は再試行する価値があります
• 購読はSDKに任せる。persona.on(…)は再接続後に購読を張り直すので、呼び出し側で管理する必要はありません

LLMプロンプト

下のプロンプトをAIアシスタントに貼り付けるか、プロジェクトのCLAUDE.mdやAGENTS.mdのようなルールファイルに保存してください。プラグインを書いてもらうのに必要な背景はこれでひととおり揃います。どのモデルにも読みやすいよう英語で書かれており、引用しているドキュメントURLはそのまま取得できます

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

クライアント

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));

PersonaClientは次のオプションで構築します。必須なのはtokenだけです

ClientInfo

clientInfoは、自分のアプリがPersonaの設定の接続中のクライアントにどの名前で並ぶかを決めます。省略可能で、自己申告であり、表示専用です——認可には決して使われません——SDKが再接続のたびに申告し直します

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

認証

既定ではトークンは?token=クエリパラメータで渡されます。ブラウザではこれしかできません。Nodeではリクエストヘッダーを設定するソケットを渡すことで、トークンをAuthorization: Bearerヘッダーとして送れます——別途インストールしたwsパッケージを使います：

import WebSocket from "ws";

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

WebSocketLikeはcreateWebSocketが返すべきソケットの形です。グローバルのWebSocketもwsのクライアントも構造的にこれを満たすので、型アサーションは不要です

パラメータリース

driveParameterはモデルのパラメータに値を継続的に設定し、InjectionHandleを返します。ハートビートはSDKが担当し、リースは最後の書き込みからおよそ1秒で期限切れになります——つまりプロセスが落ちればパラメータは固まったままにならず、自動的に元へ戻ります

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

1つのパラメータを同時に保持できるセッションは1つだけです。2つ目はconflictエラーを受け取ります

3つ目の引数にはweightに加えてonErrorも渡せます。バックグラウンドのハートビートが失敗したときに通知されるので、呼び出し側が更新のたびにawaitする必要はありません

クローズ

onCloseは、サーバーまたはネットワーク由来のクローズをすべて報告します。元のソケットのクローズコードと理由に加えて、クライアントが再接続しないものを示すterminalが付きます。クライアント自身の処理（状態、保留中の呼び出し）が終わったあとで発火するので、その中でclose()を呼んでも安全です。自分から呼んだclose()は報告されません。これを指定した場合、終端的なクローズはonWarningを通らなくなります

PersonaClientState

type PersonaClientState = "closed" | "connecting" | "open" | "reconnecting";

定数

API_ERROR_CODES、EVENT_NAMES、INPUT_NAMES、APP_CAPABILITIES、FPS_LIMIT_PRESETS、EFFECTS_QUALITY_LEVELSはas constの配列として提供されるので、ピッカーがアプリの受け付ける値を正確に列挙できます。isApiErrorCode、isEventName、isAppCapabilityはそれらの型ガードで、injectTargetKeyは注入対象の正規化されたキーを構築します

personaWsUrlはホスト、ポート、secureフラグ——またはユーザーが入力した1行のアドレス——からソケットのURLを組み立てます。host、host:port、角括弧の有無を問わないIPv6、そしてそのまま通す完全なws(s):// URLに対応します。トークンはここには含まれず、PersonaClientが自分で付け足します。parsePortとisValidPortは対になる入力検証です

モデルとアセット

モデルとアセットは同じ形のエントリを共有します。kindは常にそのエントリが何かを、originは常にどこから来たかを表します——bundledはアプリに同梱されたもの、userはユーザーが登録したものです。その隣に、アプリのコンテンツマニフェストが宣言した作者クレジットが並びます

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

effectはファイルを指さない唯一の種類です。インベントリはこれを使って内蔵エフェクトを並べます

model.listはModelRef——kindをModelFormatに絞ったContentRef——を返します。asset.listはAssetRefを返し、こちらはkindをAssetKindに絞ったうえでexistsが加わります。ファイルがディスクから消えるとfalseになります

CatalogItem

CatalogItemはコンテンツ選択に使う、転送方式に依存しないメタデータ型です。ローカルの登録項目とリモートのカタログ項目を共通の形式で扱えます。ContentRefからインストール前には未確定のoriginを除き、カタログ情報を追加したものです。downloadは未インストール項目の取得方法を示し、省略されていればローカルに存在します

配置

スクリーン空間はピクセル単位で、原点はステージの中心です。ワールド空間はメートル単位です。パネルには角度で表示されますが、ワイヤー形式での回転はすべてラジアンです

Place2DとPlace3Dはオブジェクト版です——フィールドは同じで、opacityが加わります

シーンアイテム

シーンのitems配列は、モデルとオブジェクトをz順で一緒に保持します

type SceneItem = SceneModelItem | SceneObjectItem;

ObjectContent

オブジェクトが描画する内容で、kindで区別されます。captureを除き、現時点でいずれもUIから作成できます——レイヤーを参照してください

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";

ピン留め

AttachAnchor

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

object.anchorsは親が提供するアンカーをAnchorOptionとして返します——アンカーと、その表示名の組です。VRMはモデルルートとヒューマノイドのボーンを、Live2Dはモデルルートとすべてのアートメッシュを返します。アートメッシュの各行には、リストを取得した時点の描画順であるorderも付きます

AttachDepth

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

depthは、Live2Dアイテムが追従先のモデルの内側のどこに描かれるかです——後ろ、前面、またはそのアートメッシュの1つのすぐ上。使われるのは、Live2Dモデルに追従するLive2Dインスタンスだけで、instance.attachで設定します

depthStops(meshes)は深さのコントロールの段を後ろから前へ並べます——後ろ、描画順に各アートメッシュの上、前面。depthStopIndex(meshes, depth)はある深さがどの段にあるかを返し、親にもうないアートメッシュは最前面の段として扱います。pinRiders(items, instanceId)はinstanceIdに直接、または連なるピン留めを介して追従しているすべてのインスタンスを返します。これらにはピン留めできません。pinnableParents(models, items, instanceId)はそこからピン留め先の選択肢を作り、無効にすべきものにridesThisを付けます。defaultAttach(parentInstanceId)は新しいピン留めで、アンカーはルート、位置は前面、分割もチューニングもありません

シーン

背景

type BackgroundMode = "transparent" | "color" | "image";

カメラ

cameraDistanceLimits(environment, radius)は、マウスでの操作が守る距離の範囲を返します。DISTANCE_MINとDISTANCE_MAX、つまり0.35と20で、シーンの3Dセットが幅10メートルほどの部屋より大きく、または小さく配置されていると、比率に応じて広がります。radiusはセット自身のバウンディング半径で、scene.inspectのenvironment.radiusから取ります——セットの読み込みが終わるまではnullで、古いビルドは返しません——nullを渡すと通常の範囲になります

ライティング

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

SCENE_LIGHT_TYPES、SHADOW_QUALITY_LEVELS、SHADOW_FILTERSは、ライトの種類、シャドウの段階、フィルターをas constの配列として提供します。順序はパネルと同じです

followCameraはライトの位置と角度をカメラ基準にし、followCameraOptionsはカメラのどの動きに追従するかを選び——DEFAULT_LIGHT_FOLLOW_CAMERA_OPTIONSは3つともオンです——followCameraReferenceはオフにした選択肢が固定した値を持ちます。ライトを動かさずに追従を切り替えるには、フィールドを直接書き換えずにscene.setLightFollowCameraを呼んでください。ライティングを参照してください

iblAssetIdとmodelAssetIdはそれぞれ環境マップと3Dセットを指定し、environment-map-modelを持つビルドは両方を同時に受け付けます。書き込みにはenvironmentWithAsset()を使ってください。この関数は選んだほうを設定してもう一方は残し、出ていくセットに紐づいていたライトの上書きを落とします。マップを選ぶとbakeFromModelはオフになり、マップもセットもなかった所にセットが入ったときだけオンになり、セットが別のセットに替わるときはそのまま残ります。nullなら両方を消します。environmentClearPatch(environment, slot)は'model'、'map'、またはnullで両方を削除する編集を組み立てます。モデルを消すとbakeFromModelとそのライトの上書きも一緒に消え、マップだけを消すと照明は残ったセットに引き継がれます。ほかの2つのヘルパーはパネルのボタンに対応します。applyEnvironmentLighting()は2つのライトルートを有効にしてシーン自身のライトを理想の強さまで下げ、applyEnvironmentLook()はEnvironmentLookをシーンに適用します

SCENE_VOLUMETRIC_LIGHTING_SPECSは霧の各スライダーの範囲を持ち、defaultSceneVolumetricLighting()はシーンが最初に持つ霧の設定を返し、healSceneVolumetricLighting()は任意の値を範囲内に補正します。霧はライトごとにSceneLight.volumetricでオンにします。sceneLightCanHaze(type)はその種類が霧を照らせるかを、sceneLightHazes(light)はそのライトがいま霧を照らしているかを返します

エフェクト

SceneEffectsは意図的にフラットです。「スイッチと数値」を持つエフェクトはすべてトップレベルに置かれているので、ツールから一律に走査できます。あるエフェクトがパネルのどこに現れるかは表示上の選択であって、構造ではありません

レイヤーリストにどのエフェクトが行を持つかは、environment.effectLayers——このレジストリの「スイッチと数値」を持つキー、つまりToggleEffectKeyのリスト——が別に持っています。enabledとは別物で、enabledはオンかどうか、effectLayersは行があるかどうかです。エフェクトをオンにパッチすると行も自動で追加されるので、enabledだけ書けば足ります

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

グラデーションとリムライトは24種類のブレンドモードEffectBlendModeを共有します。EFFECT_BLEND_MODESはそれをパネルと同じ順序で並べたものです

rainとsnowは形こそ他のエフェクトと同じですが、振る舞いは異なります。ポストチェーンの一段ではなく、シーンの中のジオメトリです。雨と雪を参照してください

モデルとオブジェクトも、それぞれ独自のエフェクトを持ちます——SceneModelItemとSceneObjectItemのeffectsとeffectLayersで、シーンのエフェクトより先に適用され、instance.setEffectsで編集します。含まれるのはLayerEffectKeyの部分集合、つまりcolor、levels、colorWheels、colorShift、selectColors、gradient、blur、bloom、diffusion、rim、outline、dropShadowだけです。ブルームの色選択のフィールドが効くのはこちらだけです。レイヤーエフェクトを参照してください

切り替え効果

transitionは、シーンに入るときに再生される効果です——シーン切り替えを参照してください。scene-transitionsケイパビリティを持たないビルドには含まれません。SCENE_TRANSITION_TYPESが種類を列挙し、defaultSceneTransition()はどのシーンも最初に持つカットを返し、healSceneTransition()は任意の値を範囲内に補正します

environment.itemTransitionは、シーンのモデル、オブジェクト、生成された物体がどのように現れ、消えるかです——表示・非表示を参照してください。古いビルドには含まれません。ITEM_TRANSITION_STYLESがスタイルを列挙し、defaultItemTransition()はどのシーンも最初に持つ300ミリ秒のglitchを返し、ITEM_TRANSITION_MAX_MSは上限の5000ミリ秒です

ランタイム状態

instance.listはステージ上の各アイテムに実際に何ができるかを報告するので、クライアントはエラーで気付くのではなく、コントロールをあらかじめ無効化できます

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

speechは読み込み済みのLive2Dモデルだけが報告するので、ランタイム側のケイパビリティ一覧にしか現れず、formatからは判断できません。アプリ自身のケイパビリティは別の一覧で、helloとapp.infoが報告します——機能の有効・無効はこれで判定し、versionの比較に頼らないでください

type AppCapability =
  | "storage"
  | "speech"
  | "automations"
  | "controllers"
  | "model-editing"
  | "asset-inspection"
  | "layer-effects"
  | "scene-transitions"
  | "area-lights"
  | "spot-lights"
  | "camera-follow-lights"
  | "shadow-filters"
  | "environment-map-model"
  | "spawn"
  | "tracking-lost"
  | "motion-stop"
  | "stage-capture";

stage.capture（stage-captureケイパビリティ）は{ dataUrl, width, height }を返します——ステージウィンドウのアルファ付きPNGで、最長辺はmaxEdge以下、64 – 2048の範囲で既定値は1024です。画面を見られないクライアントが結果を確かめる手段で、残りの契約はプラグインAPIにあります

filesでは各モーションがモデルファイルでの元の番号を保ちます。ファイルが欠けているモーションは空文字列として残るので、後ろのモーションの番号はずれません。motionSlots(files)は再生できるエントリをその番号とともに返します。空のスロットをmotion.playで再生しようとするとnot-foundになり、ファイルが1つもないグループは一覧に含まれません。Live2Dモデルでは、model3.jsonが宣言していない.motion3.jsonもモデルフォルダーからすべて列挙され、それぞれがファイル名を名前とするグループになります

motion.stop（アプリのケイパビリティmotion-stop）は再生中のモーションをフェードアウトさせ、アイドルに戻します。アイドルしか再生していないときは{ stopped: false }を返します。motion.playingのoneShot（motion.startedにもあります）は、そのモーションがstopで終わる種類かどうかを示します

ホットキー

HotkeyConfigはregisteredを除いた同じ形——つまりhotkey.setが受け付けるものです

オートメーション

アプリ自身のオートメーションは別ものです。モデルではなくアプリに属し、1つのオートメーションがアクションの並びを持ち、ショートカット、イベント、呼び出しのいずれかで始まります。automation.listが一覧を返し、automation.runが1つを実行し、automation.stateは一覧が変わるたびに全体を送り直します。automationsケイパビリティが必要で、使い方はプラグインAPIにあります

type AutomationActionKind =
  | "effect-toggle"
  | "effect-params"
  | "effect-clip"
  | "camera-pose"
  | "reset-camera"
  | "play-camera-motion"
  | "stop-camera-motion"
  | "layer-visibility"
  | "stream-mode"
  | "switch-scene"
  | "toggle-expression"
  | "play-motion"
  | "play-audio"
  | "audio-control"
  | "remove-all-expressions"
  | "load-model"
  | "model-position";

actionKindsとtriggerKindsの型がユニオンではなくstring[]なのは意図的です。サーバーはSDKより新しい種類を送ってくることがあります。automationActionLabelは1つのアクションの種類に英語のラベルを与え、未知のものは汎用の名前にまとめます。automationLabelはオートメーション全体のラベルを返します——titleがあればそれを、なければ各アクションのラベルを一覧の順に·でつないだものです。この順序は再生の順番ではありません。AUTOMATION_BOUNDARY_KINDSとisAutomationBoundaryが指すのは、タイムラインの開始前に終わる準備の種類、switch-sceneとload-modelです

設定

SettingsPatchは書き込み可能な部分集合で、lipSync、controller（enabledスイッチのみ）、window、ui、performanceがいずれも省略可能です。トラッキングとポーズはtracking.*とpose.*から変更します。どちらの型も、SDKが一緒にエクスポートしている実行時のZodスキーマSettingsSchemaとSettingsPatchSchemaから推論されています。パッチをパースすると未知のキーと読み取り専用のキーは取り除かれ、レスポンスのパースでは未知のフィールドもそのまま通ります。PersonaClientが設定を自動で検証することはありません

type TrackingSourceId = "persona-ios" | "ifacialmocap" | "vts-ios";
type PoseSourceId = "vmc" | "mocopi";
type TrackingSourceKind = TrackingSourceId | PoseSourceId | "mediapipe";
type TrackingStatus = "off" | "waiting" | "tracking" | "no-face";
type PoseStatus = "off" | "waiting" | "tracking";
type EffectsQuality = "low" | "medium" | "high";

トラッキングソース

tracking.sourcesは設定済みのソースの一覧で、ネットワークの顔と身体のソース、そしてウェブカメラを含みます。複数を同時に走らせられ、モデルインスタンスはSceneModelItemのfaceSourceId、poseSourceId、handSourceIdを通じてidでソースに紐づきます

tracking.source、pose.source、pose.portは複数ソース以前のフィールドで、いまは各チャンネルの最初のネットワークソースを映しているだけです。古いクライアントのために残されています。新しいコードはsourcesを読んでください

mediapipeのウェブカメラソースは独自のオプションを持ち、その既定値はDEFAULT_MEDIAPIPE_CONFIGにあります

type HandTrackingMode = "arms" | "fingers";

ソースの種類は、もはや1つのチャンネルに対応しません——ウェブカメラは3つすべてを担えます。sourceSupportsChannel(source, channel)は、ソースが現在のタスクのスイッチでface、hands、poseを供給できるかを判定し、sourceChannelEnabled(source, channel, masters)はさらにソース自身のスイッチと、ネットワークソースならフェイスとポーズのマスタースイッチも考慮します

リップシンク

settings.lipSyncとlipSync.configureは、デスクトップのマイクを表す同じLipSyncConfigを共有します。マイクによるリップシンクに対応していないビルドでは、Settingsにこの項目がありません

lipSync.stateとlipSync.calibrateはLipSyncStateを返します。キャリブレーションの手順はマイクによるリップシンクにあります

SceneModelItemのlipSyncModeで、マイクがそのモデルを動かすかどうかをモデルごとに決めます：

type LipSyncMode = "off" | "always" | "when-untracked";