Persona

@laplace.live/persona-sdkはPersonaプラグインAPIの公式TypeScript/JavaScriptクライアントライブラリであり、通信プロトコルスキーマの正式な型定義元です。本ページは型定義およびAPIの完全なリファレンスを提供します。サーバーの有効化、APIキー管理、および利用可能なRPCメソッドの一覧についてはプラグインAPIを参照してください。

本SDKはNode.js 22+、Bun、モダンWebブラウザ、OBSブラウザソースなど多様な実行環境で動作します。実行時の外部依存は通信スキーマの定義と検証を担うzodのみです。

npm install @laplace.live/persona-sdk

何が構築できるかアンカーリンクをコピー

Persona Consoleは本SDKを用いて構築された公式リファレンス実装です。シーン、レイヤー、素材インベントリ、表情、モーション、パラメータマッピング、ショートカット、トラッキングソース、全体設定のすべてを単一のブラウザタブで集中管理でき、配信中にスマートフォンなどのタッチ端末から快適に操作できるよう最適化されています。

Webコンソールはデスクトップ側の独自コードに一切依存せず、すべての操作をプラグインAPI経由で実行しています。そのため、本SDKを用いることで同等の操作を行うツールや連携システムを自由に構築できます。

クライアント実装時には以下の設計パターンの採用を推奨します。

• モデル形式やバージョン番号ではなく、機能ケイパビリティに基づいて判定する：各インスタンスの操作UIは、InstanceRuntime.capabilitiesを確認した上で動的に有効・無効を切り替えます。これにより、非対応フォーマットに対する呼び出しエラー（unsupported-for-format）の発生を防ぎます。
• 再接続時はキャッシュを破棄して状態を同期し直す：WebSocket切断中に発生したイベントは再送されないため、ローカルキャッシュがサーバー側の最新状態と乖離する可能性があります。再接続確立時はキャッシュを破棄し、必要な状態データを再取得してください。
• 恒久的な切断コード（Terminal Close Code）を適切にハンドリングする：4001（キー失効）および4002（強制切断）を受信した場合は再接続を中止します。それ以外の切断時は自動再試行を行います。
• イベント購読のライフサイクルをSDKに委ねる：persona.on(…)によるイベントリスナーは再接続時に自動で再登録されるため、呼び出し側で個別に再購読処理を記述する必要はありません。

LLMプロンプトアンカーリンクをコピー

以下のプロンプトをLLMに提供するか、プロジェクトのCLAUDE.mdやAGENTS.mdなどのルールファイルに追加することで、プラグイン開発に必要な完全なコンテキストを提供できます。

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はデスクトップアプリの設定画面（接続中のクライアント）に表示されるクライアント識別子を宣言します。この項目は任意設定の表示用メタデータであり、認証認可の判定には使用されません。SDKは再接続時にこの情報を自動で再通知します。

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

認証方式アンカーリンクをコピー

ブラウザ環境では、APIトークンはURLクエリパラメータ?token=経由で渡されます（ブラウザ標準WebSocket APIの仕様制約による）。Node.jsやBunなどのサーバー環境では、カスタムのcreateWebSocketフックを利用してAuthorization: Bearerヘッダー経由でトークンを渡すことが可能です（wsパッケージ併用）。

import WebSocket from "ws";

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

WebSocketLikeはcreateWebSocketが返却すべきSocketの抽象インターフェースです。ブラウザ標準のWebSocketおよびwsクライアントは型アサーションなしで本インターフェースを満たします。

Node.js 22以降では、グローバルのWebSocketがWebSocketInit拡張を通じてハンドシェイクヘッダーを送信できます。SDKのヘルパー関数createNodeClientは、これを使ってクライアントを作成します。

• auth: 'header'を設定します。
• Node.jsのグローバルWebSocketを使用します。
• 接続タイムアウトを5秒に設定します。
• SDKの警告と恒久的な切断（APIキーの失効やサーバー側からの切断）を、渡されたlog関数に出力します。

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

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

パラメータリース駆動アンカーリンクをコピー

driveParameterはモデルの特定パラメータに値を継続的に書き込むためのインターフェースで、操作用のInjectionHandleを返します。SDKがバックグラウンドでリースのキープアライブを自動維持し、最後の書き込みから約1秒後にリースが自動期限切れとなってパラメータが初期値へ安全に復帰します。これにより、クライアントプロセスの予期せぬ終了時にもモデルが停止したままになるのを防ぎます。

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

同一パラメータを同時にリースできるセッションは1つのみです。他のセッションが重複してリースを要求した場合はconflictエラーが返されます。

第3引数には重み係数（weight）およびバックグラウンドのキープアライブ失敗時に呼ばれるonErrorコールバックを指定できます。

切断ハンドリングアンカーリンクをコピー

onCloseはサーバーまたはネットワークに起因する切断を検知します。コールバックにはSocketのクローズコード、理由文字列、および再接続の試行が終了したかを示すterminalフラグが渡されます。

• 内部のクリーンアップ処理が完了した後に呼び出されるため、ハンドラー内でclose()を安全に呼び出せます。
• クライアント自身が明示的に呼んだclose()では呼び出されません。
• onCloseを指定すると、恒久的な切断はonWarningからは報告されなくなります。

PersonaClientStateとクライアントエラーアンカーリンクをコピー

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

クライアント自身またはトランスポート層でconnect()やcall()が失敗した場合、Promiseはreason: ClientErrorReason（CLIENT_ERROR_REASONSのいずれか）を持つPersonaClientErrorで拒否されます。サーバーがエラーフレームを返した場合は、call()がPersonaApiError（code: ApiErrorCode）で拒否されます。詳細はプラグインAPI：エラーコードを参照してください。

定数定義アンカーリンクをコピー

SDKは以下の値リストとヘルパーもエクスポートしています。

• 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配列です。UIのセレクト項目などで有効な値をすべて列挙できます。
• isApiErrorCode、isEventName、isAppCapability、isTimeInputName、isRandomPulseInputName：対応するTypeScriptの型ガードです。
• injectTargetKey：正規化された注入ターゲット文字列を構築します。
• personaWsUrl：{ host, port, secure }（PersonaAddress、hostには純粋なホスト名またはIPアドレスのみを指定）またはユーザーが入力したアドレス文字列（ホスト名のみ、host:port、IPv4/IPv6アドレス、完全なws:///wss:// URL）からWebSocket URLを組み立てます。APIトークンは接続時にPersonaClientが自動で付加します。
• parseHost、parsePort、isValidPort：純粋なホスト名・IPアドレス（角括弧あり・なしのIPv6に対応し、スキーム・ポート・パス・ゾーンIDを含む場合はnullを返す）およびポート番号を検証します。
• requestTimeoutMs(method, fallbackMs)：メソッド名に応じたリクエストタイムアウトを返します（scene.activateとasset.importではそれぞれの長時間タイムアウトを適用）。

モデルと素材アンカーリンクをコピー

モデルおよび一般素材は共通のメタデータ定義構造を持ちます。kindはアセット種別を示し、originはアセットの出所（bundledはアプリ同梱の素材およびPersonaカタログからオンデマンドでダウンロードした素材、userはユーザー登録素材）を示します。

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はディスク上のファイルに対応しない仮想アセット種別で、インベントリ内で組み込みエフェクトを列挙するために利用されます。addonはアプリケーション自体を拡張するオプションのアドオン（ウェブカメラトラッキングのアドオンなど）を表し、シーンのレイヤーには追加されません。

model.listはModelRef配列、asset.listはAssetRef配列を返します。どちらも、kindをそれぞれModelFormatとAssetKindに絞り込んだContentRefです。

どちらも真偽値のexistsを持ちます。AssetRefでは対象ファイルがディスク上に存在するかを示し（移動または削除された場合はfalse）、ModelRefではモデルのエントリーファイルが見つからない場合にfalseになります。

CatalogItemアンカーリンクをコピー

CatalogItemはピッカーUIなどで利用されるプロトコル非依存のコンテンツメタデータ構造です。ローカルレジストリとリモートカタログの両方がこの型に正規化され、多言語の紹介文description（LocalizedText）とカタログ属性を持ちます。download（CatalogDownload）は未インストール素材の取得情報を表し、省略されている場合はローカルに存在することを示します。

カタログおよび多言語テキストのヘルパー：

• CATALOG_FORMAT、MARKETPLACE_ITEMS_PATH、CATALOG_KINDS：カタログマニフェスト形式バージョン、公開カタログAPIパス（/api/items）、および対応するアイテム種別の一覧です。
• isCatalogId、healCatalog、healCatalogItem、healCatalogRows、healSha256：リモートまたはローカルのカタログマニフェストを検証・正規化します。
• payloadEntryPath、payloadEntryKey、catalogMediaFile（引数はCatalogMediaRole）：展開されたカタログアセットのエントリパスと、ソース内のレンダリング済みサムネイルおよびプレビュー動画のファイル名（.thumbnail.avifと.preview.webm）を解決します。
• pickLocalized(text, locale)、healLocalizedText：LocalizedTextから表示言語に合った文字列を取得し、多言語テキストマップを正規化します。

配置とトランスフォームアンカーリンクをコピー

2Dスクリーン空間はピクセル単位で、ステージ中央を原点とします（+y方向が下）。3Dワールド空間はメートル単位を使用します。プロトコル上の回転値はすべてラジアン単位で表現されます（UI上では度数法で表示）。

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モデルはルートおよび各ArtMesh（描画順order付き）を提供します。

AttachDepthアンカーリンクをコピー

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

depthは親Live2Dモデル内部でのLive2Dアイテムの重なり順を制御します（背後、前面、または特定ArtMeshの直上）。instance.attachで指定します。

アタッチ用のヘルパー関数は以下のとおりです。

• depthStops(meshes)：奥から手前への深度段階一覧（モデルの背後、描画順に各ArtMeshの直上、モデルの前面）を返します。
• depthStopIndex(meshes, depth)：指定した深度がどの段階に該当するかを算出します。関連するArtMeshが存在しない場合は最前面として扱います。
• pinRiders(items, instanceId)：instanceIdに直接または間接的にアタッチされているすべてのインスタンスを返します。循環アタッチの防止に使います。
• pinnableParents(models, items, instanceId)：アタッチ可能な親候補一覧を生成し、循環参照となる対象にridesThisを付与します。
• defaultAttach(parentInstanceId, screenSpace?)：初期状態のアタッチ設定（ルートにアンカー、前面に配置、分割なし、物理パラメータなし）を生成します。screenSpaceを指定した場合（Live2Dモデルまたは2Dオブジェクト）は、既定の反応でホストの頭の動きにも追従します。

シーンアンカーリンクをコピー

背景アンカーリンクをコピー

type BackgroundMode = "color" | "image";

カメラアンカーリンクをコピー

cameraDistanceLimits(environment, radius)はマウス操作によるオービットカメラの許容距離範囲を算出します（デフォルト最小値DISTANCE_MINは0.35m、最大値DISTANCE_MAXは20m）。3D環境のバウンディング半径が標準空間（約10m）と大きく異なる場合、制限値が動的にスケーリングされます。radiusはscene.inspectのenvironment.radiusから取得されます。

ライティングアンカーリンクをコピー

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配列です。

ライトをカメラに追従させるには、SceneLightの次の3つのフィールドを使います。

• followCamera：ライトの位置と角度をカメラ視線に連動させます。
• followCameraOptions：カメラの動きに連動させる自由度を選択します。DEFAULT_LIGHT_FOLLOW_CAMERA_OPTIONSではすべて有効です。
• followCameraReference：連動しない軸の基準姿勢を保持します。

ライトの照射角を保ったまま連動モードを切り替えるには、これらのフィールドを直接変更せず、scene.setLightFollowCameraヘルパーメソッドを利用してください。詳細はライティングを参照してください。

iblAssetIdとmodelAssetIdは、それぞれ環境マップ（IBL）と3Dステージ環境モデルを指定します。environment-map-modelケイパビリティを持つビルドでは両方を同時に設定できます。

• 環境設定の更新にはenvironmentWithAsset()ヘルパーの利用を推奨します。新しいアセットを設定し、もう一方の既存アセットを保持したうえで、旧モデルに紐づくライトのオーバーライドをリセットします。
• 環境マップを選択するとbakeFromModelが自動的にオフになります。ベイクがデフォルトで有効になるのは、空の環境に3Dモデルを読み込んだ場合のみです。
• environmentClearPatch(environment, slot)は'model'または'map'をクリアするパッチを生成します。slotがnullの場合は両方をクリアします。
• applyEnvironmentLighting()とapplyEnvironmentLook()はUI上のボタンに対応するヘルパーで、それぞれ環境ライティングとEnvironmentLookのスタイルを適用します。

ボリューメトリック効果はライトごとにSceneLight.volumetricで個別に設定します。関連するヘルパーは以下のとおりです。

• SCENE_VOLUMETRIC_LIGHTING_SPECS：ボリューメトリックフォグの各スライダーの数値範囲を定義します。
• defaultSceneVolumetricLighting()：デフォルトのフォグ設定を返します。
• healSceneVolumetricLighting()：範囲外の値を有効範囲に収めます。
• sceneLightCanHaze(type)：ライトの種類が散乱効果に対応しているかを判定します。
• sceneLightHazes(light)：ライトが現在ボリューメトリック効果を発生させているかを判定します。

エフェクトアンカーリンクをコピー

SceneEffectsはフラットなデータ構造を採用しており、オン・オフとパラメータを持つ各ポストプロセス効果がトップレベルプロパティとして配置されています。これにより、汎用的な反復処理やリフレクションが容易になります。

レイヤー一覧におけるエフェクトの表示順序はenvironment.effectLayers（ToggleEffectKey配列）で個別に管理されます。これはエフェクト自体のenabledフラグからは独立しており、Patchでエフェクトを有効化すると自動的にレイヤー項目が追加されます。

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

グラデーションはEffectBlendModeで定義される24種類のブレンドモードに対応し、EFFECT_BLEND_MODESに列挙されます。

rain（雨）およびsnow（雪）はデータ構造上他のエフェクトと共通ですが、動作特性が異なります。画面全体のポストプロセスではなく、シーン内に配置される3Dパーティクルジオメトリとしてレンダリングされます。詳細は雨エフェクトおよび雪エフェクトを参照してください。

モデルおよびオブジェクトレイヤーも独自のエフェクトパイプラインを備えています。SceneModelItemおよびSceneObjectItemのeffectsとeffectLayersはシーン全体のエフェクトに先立って評価され、instance.setEffectsから設定できます。

• レイヤーエフェクトはLayerEffectKeyで定義されるサブセット（color、levels、colorWheels、colorShift、selectColors、gradient、blur、bloom、diffusion、sketch、rim、outline、dropShadow）に対応します。
• ブルームのカラー選択はレイヤー単位でのみ機能します。詳細はレイヤーエフェクトを参照してください。

トランジションアンカーリンクをコピー

transitionはシーン切り替え時の視覚効果を設定します（要scene-transitionsケイパビリティ）。詳細はシーントランジションを参照してください。SCENE_TRANSITION_TYPESは利用可能なすべてのトランジション種別を列挙します。

environment.itemTransitionはシーン内のモデルやオブジェクトの出現・消失アニメーションを制御します。詳細は表示と非表示を参照してください。ITEM_TRANSITION_STYLESはサポートされるスタイル一覧を定義します。

シーンプリセットアンカーリンクをコピー

presetsはシーンに保存されたシーンプリセットを表示順に列挙します（scene-presetsケイパビリティ非対応のバージョンでは提供されません）。アクティブなシーンのプリセットはpreset.create、preset.update、preset.rename、preset.setTransition、preset.delete、preset.applyで管理します。詳細はプラグインAPI：シーンプリセットを参照してください。

• SCENE_PRESET_TRANSITIONS：すべての切り替え効果を列挙します。
• scenePresetIsCurrent()：ステージの現在の配置がプリセットと一致するかを判定します。デスクトップアプリとWebコンソールはこれをもとに該当プリセットをハイライト表示します。
• capturePresetItems()：レイヤー配置を取得します。
• presetStep()：プリセット適用時の各レイヤーの変化を算出します。

ランタイム状態アンカーリンクをコピー

instance.listはステージ上に存在する各インスタンスが実際にサポートする機能ケイパビリティ一覧を動的に返します。クライアントはこれにより、非対応のUIコントロールを事前に無効化できます。

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