Persona

Personaは外部アプリケーションから制御できるローカルWebSocketサーバーを提供します。シーンの切り替え、レイヤーの追加と配置、表情の切り替え、モーションの再生、リップシンク付き音声の再生、トラッキング状態の取得、モデルパラメータへの直接書き込みが可能です。

APIサーバーは既定で無効化されています。設定 → プラグインAPIでサーバーを起動し、APIキーを作成して、生成されたトークンをプラグインや外部連携ツールに設定してください。

サーバー設定アンカーリンクをコピー

ローカルネットワークアクセスを有効にすると、PersonaがバインドしているLAN内のIPアドレスとポートが表示され、リモート端末やWebコンソールからの接続設定が容易になります。

設定したポートがすでに他のプロセスで使用されている場合、設定パネルにエラー状態が直接表示されます。

APIキーアンカーリンクをコピー

すべての外部接続において認証が必須であり、未認証の接続は即座に拒否されます。キーを作成をクリックして識別名を入力すると、生成されたトークンの全文が一度だけ表示されます。キー一覧のコピーボタンからいつでも全文をクリップボードに取得できます。

各キー行には接続中、未使用、または直近の使用時刻（相対表示）が表示されます。クライアントがハンドシェイク時にクライアント情報を申告すると、その名前とバージョンが記録され、オフライン時でも接続元を容易に識別できます。

トークンはOSのセキュアな認証情報ストレージ（macOS KeychainやWindows Credential Managerなど）に保管されます。セキュアストレージが利用できない環境では、平文ファイルへの保存を避け、エラー詳細を通知してキー作成を中止します。

プラグインフォルダとリソース登録アンカーリンクをコピー

プラグインはAPI経由でPersonaにモデルや素材アセットの登録・読み込みを要求できます。model.registerおよびasset.registerは、設定画面で（ネイティブダイアログから）明示的に指定されたプラグインフォルダ内の絶対パスのみを受け付け、シンボリックリンクは両側で解決されます。それ以外のパスへのアクセスはforbidden-pathエラーで拒否されます。

asset-import機能に対応している場合、同じコンピュータ（ループバック接続）からのクライアントは、registry.pluginFolders（{ folders }を返す）で設定済みのプラグインフォルダ一覧を取得したり、asset.import { path, want? }でローカルファイルを素材インベントリにインポートしたりできます。

• プラグインフォルダ内のファイルや、すでにインベントリに登録済みのファイルは確認なしで直ちに登録されます。それ以外のパスでは、デスクトップのコントロールパネルに確認プロンプト（ファイルを追加、クライアント名とAPIキー名を表示し、配信モード中はフォルダ名を非表示）が表示されます。ユーザーが拒否するか45秒（ASSET_IMPORT_PROMPT_MS）以内に応答しなかった場合はforbidden-pathを返し、確認待ちのプロンプトが開いている間に別のインポートを呼び出すとinvalid-stateを返します。ループバック以外のリモートクライアントからの呼び出しは、どちらのメソッドもforbidden-pathとなります。
• asset.registerとasset.importはいずれもステージ側の一覧更新が完了してから応答を返すため、直後のobject.addでそのままアセットを読み込めます。

登録されたアセットIDはコンテンツアドレス方式（sha256(path)プレフィックス）のため、再起動後も変わらず、実際のファイルパスがネットワーク上に露出することもありません。ModelRefおよびAssetRefのorigin: 'bundled'には、アプリ同梱のコンテンツと、デスクトップでPersonaのカタログからオンデマンドでダウンロードしたコンテンツの両方が含まれます（未ダウンロードのカタログ項目は一覧に含まれず、APIにはダウンロード用メソッドはありません）。

asset.registerのwantフィールドはアセットの種類を指定します（一致しない場合はinvalid-paramsを返します）。

• image、video、prop、ibl、lut
• animationとcameraMotion：共通の.vmd拡張子を持ち、ファイルヘッダーによって自動判別
• audio（WAV、MP3、OGG、FLAC、M4A、AACファイル）とlyrics（.lrcファイル）：アセット一覧用のアセット種別であり、ObjectContentではないため、登録してもステージ上に独立したレイヤーは作成されない

モデル参照にはエントリファイル名entryFile（ベースネーム）が含まれます。.vtube.jsonのファイル名vtubeFileはmodel.listからのみ返されます（未設定時はnull、ディレクトリパスは含まない）。SDKのmodelMatchesFileはこれらに基づいてモデル読み込みショートカットを照合するため、ショートカットの照合はシーン内アイテムの参照ではなくmodel.listの結果に対して行ってください。

接続中のクライアントアンカーリンクをコピー

サーバーの動作中は、現在確立されているすべてのクライアントセッションが一覧表示されます。申告されたクライアント名、バージョン、開発元識別子、使用中のAPIキー、接続元IPが表示され、Webブラウザからの接続ではページのOriginも表示されます。

識別情報を送信しないクライアントは不明なクライアントとして分類されますが、APIの実行権限に違いはありません。行右側の切断ボタンをクリックすると該当セッションを強制切断し、クライアントに自動再接続の停止を通知します。

新しい接続を受け入れるたびに、クライアント名、キー、接続元IPを記載した無音の通知がシステム経由で配信されます。OS側の設定で通知が抑制されている場合（未署名の開発ビルドや通知権限が無効な環境）、コントロールパネルが開いていればその中に警告トーストとして表示されます。配信映像の誤キャプチャを防ぐため、ステージ画面上には一切表示されません。

Webコンソールアンカーリンクをコピー

各設定については、Webコンソールをご覧ください。

Stream Deckアンカーリンクをコピー

公式のStream Deckプラグインも本APIを利用した純正連携機能です。モデルやシーンの切り替え、ショートカットの実行、表情やモーションの再生、アバターの座標・スケール調整を物理キーに割り当てて操作できます。

MCPサーバーアンカーリンクをコピー

@laplace.live/persona-mcpは公式のModel Context Protocolサーバーです。Claude、Cursor、CodexなどのAIアシスタント向けに本APIをタスク特化型ツール群および汎用的なcall_apiインターフェースとして公開し、stage.captureによるリアルタイムな画面視覚フィードバックを提供します。

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

@laplace.live/persona-sdkは公式のTypeScript/JavaScriptクライアントライブラリであり、Node.js、Bun、Webブラウザ、OBSブラウザソースで共通して動作します。

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

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

await persona.call("expression.toggle", { name: "Smile" });
persona.on("motion.started", (m) => console.log("playing", m.group));

すべてのAPIメソッドは共通の型定義スキーマによって管理されており、パラメータおよび戻り値の型推論が自動的に行われます。SDKリファレンスではインストール手順、クライアントオプション、認証、パラメータリース、エクスポートされているすべての型定義について解説しています。

イベントアンカーリンクをコピー

クライアントは購読したイベントのみを受信します。ネットワーク切断からの再接続時、SDKは以前の購読状態を自動的に復元します。

メソッド一覧アンカーリンクをコピー

モデルを対象とするAPIメソッドは省略可能なinstanceId引数を受け取り、省略時はアクティブなシーンのメインモデルを自動的に対象とします。

scene.createは新しい空のシーンを追加して直ちにアクティブ化します（デスクトップでシーンを新規作成した場合と同じ動作）。レスポンスのactiveSceneIdが新しいシーンIDです。並行セッションとの衝突を避けるため、一覧を再取得して比較せず、このIDを直接使用してください。

scene.patchはアクティブなシーンの背景、カメラ設定、ライティング、環境、およびシーン転換を更新します。シーン内の各アイテムはinstance.*およびobject.*から個別に変更します。

ライトのenabledをfalseに設定すると、照明とシャドウが無効になり、パラメータ設定自体は保持されます。このフィールドの既定値はtrueです。旧ビルドではこのフィールドが省略され、ライトを個別に無効化できません。

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

vrmCameraはorbit、fov（1～179°）、roll（視線軸を中心とする回転角［ラジアン］）、projection（perspectiveまたはorthographic）、clipAssetIdを一括で更新できます。

• オービット角度は任意のラジアン値、distanceは負の値も受け入れます（マウス操作によるナビゲーションは従来の狭い範囲を維持）。
• 平行投影時のビュー幅はabs(distance)となり、fovは保持されますが計算には使われません。距離が負の場合は両軸が反転します。
• stage.resetCameraを実行すると、ロール角と投影方式も既定値にリセットされます。
• 古いビルドではrollとprojectionが含まれず、0およびperspectiveとして処理されます。UIコントロールを表示する前にフィールドの有無を確認してください。

vrmCamera.followはカメラを指定レイヤーに追従させます（{ instanceId, anchor, binding, damping }）。既定値はnullで、camera-follow機能フラグが必要です。

• 追従中は、対象が原点にあるときの構図を基準としてorbitが計算されます。カメラは対象の移動・歩行・モーション再生・動態追従に連動して移動し、orbitへの書き戻しは行われません。
• 別のレイヤーやアンカーを選択すると滑らかに遷移します。追従対象レイヤーを削除するか2Dへ変更すると、followは自動的にnullへクリアされます。
• カメラモーション軌跡の再生中は追従よりモーションが優先されます。stage.resetCameraは追従対象を基準に初期構図へ戻し、現在のfollow設定は保持します。

vrmCamera.aimはカメラの空間位置を保ったまま向きを自動で回し、対象を画面内の指定位置に収めます（{ instanceId, anchor, screenX, screenY, deadZone, softZone, bias, damping, lookahead }）。既定値はnullで、camera-aim機能フラグが必要です。

• カメラの位置座標や距離は変化せず、視線方向のみが回転します（ワールドY軸周りのヨー、ローカルX軸周りのピッチ、ロール角は維持）。
• ギズモのドラッグ操作中やモデル読み込み中は静止を維持します。
• 解除条件はfollowと同様で、カメラモーション再生中はモーションが優先されます。

vrmCamera.focusは被写界深度が有効なとき、フォーカス面を注視点距離ではなく指定レイヤーやアンカーに固定します。既定値はnullで、camera-focus機能フラグが必要です。dampingの既定値は0.2秒です。

• アンカーがカメラの背面に回り込んだ場合は、通常の注視点距離へフォールバックします。
• カメラモーション再生中も有効です。被写界深度が無効な間は表示上の影響を与えません。

vrmCamera.handheldはプロシージャルノイズによってカメラに手持ち撮影のような微細な揺れを加えます。既定値は{ enabled: false, intensity: 0.5, speed: 1 }で、camera-handheld機能フラグが必要です。intensityは0～1、speedは0～2です。

• 切り替えや強度の変更は約1秒かけて滑らかにフェードします。
• シーン設定ファイルには保存されず、カメラモーション再生時は無効化され、ギズモのドラッグ操作中は自動停止します。

オブジェクトとテキストアンカーリンクをコピー

object.addはplace2dまたはplace3d引数を受け取り、初期原点でのレンダリングを挟むことなく指定座標に直接オブジェクトを配置します。値はobject.setPlacementと同じ規則で範囲内に制限されます。

object.addMany { objects }は最大100個のオブジェクトを1回のシーン編集でまとめて追加し（保存は1回、取り消しも1ステップ）、リクエスト順にinstanceIdsを返します。アセットの解決に失敗した項目が1つでもある場合、トランザクション全体がロールバックされます。

object-text機能に対応している場合、ObjectContentをテキストレイヤー（{ kind: 'text', text, font, size, color, shear, letterSpacing, wordSpacing, lineHeight, align, verticalAlign, boxWidth, boxHeight, overflow, stroke, shadow, plate, sung, extrude, bevel, bevelResolution, roughness, metalness, emission, faceCamera }）にできます。1レイヤーにつき単一のスタイルが適用されます。

• 3D空間ではBlenderスタイルの立体押し出し文字としてレンダリングされます。各空間の固有フィールドは切り替え時にも保持されます。
• 全フィールドがリアルタイムに反映されます。テキストレイヤーへのobject.setContent呼び出しは、入力の小休止ごとに1回の取り消しステップとしてその場で編集されます。
• fonts.listはリモートUI向けに、デスクトップホストにインストールされているフォントファミリと字形一覧を返します。
• この機能に対応していない古いホストはテキストレイヤーを破棄します。

object.setText { instanceId, text, transient? }はテキストレイヤーのテキスト内容のみを更新し、入力の小休止ごとに1ステップの取り消し履歴としてリアルタイムに反映されます。

• transient: trueを指定すると、scenes.jsonへの保存や取り消し履歴の記録を行わずに一時的なテキストのみを表示します。この表示は、text: nullが渡されるか、保存済みテキストが編集されるか、レイヤーがステージから外れる（削除または別シーンのアクティブ化）まで維持されます。scene.inspectはこの値をオブジェクトのliveTextとして報告します。
• 非テキストオブジェクトに対して呼び出すとunsupported-for-formatエラーになります。
• TEXT_LENGTH_MAXを超えるテキストは切り詰められます。

object-video-sound機能に対応している場合、動画レイヤーのloop、muted、volumeをobject.setContentでシーンを再読み込みせずに直接編集でき（小休止ごとに1回の取り消しステップとして記録）、音声は設定済みのデスクトップ音声出力デバイスから再生されます。この機能を持たない古いホストは編集ごとにシーンを置換して独立した取り消し履歴を作成し、音声はシステムのデフォルトデバイスで再生されます。

object-chroma-key機能に対応している場合、画像・動画・ウェブページレイヤーでchromaKey（{ enabled, color, similarity, smoothness, spill }）を受け付け、object.setContentでその場で編集できます（操作の一時停止ごとに1つの取り消し履歴を生成）。非対応の古いホストでは正規化時にこのフィールドが破棄されます。

instance.attach { instanceId, attach }はLive2Dインスタンスをアクセサリーとして別のLive2Dモデルにアタッチします。attachのデータ構造はobject.attachと同一であり、nullを渡すとその場でアタッチを解除します。

• object.anchorsの各要素に含まれるorderは取得時点の各ArtMeshの描画順序を表し、UIの深度選択肢の並び順として使用されます。
• アタッチ関係が循環参照となる場合はinvalid-params、VRMインスタンスに対して呼び出した場合はunsupported-for-formatを返します。
• object-pin-depth対応ホストでは、Live2Dモデルにピン留めされた2D画像、動画、ウェブページもattach.depthによる親モデルの階層への挟み込みに対応します（全体描画のみ、split非対応）。3Dオブジェクトに対しては現在frontのみが有効です。
• object-pin-depthは2Dウェブページを通常の画像と同様にシーン順序でスタックし、ポストプロセスエフェクトの対象とします（従来のlayerプロパティは廃止）。このフラグを持たない古いホストはオブジェクトの深度設定を無視し、ピン留めされたメディアをシーン順序で描画し、layerプロパティによって2Dウェブページをステージの完全な背面または前面に合成します。

ステージアンカーリンクをコピー

stage.resetTransform { instanceId? }は指定レイヤーの空間配置トランスフォームをリセットします。instanceIdを省略した場合はアプリ内で現在選択されているレイヤー、非選択時はメインモデルが対象となります。読み込み済みのモデルは約⅓秒かけて初期位置へ滑らかに復帰します。

stage.captureはステージビューポートの透明度付きPNGスクリーンショットを{ dataUrl, width, height }形式で返します。stage-capture機能フラグが必要です。長辺はmaxEdge（64～2048、既定1024）以下にリサイズされ、拡大処理は行われません。

• MCPサーバーなどを経由する、画面を持たないAIエージェントが変更結果を視覚的に確認する用途で使用されます。
• キャプチャの実行には1フレーム分のレンダリング停止を伴うため、定期ポーリングは避け、必要なタイミングでのみ呼び出してください。
• renderer-unavailableエラーはステージウィンドウが未初期化か、フレームバッファがコピー不能であることを示します。クラッシュ後の再ロード中は最初のフレームが描画されるまでこのエラーが返されるため、再試行してください。

機能フラグ（Capabilities）アンカーリンクをコピー

アプリケーション全体および各インスタンスの機能フラグによって、現在動作しているビルドで利用可能な機能を確認できます。バージョン番号の文字列比較ではなく、必ず機能フラグを参照して動作を分岐させてください。

アプリケーション機能フラグは接続時のhelloハンドシェイク応答およびapp.infoから取得できます。

各機能フラグは拡張対象のモジュール名を先頭に冠しています（light-spot、object-textなど）。サーバーは旧バージョンクライアント向けに改名前の旧名も同時に報告し、SDKクライアントは受領時に自動的に現在の名称へ正規化します。

各モデルインスタンスのフラグはinstance.list内のcapabilitiesで返されます。形式上サポートされていないメソッドの呼び出しはunsupported-for-formatエラーで拒否されます。instance.listとinstance.getには直近の読み込み失敗理由を示すloadError?: string | nullも含まれます（読み込み済みまたは読み込み中はnull、古いホストでは省略）。

コントローラーアンカーリンクをコピー

controllersはcontroller.*（接続済み機器と保存済みプロファイルの確認、名前の変更、デッドゾーン設定、プロファイルの削除、割り当ての開始）と、settings.patchによるcontroller.enabledマスタースイッチの切り替えを提供します。対象はデスクトップホスト本体に接続されたコントローラーです。

instance.setControllerMovementはインスタンスのコントローラー移動設定（enabled、slot［保存済みプロファイル番号］、moveSpeed、turnSpeed、smoothing）を更新します。VRMモデルではさらにwalkEnabled、walkClip、walkSpeed、faceMovementが利用可能で、walkClipの参照形式はinstance.setIdleと同一です。許容範囲外の数値は自動的に境界値に丸められ、オブジェクトに対して呼び出すとunsupported-for-formatが返されます。

パラメータの割り当てアンカーリンクをコピー

model-editingはinstance.setBreathと、パラメータマッピングの取得・プレビュー・書き込み・解放を行うbinding.*を提供します。

• binding.overrideは一時的な入力オーバーライドを行います。
• binding.inputsは{ inputs, outputs }を返します。inputsはリアルタイムのトラッキング生データ、outputsはモーション・表情・物理演算を適用した後の各モデルパラメータの現在値です。モデルが宣言していない出力は含まれません。
• Time24hおよびTime12hは0..1の範囲を持つ組み込みバインディング入力チャンネルです。顔トラッキングとは独立してデスクトップのローカル時計を毎レンダリングフレームサンプリングし、Live2DおよびVRMの両方のバインディングを駆動します（詳細は時刻パラメータの割り当てを参照）。SDKはTIME_INPUT_NAMES、TIME_INPUT_RANGES、isTimeInputNameから定義を公開しています。

binding-calibrationは入力ごとのキャリブレーションマップcalibrationを追加します。

• binding.getの応答にcalibrationが含まれます（未調整時は{}、非対応の古いホストでは省略）。
• binding.previewおよびbinding.setはconnectionsとcalibrationの片方または両方を受け付け、省略された側はライブ状態でもディスク上でもそのまま維持されます。
• キャリブレーションのみの保存では<model>.persona.jsonにbindingsを書き込まないため、.vtube.jsonの割り当てがそのまま有効に保たれます。

binding-random-pulsesは組み込みのランダムパルス入力RandomPulse1～RandomPulse8（範囲0..1、顔トラッキングとは独立）と、モデルごとの発動設定マップrandomPulsesを追加します。

• 入力がすべてランダムパルスの割り当ては、同じパラメータを動かす他の入力の上に重ねて発動し（発動中はoutRange[1]へ向かい、待機出力がパラメータの初期値と異なる場合を除き非発動時は元の値をそのまま通す）、通常の割り当てと同じ出力パラメータを共有できます（詳細はパラメータの割り当てを参照）。
• binding.getの応答にrandomPulsesが含まれます（カスタム設定がない場合は{}、非対応の古いホストでは省略）。各設定は{ intervalSeconds: [min, max], durationSeconds: [min, max], fadeInSeconds, fadeOutSeconds }（単位は秒、間隔と持続時間は0.1～3600、フェードインとフェードアウトは0～3600）で、未設定のパルスはDEFAULT_RANDOM_PULSE_SCHEDULE（間隔0.5～4.5秒、持続時間0.58秒、フェードイン・フェードアウト各0.29秒で、VTube Studioの自動まばたきと同じ）で動作します。
• binding.previewおよびbinding.setはconnections、calibration、randomPulsesの任意の組み合わせを受け付け、省略された項目はライブ状態でもディスク上でもそのまま維持されます。randomPulsesのみの保存でも.vtube.jsonのbindingsは<model>.persona.jsonへコピーされません。

モデル全体の移動アンカーリンクをコピー

model-movement機能に対応している場合、model.getMovementとmodel.setMovementでVTube Studio互換のLive2Dモデル全体の移動設定を取得・更新できます。

• modelIdを省略した場合はアクティブなメインモデルが対象となります。存在しないモデルではnot-found、VRMモデルに対して呼び出した場合はunsupported-for-formatが返されます。
• この設定はインスタンスごとではなくモデル単位で保持されます。モデルの.vtube.jsonが存在する場合はそこに保存され（存在しない場合は.persona.json）、VTube Studioと共有されます。
• 全体の移動はモデルの配置座標を直接調整し、パラメータ値を上書きしないため、モデル固有のFacePosition*バインディングと重ねて反映されます。
• 既定値はVTube Studio準拠（有効、6/8/11）で、設定が変更されるたびにmodel.movement { modelId, movement }イベントが配信されます。

model-movement-pivotはmovementにpivot（前後の拡大中心点）を含めることを可能にします。{ kind: 'root' }はモデル中心で既定値、ArtMeshアンカーなら{ kind: 'artMesh', id, verts, weights }を指定します。

• モデルに.vtube.jsonが存在する場合でも、拡大中心は常に.persona.jsonに保存されます。
• 拡大中心はモデルの静止ポーズでの位置で計算されるため、頭の回転によってモデルが移動することはありません。

表情グループアンカーリンクをコピー

expression-groups機能に対応している場合、expression.getGroupsとexpression.setGroupsでモデルの表情グループを取得・更新できます。ルールはVTube StudioのExpression Groupsと同じで、有効なグループ内でメンバーの1つが表示されると、表示中のほかのメンバーは自動的に非表示になり、グループ内の表情は一度に1つだけ表示されます。

• expressionはメンバーの表情キーで、Live2Dでは.exp3.jsonのファイル名、VRMでは表情名です。大文字・小文字は区別しません。
• 表情がオンになる、またはinverted（反転）メンバーがオフになると「表示」とみなされます。反転メンバーはオフの間に表示扱いとなり、帽子をかぶったモデルの「帽子を脱ぐ」表情などに使えます。メンバーが表示されると、所属する各有効グループ内で表示中のほかのメンバーが非表示になり（通常メンバーはオフ、反転メンバーはオン）、それぞれ自身のfadeSecondsで切り替わります。非表示にしてもほかのメンバーが表示されることはないため、何も表示しないグループもあり得ます。複数のグループで結果が食い違う表情は、後のグループに従います。
• expression-groups-hide-first機能に対応している場合、グループにhideFirst: true（隠してから表示）を設定できます。メンバーが表示に切り替わるとき、そのグループによって非表示になるほかのメンバー（オンに切り替わる反転メンバーを含む）が完全にフェードアウトし終わるまで待ってからフェードインが始まります。省略またはfalseの場合は既定のクロスフェード（VTube Studioと同じ）になります。グループによる非表示化、全表情の解除、復元、整理、およびウェイトを0にする操作では待機しません。この機能を持たない古いホストはhideFirstを破棄します。
• メンバーのfadeSecondsは、切り替えを起こした側（ショートカットのfadeSecondsを含む）のフェード時間より優先されます。無効なグループはフェード時間も含めて無視されます。
• 表情グループは、expression.toggle、ショートカット、オートメーション、全表情の解除（解除後は各グループを整理し、最初に表示されたメンバーを残す）、記憶された表情の復元など、すべての切り替え経路に適用されます。実際の切り替え結果はexpression.changedで通知されます。
• expression.setGroupsでグループの有効状態を切り替えたり、メンバーを追加・削除・反転したりすると、ステージ上でそのモデルが表示中の表情を即座に整理します。名前変更やフェード時間、hideFirstの変更だけでは整理されません（VTSのエディタと同じ）。
• .persona.jsonにまだ表情グループが保存されていない場合、Personaは.vtube.jsonのExpressionGroupsを読み取り専用でインポートします（edited: false）。expression.setGroupsやパネルでグループを編集すると一覧全体が.persona.jsonに保存され、以降は.vtube.jsonより優先されます（.vtube.jsonも存在する場合はedited: true）。.vtube.jsonには書き込みません。表情エディターで.exp3.jsonの名前変更や削除を行った場合は、.persona.jsonへの移行を起こさずに.vtube.json内の該当エントリをその場で更新し、.persona.jsonがあればそちらも更新します。
• 変更のたびに（表情ファイルの名前変更や削除に伴う変更を含む）expression.groups { modelId, groups, edited }イベントが配信されます（古いホストではeditedが省略されます）。

バージョン履歴アンカーリンクをコピー

model-history機能に対応している場合、モデルの保存済みバージョンを取得・管理できます。デスクトップのモデル詳細にあるバージョンセクションに相当します（詳しくはバージョン履歴を参照）。すべてのメソッドはmodelIdを受け付け、省略時はメインモデルが対象です。同梱モデルに対してはinvalid-stateを返します。明示的に要求しない限り、バージョンは保存されません。

• ModelVersionは{ id, parentId, time, kind, message, name, notes, current }です。kindはMODEL_VERSION_KINDS（first、saved、backup）のいずれかで、ほかのGitツールが作成したコミットではnullとなり、messageがそのコミットメッセージの1行目になります。currentはディスク上のファイルの元になったバージョンを示します。
• 切り替えや復元が未保存の変更があるファイルを上書きする場合、unsavedChanges（MODEL_VERSION_UNSAVED_ACTIONS）を指定しないとinvalid-stateを返します。'save'はすべての未保存の変更を先にbackupバージョンとして保存してbackupで返し、'discard'は上書きされる変更を破棄します。
• 履歴がオフの間、保存・切り替え・復元はinvalid-stateを返します。一覧・比較・命名は以前に保存された履歴を引き続き読み取れます。
• モデルのファイルが見つからない間、履歴のオン・保存・切り替え・復元はnot-foundを返します。バージョン履歴が読み取れないフォルダ（UNC共有、またはmacOS・Linuxでバックスラッシュを含む名前のフォルダ）で履歴をオンにするとinvalid-stateを返します。
• Personaが書き込めないファイルや、ほかのGitツールが途中で残した状態（ステージ済みのファイル、マージ中、ブランチなし）がある場合は、何も変更せずにinvalid-stateを返します。
• バージョン名は最大80文字（MODEL_VERSION_NAME_MAX_LENGTH）、メモは最大2000文字（MODEL_VERSION_NOTES_MAX_LENGTH）です。
• 変更のたびにmodel.versions { modelId }イベントが配信されます。ほかのアプリによるファイル編集では配信されません。古いホストにはこれらのメソッドがありません。

モーションと待機状態アンカーリンクをコピー

motion.listはモデルに登録されているモーショングループの一覧を取得します。Live2Dモデルの場合、モデルフォルダ内に存在し.model3.jsonで宣言されていない.motion3.jsonファイルも自動検出され、ファイル名に基づいた独立したグループとして一覧に加わります。デスクトップのモーションタブで新規記録したモーションも、モデルを再読み込みすることなく即座に反映されます。

motion.stopは現在再生中の単発モーションを終了し、モデルを瞬時に戻すのではなくなめらかに待機状態へ復帰させます（motion.endedは復帰を待たずにすぐ配信されます）。motion-stop機能が必要です。待機アニメーションのみが再生されている場合は何も行わず{ stopped: false }を返します。

motion.playingおよびmotion.startedのoneShotフラグは、そのモーションが待機アニメーションの上に重ねて再生されている単発モーション、つまりmotion.stopで停止される種類であるかを示します。旧ビルドではこのフィールドは返されません。

instance.setIdleはインスタンスの待機設定を更新します。

instance.getを呼び出すとこれらの待機設定がまとめて返されます。

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

light-area機能を備えたビルドでは、SceneLightの種別としてareaが利用可能です。座標x/y/zに配置された矩形面光源です。

• 面光源はPBRマテリアルおよびMToonアバターを照らします（MToon側はトゥーンシェーダー内で4つのサンプル点を用いて近似）。Live2Dレイヤーには影響せず、シャドウの投射も行いません。
• rangeやシャドウの設定値は保持されるため、後から別の光源種別に切り替えることが可能です。

light-spot機能を備えたビルドでは、SceneLightの種別としてspot（スポットライト）が利用可能です。座標x/y/zに配置されます。

• 強度は0～20で、ポイントライトと同様です。
• スポットライトはPBRおよびMToonマテリアルを照らし、シャドウ品質やボケ半径の設定、ボリュメトリックフォグの照射に対応します。面光源とスポットライトの新規作成や種別の切り替えは、対応する機能を備えたビルドでのみ利用できます。

shadowFilterは平行光、ポイントライト、スポットライトごとにpcf（既定）またはpcssを個別に選択でき、1つのシーン内に混在させることも可能です。利用可否はlight-shadow-filter機能フラグに基づいて判定してください。非対応のビルドでも、ローカルで作成したライトにはshadowFilterが含まれる場合があります。古いシーンを読み込んだ際はPCFが既定となります。

followCameraはライトをカメラに追従させます。light-camera-follow機能が必要で、環境光では無視されます。既定値はfalseです。有効にすると、ライトの位置と角度がカメラのローカル座標系に基づいて計算され、手動でのカメラ操作やカメラスルー再生に同期して追従します。

followCameraOptionsで追従するトランスフォーム成分を選択できます（各項目とも既定true）。

• fovの変更のみではライトは移動しません。
• 追従を無効化した成分は、followCameraReferenceに記録された固定値（targetX、targetY、targetZ、distance、ワールド空間の回転クォータニオン）で保持されます。参照値がない場合は原点、無回転、距離0として扱われます。

scene.setLightFollowCamera { lightId, followCamera, options? }はアクティブなシーン内の指定したライトのカメラ追従状態を切り替え、またはoptionsをマージします。このときライトのワールド座標や向きは変化しません。followCameraと同様に、利用可否はlight-camera-follow機能フラグに基づいて判定してください。

• デスクトップ側が表示中のカメラトランスフォーム（再生中のカメラモーションを含む）に基づいてライトの座標を逆算し、計算後の{ light }を返します（ライトが削除済みの場合はlight: null）。
• scene.patchやシーンファイルからの読み込みでは逆算を行わず、指定された生の値がそのまま適用されます。

SceneLight.volumetricはポイントライト、スポットライト、面光源ごとに光線フォグ（ボリュメトリック照明）を有効化します（既定false）。その他の種類のライトではこの設定は無視されます。古いビルドではシーン全体のグローバル設定だったため、グローバル設定で保存された旧シーンを読み込むと、フォグ照射に対応したすべてのライトで自動的にvolumetricが有効になります。

SceneEnvironmentには省略可能なvolumetricLightingとclusteredLightingの設定が追加されています。古いビルドではこれらのフィールドが含まれないため、UIコントロールを表示する前にフィールドの有無を確認してください。

volumetricLightingはシーン全体のフォグの質感を決定します。フォグ自体にグローバルな有効・無効スイッチはなく、フォグが有効なアクティブライトが1つ以上存在するときにのみレンダリングされます。現行のホストは完全なフォグ設定を返し、scene.patchで更新できます。

フォグは有効化された光源の周囲に散乱し、深度遮蔽を受け、光が当たらない領域は透明を保ちます。フォグが有効なアクティブライトが1つでもあれば、3Dオブジェクトや環境モデルに内蔵されたポイントライト、スポットライト、面光源もフォグを照らします。

フォグには透視投影カメラが必要であり、平行投影ではパラメータ設定は保持されますがレンダリングは行われません。平行光や環境光はフォグを照射せず、Live2Dレイヤーはフォグを遮蔽しません。

clusteredLighting: trueはWebGPU透視投影環境において、照射範囲が有限でシャドウを投射しない1～64個のポイントライトのライティング計算をクラスター化して高速化します（既定false）。照射範囲が有限でないポイントライトがある場合、ライト数が上限を超える場合、または非対応のレンダラーや投影方式では、通常のライティングにフォールバックします。クラスター化によってシャドウ描画の負荷は下がらず、フォグが参照するライトも変わりません。

environment-map-model機能を備えたビルドでは、SceneEnvironmentにiblAssetIdとmodelAssetIdの両方を同時に設定できます。

• bakeFromModelを有効にすると、3D環境モデルから照射プローブを生成し、環境テクスチャを入力として使用します。falseの場合はテクスチャから直接ライティングを行い、テクスチャがなければモデル内蔵の空にフォールバックします。
• showSkyboxは背景描画のみを制御し、ライティングの供給元に関わらず、背景にはテクスチャまたはモデルの空が描画されます。
• 一方のアセットをクリアしても他方は保持されます（SDKのenvironmentClearPatch()を使用）。古いビルドでは環境アセットを同時に1つしか設定できないため、新しいアセットを設定する際はもう一方をクリアしてください。

また、scene.patchを使用してパノラマ環境の次の省略可能なフィールドを調整できます。これらは対応ビルドにのみ存在するため、UIコントロールを表示する前にフィールドの有無を確認してください。

物理演算アンカーリンクをコピー

SceneEnvironment.physicsはシーンの物理演算のマスター切り替えです。有効にすると3Dオブジェクトが重力に従ってステージ床面に落下し、VRMアバターと衝突判定を行います。既定値はfalseで、古いビルドではこのフィールドが省略されます。物理演算によるシミュレーション結果の座標は保存されず、API経由で取得される座標は常に初期配置時の値です。physicsをオフにすると、すべてのオブジェクトが即座に初期配置座標に復帰します。

stage.spawnは登録済みのprop小道具アセットを、物理駆動の動的オブジェクトとしてステージ上に一括スポーンします。stage-spawn機能が必要で、成功時は{ spawned, alive }を返します（aliveはステージ上に現存する物理オブジェクトの総数）。

スポーンされたオブジェクトはレンダラーのメモリ上のみに存在し、シーンアイテムやレイヤー階層を作成せず、元に戻す操作やファイル保存の対象外です。同一アセットの全インスタンスでジオメトリ、テクスチャ、ドローコールが共有されるため、数百個配置しても軽量に動作します。シーンのphysicsが無効な場合はinvalid-state、未登録のアセットではnot-found、prop以外のアセットではinvalid-paramsエラーを返します。

許容範囲外のパラメータは境界値に自動調整されます。スポーンされたオブジェクトはttlMsの経過、シーン切り替え、またはphysicsの無効化時に自動的に破棄されます。stage.clearSpawned {}を呼び出して即座に全消去することも可能です。この呼び出しは{ cleared }を返し、アセット読み込み中のスポーンも取り消します。

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

scene.activateは対象シーンのリソース読み込みが完了してステージ描画が切り替わるまで待機しますが、トランジション演出が完全に完了するまでは待機しません。読み込み中も切り替え元のシーンは動作を続け、編集も可能です。トランジション中に新たなシーン切り替えが要求された場合は後発の要求が優先され、レスポンスには最終的に有効化されたシーンIDが返されます。SDKの既定タイムアウトは120秒で、requestTimeoutMsを指定した場合はその値が優先されます。

scene-transitions機能を備えたビルドでは、Scene.transitionにシーン固有のトランジション設定（そのシーンに入る際に再生される演出）が含まれます。scene.patch { transition }で設定を一括更新できますが、その時点では再生されません。

どのような手段でシーンを切り替えても、対象シーンに設定されたトランジション演出が実行されます。直接切り替え（cut）を除き、演出は直ちに開始され、新シーンの準備が完了するまで画面を覆い続けます。読み込みに時間がかかる場合はdurationMsを超えて自動延長されます。動画トランジションは無音で、再生速度を演出時間に合わせて再生され、待機中はswitchPointのフレームで静止します。

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

scene-presets機能を備えたビルドでは、Scene.presetsにシーンの保存済みシーンプリセットが表示順に含まれます。各要素は{ id, name, transition, items }です。旧バージョンのホストにはpresetsフィールドが含まれません。

• itemsはインスタンスIDをキーとし、値は{ visible, place }です。
• Live2Dモデルと2Dオブジェクトのplaceは{ space: '2d', x, y, scale, rotation }、それ以外は{ space: '3d', x, y, z, rotX, rotY, rotZ, scale }です。不透明度はプリセットに含まれません。
• プリセット保存後に追加されたレイヤーには対応するエントリがなく、適用時もそのまま維持されます。

preset.*メソッドはいずれもアクティブなシーンに作用します。

create、update、rename、setTransitionは{ preset }を、deleteとapplyは{}を返します。

transitionはステージがプリセットへ移る方式を指定し、レイヤーの表示状態の変化も同じ方式に従います。

• トランジション中に保存すると、レイヤーが最終的に停止する位置が記録されます。ステージが向かっている最中のプリセットに再度applyを呼び出しても変化はありません。
• アクティブなシーンに存在しないプリセットIDはnot-foundを返します。プリセットIDは単一シーン内でのみ一意で、シーンを複製しても元のIDが保持されます。
• デスクトップでの編集と適用はシーンの取り消しステップとして記録され、変更のたびにscene.changedで通知されます。
• キーボード、コントローラー、Stream Deckからは、プリセットを適用するアクションを含むオートメーション（またはStream Deckのプリセットを適用キー）でプリセットを呼び出します。

背景の不透明度アンカーリンクをコピー

background-alpha機能に対応したビルドでは、SceneBackground.colorにアルファバイト（#rrggbbaa）を含められます。透明なステージは独立したモードではなく、アルファ00のcolor背景として表現されます（ステージの背景を参照）。ホストは旧来のtransparentモード（LEGACY_TRANSPARENT_BACKGROUND）も引き続き受け付け、同じ色のアルファ0として保存します。

この機能を持たない旧バージョンのホストはtransparentモードを使い続け、アルファ付きの色は既定の色に補正します。SDKクライアントはそうしたホストに合わせて次のように動作します。

• ホストが返すtransparentをアルファ0の色として読み取ります。
• scene.patchを送る際、アルファ00のcolor背景をtransparentに変換します。
• それ以外の背景色からはアルファバイトを取り除きます。

表示と非表示アンカーリンクをコピー

SceneEnvironment.itemTransition { style, durationMs }はシーン内のアイテムに対する表示と非表示ルールを設定し、モデル、オブジェクト、スポーンアイテムの出現時・退場時アニメーションを定義します。古いビルドではこのフィールドは含まれません。styleには次のいずれかを指定します。

durationMsは0～5000ミリ秒（既定300ミリ秒）です。cutの場合やdurationMsが0の場合、レイヤーは瞬時に表示・非表示になります。設定はscene.patchで更新します。

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

layer-effects機能を備えたビルドでは、個別のモデルやオブジェクトに対して専用の画面エフェクトを付与し、全画面合成の前段階で適用できます。各シーンアイテムはシーン全体と同等のeffectsおよびeffectLayers構造を持ち、instance.setEffects { instanceId, effects, effectLayers? }から編集します。

• effectsはcolor、levels、colorWheels、colorShift、selectColors、gradient、blur、bloom、diffusion、sketch、rim、outline、dropShadowの部分設定を受け入れます（省略したパラメータは現在の値を維持）
• effectLayersを指定すると、追加済みのエフェクト階層スタック全体が置き換えられます（有効なエフェクトは常に一覧に含まれます）

レスポンスには正規化後の完全な設定が返されます。範囲外の数値は丸められ、未定義のキーは破棄されます。不正な形式のエフェクトが含まれる場合、変更は適用されず呼び出し全体が失敗します。

ブルーム（bloom）の発光処理はWarudoのCamera Bloom（Beautify仕様）に準拠します。

リムライト（rim）はVTube Studioのバックライト仕様に準拠し、白色リムは純白にクリップして被写体の固有色へと自然に減衰します。blendModeプロパティは持ちません（古いクライアントからの値は破棄されます）。既定カラーは#ffeb74、既定サイズは0.5です。

アウトライン（outline）は正規化されたsize、color、opacity、quality（low、medium、high）、およびroundnessを受け入れます。roundnessは狭い隙間を埋めて角を丸める正規化されたクロージング半径で、0で元のシルエットに厳密に従います。

スケッチエフェクト（sketch）はJaume Sanchez氏のNPRスケッチシェーダーをベースにしており、シーン全体（environment.effects.sketch）およびレイヤーエフェクトとして利用できます。

• シーン全体ではpaperBackground: trueにより透明ピクセルを用紙色で塗りつぶします。レイヤーエフェクトでは本フラグに関わらず常に元画像のアルファ値を維持します。
• 旧ビルドでは返却されるエフェクト一覧にsketchが含まれません。

魚眼エフェクト（fisheye）はシーン専用で、environment.effects.fisheyeで設定します。画面を魚眼レンズで見たように中心から膨らませて描き直します。strength（0〜1、既定値0.5）が曲がりの強さで、1は画面の対角線で150°の魚眼に相当します。四隅は動かないため画面は常に埋まり、各辺の中央付近がトリミングされます。古いホストが返すエフェクトにはfisheyeが含まれません。

レイヤーエフェクトはモデルおよび2D・3D空間のオブジェクトに適用できます。2D空間の画像、動画、ウェブページ、テキストに適用するには、ホストがlayer-effects-2d機能を宣言している必要があります。エフェクトはピン留めの有無に関わらずレイヤースタック内の当該オブジェクトの位置で合成され、オブジェクトの不透明度に合わせてフェードします。旧バージョンのホストでは2Dオブジェクトに対して呼び出すとunsupported-for-formatが返されますが、保存済みの設定値は保持されます。オブジェクトの空間を切り替えた場合も、保存済みの設定値は保持されます。

トラッキングソースアンカーリンクをコピー

Personaは複数のトラッキングソースを並行して実行できます。ソースの一覧はsettings.tracking.sourcesに格納され、tracking.addSource、tracking.updateSource、tracking.removeSourceで管理します。

instance.setTrackingSourcesによって、インスタンスの顔、姿勢、手チャンネル（faceSourceId、poseSourceId、handSourceId）を特定のソースに紐付けます。チャンネルにnullまたは存在しないIDを指定すると、そのチャンネルのトラッキングが停止します。新規インスタンスはシステム全体の既定ソースに接続されます。1つのソースから複数のアバターを同時に駆動することも可能です。

instance.setTrackingSourcesではhandTrackingModeも設定できます。armsはVRMの腕・手首・指をハンドトラッキングから連動駆動し、fingersは指のみを駆動して腕のポーズをVMCやmocopiなどのボディトラッカーに委ねます。

フェイストラッキングと姿勢トラッキングのソースには次の種類があります。

• フェイストラッキングソースは、任意のphoneIpで送信元端末をフィルタリングできます。
• portを省略して追加したソースには、その種類のデフォルトポートから順に空いている最初のポートが割り当てられます。
• ポートが衝突した場合は拒否されます（ifacialmocapソース同士、またはpersona-iosソース同士では同一ソケットを共有可能）。
• 非推奨のvts-ios-nativeはプロトコル層で拒否されます。

mediapipeは内蔵のWebカメラトラッキングソースであり、ポートやIPの設定を持たないシングルトンです。オプションは次のとおりです。

既定では映像の左右反転が有効、CPUで動作し、顔と手のトラッキングが有効、身体のトラッキングは無効です。tracking.addSourceとtracking.updateSourceはオプションの部分更新を受け付け、指定しなかった項目は現在の値を維持します。認識された手はパラメータ注入で定義されている手の入力値も駆動します。

tracking.statusはネットワーク経由の顔・姿勢ソースの統合状態と、sourcesマップ内の各ソース（Webカメラを含む）の状態を返します。tracking.statusイベントも同じペイロードで、個別ソースの状態が変化するたびに配信されます。

従来の単一ソース向けメソッドも引き続き利用可能で、対応するチャンネルの最初のネットワークソースに作用します。

• tracking.setSourceで種別を変更します。
• pose.setSourceはプロトコルを切り替え（ソースがなければ作成）、割り当てられたポートを返します。
• pose.setPortでポート番号を更新します。
• tracking.setEnabledおよびpose.setEnabledはネットワーク顔・姿勢トラッキングのマスター切り替えです。

Webカメラトラッキングは自身のenabled設定のみに従い、tracking.updateSourceで変更します。無効化している間も、タスクの選択とモデルへのチャンネル割り当ては保持されます。Webカメラの推論にはデスクトップのウェブカメラトラッキングのアドオンが必要であり、APIからはアドオンをインストールできません。デスクトップ側でインストールされるまで、mediapipeソースの状態はwaitingのままになります。

マイク音声リップシンクアンカーリンクをコピー

リップシンクはデスクトップ本体のマイク音声入力を利用してアバターの口形状を駆動します。音声デバイスの列挙と音声の取り込みはデスクトップ本体で完結します。音声の生データとキャリブレーション係数はデスクトップから出ず、APIを通ることも公開設定に含まれることもありません。周波数解析結果はパラメータ注入で定義されている音声入力値も駆動します。

設定内容はsettings.lipSyncにも反映され、settings.patchから直接更新することも可能です。

キャリブレーションはデスクトップで選択中のマイクを使用し、デスクトップのコントロールパネルと状態を同期しながら、次の手順で進めます。

録音は即座に応答を返すため、進捗状況はlipSync.stateをポーリングして確認してください。lipSync.stateのcalibrationは現在の段階phase（ready、recording、verifying）、録音中の音素、録音済みの音素一覧を報告します。段階に合わないステップを呼び出すとinvalid-stateエラーが返されます。

instance.setLipSync { instanceId?, mode }はマイクによる口形状駆動の動作モードをalways（常時有効、既定）、when-untracked（顔認識ロスト時のみ有効）、off（無効）から設定します。オブジェクトに対して呼び出すとunsupported-for-formatエラーを返します。

音声再生アンカーリンクをコピー

speech.playは指定された音声ストリームを再生し、音声エネルギーに同期してモデルの口を動かします。機能フラグにspeechを含むインスタンス（現在読み込まれているLive2Dモデル）に対してのみ有効です。利用可否はファイル形式ではなくインスタンスの動的機能フラグによって判定されます（たとえば0.53以前の旧WebGLエンジンでは、この機能フラグは宣言されません）。

1つのモデルで同時に再生できる音声は1つのみであり、新しい音声の再生要求は現在の再生を直ちに中断して上書きします。成功レスポンスはデコードと再生の開始を示し、開始できない場合はinvalid-stateエラーとなります。再生の開始と終了はspeech.startedおよびspeech.endedイベントによって通知され、speech.stopで手動停止できます。

アバターショートカットアンカーリンクをコピー

モデル固有のショートカットキーは以下の3つのメソッドで操作します。いずれも省略可能なmodelIdを受け取り、省略時はメインモデルを対象とします。

メインモデルか否か、Live2DかVRMかを問わず、ステージ上の各モデルが個別にショートカット設定を保持します。物理キーの組み合わせが入力されると、そのキーが割り当てられたすべてのモデルのショートカットが同時に実行されます。ステージ上に配置されていないモデルに対してhotkey.triggerを実行した場合は無視されます。

HotkeyオブジェクトはVTube Studio互換の4つのオプション設定をサポートします。

古いホストはこれらのフィールドを返しません。hotkey.setで送信しなかったプロパティは既存の値を保持するため、古いクライアントがこれらの設定を消してしまうことはありません。

hotkey.triggerはキー解放の概念を持たない単発イベント呼び出しであるため、holdが設定されたショートカットは状態トグル（有効・無効の反転）として機能します。holdやdeactivateAfterSecondsによって一時的に有効化された表情は、モデルの状態としてファイルに保存されません。

Hotkey.acceleratorは+で連結された最大3つのトークンで構成され、すべて同時に押されたときに反応します。修飾キー（MODIFIER_TOKENS：Control、Alt、Shift、Super）、Electronの名称によるキー、マウスボタンLeftMouseButton・RightMouseButton・MiddleMouseButton、または同じコントローラーのController*ボタンを使えます。順番はマッチングに影響しないため、組み合わせを比較する際は文字列ではなくSDKのcomboKeyを使い、画面表示用に整形する際はhelloが報告するデスクトップ側のapp.platformを渡してacceleratorLabel(accelerator, app.platform)を使ってください。

HotkeyState.registeredには、Personaがバックグラウンドにある状態で現在反応するショートカットが列挙されます。デスクトップはOSに登録するのではなくキーの状態を読み取るため、globalを有効にした組み合わせ（単独キーを含む）はすべて対象です。古いホストは、OSに登録したControl・Alt・Superを含む組み合わせのみを列挙します。

オートメーションアンカーリンクをコピー

automations機能を備えたビルドでは、ショートカットキー、システムイベント、API呼び出しによって一連のアクションシーケンスをトリガーするオートメーションの一覧取得と実行に対応します。automation-editingおよびautomation-transport機能を備えたビルドでは、タイムライン定義全体の読み書きとタイムライン再生の制御も行えます。

automation.listは軽量な要約メタデータとしてid、title、accelerator、registered（Personaがバックグラウンドにある状態で現在反応するか。古いホストではOSに登録済みか）、enabled、およびactionKindsとtriggerKindsの配列を返すため、タイムライン全体を取得しなくてもコントロールUIを構築できます。

titleがnullの場合、SDKのautomationLabelユーティリティ関数などを用いてactionKindsから表示ラベルを自動生成できます。actionSceneIdsはactionKindsとインデックスが対応しており、scene-switchアクションの対象シーンIDを保持します（他の種別の位置はnull）。これにより対象シーンの名前を表示できます。

各オートメーションはタイムラインとして動作し、actionKinds配列の並び順は実行順序を保証しません。アクション種別はカテゴリ優先の命名規則を採用しています。

• delayアクションは廃止され、遅延はタイムライン上の空白間隔として表現されます。
• 音声再生用の独立したAPIはありません。音声ファイル、再生制御、出力デバイスはデスクトップ側で管理されるため、外部クライアントから音声を再生する場合はaudio-playを含むオートメーションを実行または再生します。
• 古いホストから送信された旧アクション名（LEGACY_AUTOMATION_ACTION_KINDSに定義され、actionKindsおよびHotkey.actionに含まれる）は、SDKクライアント受信時に自動的に正規化されます（canonicalActionKind関数でも変換可能）。
• triggerKindsには、ショートカット以外に設定されたイベントトリガーの種類が含まれます（現在はscene、model-loaded、motion、face-tracking、microphone、parameter）。

automation-editing機能に対応している場合、automation.getは完全なAppAutomation（durationMs、autoDuration、id・startMs・durationMs・sourceInMs付きのactions、triggers、cooldownMs、accelerator、global、enabled）を返します。

• automation.createとautomation.updateはAutomationDefinitionを受け付けます（AutomationDefinitionSchemaで検証され、フィールドや時間指定が不正な場合はinvalid-paramsを返します）。
• 新規作成したオートメーションは無効状態（enabled: false）、ショートカット未割り当て（accelerator: null、global: false）で作成され、すべてのIDがサーバー側で新規採番されるため、ユーザーが有効化するまで自動実行されません。
• automation.updateはアクション、トリガー、長さ、クールダウンを置き換えてステップIDを再採番し、保存済みのショートカットaccelerator、global、enabledスイッチはそのまま維持します。
• API経由での作成・更新・削除は取り消し（Undo）に対応しておらず、デスクトップのタイムラインエディタに保持されている該当オートメーションの取り消し履歴もクリアされます。

automation-transport機能に対応している場合、automation.controlとautomation.statusでデスクトップのタイムライン再生を制御・確認できます（AutomationRunStatus：{ automationId, phase, positionMs, durationMs, error, steps }、現在のセッションでまだ実行・プレビュー・準備が行われていない場合はrun: null）。

• playはタイムラインを最後まで再生し（enabledがfalseでも再生可能で、一時停止またはスクラブ位置からはその位置から再開）、pauseは一時停止、prepareはメディアとアニメーションの事前読み込み、seekは再生ヘッドをpositionMsへ移動してステージ上でエフェクトクリップ・カメラ位置・レイヤーの表示・テキストを設定・歌詞を再生をプレビューし、stopは再生を停止してプレビュー状態を解放します。
• オートメーションのトランスポートを最後に操作したセッションがその所有権を持ちます。そのクライアントが切断されると、一時停止・プレビュー中・失敗状態の実行は自動的に停止してショートカットやトリガーが再び反応するようになり、再生中または準備中の実行もその後に一時停止または失敗へ入った時点で停止します。

キーボード、マウス、コントローラーのショートカットが割り当てられていないオートメーションはaccelerator: nullとなり、automation.runから遠隔実行できます。無効なルールはenabled: falseとなり、automation.runを含むすべてのトリガーを無視します（automation.controlのplayによる試聴再生は可能）。automation.runは実行完了を待たずに即座に応答を返します。一覧、定義、有効状態、バックグラウンドで反応する対象が変化すると、automation.stateイベントによって最新の要約一覧がプッシュ配信されます。

設定アンカーリンクをコピー

settings.getおよびsettings.patchは、安全な許可リストに基づいてアプリケーションのグローバル設定（ウィンドウピン留め、タスクトレイ格納、パフォーマンス設定、コントローラー有効化など）を読み書きします。内部ストア全体は公開されません。

レスポンスおよびsettings.changedイベントには、読み取り専用のウィンドウサイズ情報が含まれます。

• window.stageSize: { width, height }：デバイス非依存ピクセル（px）単位の現在のステージサイズ。ウィンドウのリサイズ時にリアルタイムで更新
• window.stageReferenceSize: { width, height }：配置単位およびモデルの自動フィット基準となる初期ステージサイズ。この高さがスケール比を定義し、ピン留めされていないScreenPlacementの1単位（x/y）は、ビューポート中心からstageSize.height / stageReferenceSize.heightデバイス非依存ピクセルの距離に対応

レンダラーはあらゆるアスペクト比でウィンドウ全体を埋めます。2Dコンテンツおよび透視投影3Dビューでは、幅のリサイズはコンテンツのリスケールや余白（黒帯）の追加を行わず、水平方向の表示領域の拡張またはクリッピングを行います。平行投影3Dビューはabs(orbit.distance)の幅を維持します。保存された配置設定はリサイズや再起動後も保持されます。配置UIを描画するクライアントは現在のstageSizeのアスペクト比に従ってください。旧ビルドではこれらのサイズ情報が省略される場合があり、デスクトップ上の物理ウィンドウ座標は常に非公開です。

パフォーマンス設定にはshowFps、fpsLimit、effectsQuality、renderScale（旧ビルドではオプション）が含まれます。コントローラープロファイルは設定内では読み取り専用であり、更新には専用のcontroller.*メソッドを使用します。レスポンスおよびsettings.changedイベントには読み取り専用のui.streamMode（配信モード）も含まれ、リモートパネル側で機密性の高いウェブページURLを伏せ字・マスク処理できます（古いホストでは省略される場合があります）。

プラグインストレージアンカーリンクをコピー

storage.*は外部プラグイン向けの永続的なKey-Valueストレージを提供します。データはAPIキーごとに独立した名前空間で分離されます。同一APIキーを使用するすべてのセッションでデータが共有され、キーを失効させると関連データもすべて自動消去されます。保存する値は任意のJSONシリアライズ可能データに対応します。

クォータ制限として、キー名は最大128文字、シリアライズ後の値は最大64KB、1つのAPIキーにつき最大256個のキーが保存可能です。キー数の上限を超えてstorage.setを呼び出すとinvalid-stateエラーが返されます。

エラーコードアンカーリンクをコピー

サーバーがエラーフレームを返した場合、persona.callはcode（API_ERROR_CODESのいずれか）を含むPersonaApiErrorで拒否されます。

これらのエラーコードは通信プロトコル仕様の一部です。クライアントは未知のエラーコードを含むエンベロープを破棄するため、新しいコードはメジャープロトコルリビジョンでのみ追加されます。新たに生じるエラーは既存のコードに割り当てられます。

クライアント自身またはトランスポート層でconnect()やcall()が失敗した場合は、reason（CLIENT_ERROR_REASONSのいずれか）を含むPersonaClientErrorで拒否されます。

• connect()ではconnect-timeout、connection-closed、またはclient-closedが発生します（url自体に接続できない場合は、同期スローではなくTypeErrorなどの実行環境のエラーでPromiseが拒否されます）。
• call()ではnot-connected、request-timeout、connection-closed、またはclient-closedが発生します。

切断と再接続アンカーリンクをコピー

SDKクライアントは予期せぬネットワーク切断が発生した際、指数バックオフを用いて自動的に再接続を試みます。以下のWebSocket切断コードは恒久的な終了状態を表し、自動再接続を停止します。

これらのコードを受信すると、クライアントは最終的にclosed状態に遷移します。onCloseコールバックが設定されている場合はそこに通知され、onWarningはスキップされます。onCloseが未設定の場合はonWarningに通知されます。標準コード1001（Going Away）はこれに該当せず、ホストの正常終了または再起動を表すため、クライアントは再接続試行を継続します。

キーを失効させると、送信待ちの未処理フレームは直ちに破棄され、そのキーを使用しているすべてのアクティブ接続がコード4001で切断されます。描画パイプラインの完了待ちだったリクエストは即座にキャンセルされます。ステージにすでに転送された描画指示は完了する場合がありますが、その応答は破棄されます。

プロトコルバージョンの変遷アンカーリンクをコピー

プロトコルにはメジャーバージョン番号が含まれており、クライアントとホスト間で不一致がある場合はSDKが警告を出力します。古いPersonaが認識しないイベントを購読しても致命的なエラーにはならず、SDKは個別購読モードに自動フォールバックし、利用可能なイベントの購読を維持したうえで、未サポートのイベント名を記録します。

現在のプロトコルバージョンは4です。これまでのメジャーバージョン改定で整理された内容は以下のとおりで、旧プロトコル向けのプラグインは対応する移行が必要です。