Live2D Cubism Editor 5.1 alpha1 外部アプリケーション連携 開発者向けマニュアル |
2024/03/28 r1
バージョン | 改訂日 | 改訂内容 |
r1 | 2024/03/28 | 初版作成 |
エディタと外部アプリケーションでAPIを通して連携することができます。
Live2D Garageにサンプルを提供しています。
・GitHub Live2D GARAGE - CubismExternalAppPluginSamples
https://github.com/Live2D-Garage/CubismExternalAppPluginSamples
通信規格 | WebSocket |
フォーマット | JSON(UTF-8 テキスト) |
ポート | 22033 ※デフォルトのポート番号。 任意に変更可能。 |
エディタがサーバー、外部アプリケーションがクライアントになります。
Token ?: String, |
「?」が付いている要素は、指定を省略することが可能です。
{ "Version": "1.0.0", "Timestamp": 1696233943287, "RequestId": "13", "Type": "Request", "Method": "GetCurrentModelUID", "Data": {} } |
送信、受信共に以下のJSON形式でやりとりします。
Version〜Typeまでは全命令で共通になります。
要素 | タイプ | 要求 | 説明 |
Version | String | 必須 | API、命令のバージョンを指定します。 やりとりするバージョンを固定でき、互換性を維持することができます。未対応バージョンを設定した場合はエラーとなります。 |
Timestamp | Number | 任意 | エポックミリ秒。省略可能。 |
RequestId | String | 任意 | サーバーからのレスポンス時に送信で送ったIDを返します。省略した場合、サーバーレスポンスでも省略されます。 |
Type | String | 必須 | |
Method | String | 必須 | 命令。 |
Data | Any | 必須 | 操作に応じた追加データ。 |
タイプ | 説明 |
Request | 要求: 主にクライアント(外部アプリケーション)からサーバー(Editor)に命令を送る際に設定されます。 |
Response | 応答: 主にサーバーがクライアントからの命令に答える際に設定されます。 |
Event | イベント: 主にサーバーが任意のタイミング(クライアントからRequestが無い状態)で、自発的にクライアントへ応答する際に設定されます。 |
Error | エラー: Requestに不正があった場合、この値が設定されたAPIをクライアントへ返します。 |
{ (省略) "Type": "Error", "Method": "SetParameterValues", "Data": { "ErrorType" : "InvalidParameter" } } |
TypeがErrorのJSONを返します。
エラー内容はErrorTypeに種類が記入されます。
詳細は「 エラータイプ」をご覧ください。
意図しない外部アプリからエディタを守るため、ユーザーが許可しない限り外部アプリからの通信を遮断する、認証システムが組み込まれています。
接続後、まず最初にRegisterPluginで新規トークンを取得します。
トークンを取得しても、自由に通信が行えるわけではありません。
ユーザーが設定ダイアログから「許可」のチェックボックスを有効にすることで、初めてAPIが使用可能となります。
よって、外部アプリはそれまで待機する必要があります。
2回目からはユーザーによる許可をスキップすることができます。
先の接続で使用したトークンをRegisterPluginで指定してください。
ユーザーが許可していれば、RegisterPluginは指定したトークンをそのまま返し、即APIが使える状態にします。
トークンが許可されていない場合は、新しいトークンを返し、ユーザーがもう一度許可するまで通信は遮断されます。
APIは即時実行が基本ですが、パラメータは物理演算やランダムポーズの関係で反映タイミングに遅延があります。実際は以下のように一時バッファを経由して反映されます。
{ "Data": { "ModelUID" : "8456858123561231456" // UID } } { "Data": { "Parameters" : [{"Id":"ParamAngleY","Value":"0.0"}] // ParameterID } } |
パラメータIDは(モデルに変更を加えない限り)不変な値ですが、UIDは接続ごとに値が変化する可能性がある一時的なIDです。
外部アプリケーションをエディタに登録します。
登録が終わるとトークンを返します。このトークンはアプリと紐付いており、次回の接続時に指定することでユーザーの許可状態を引き継ぐことができます。
詳しくは「トークン認証」をご覧ください。
Version | Request | Response | ErrorType |
0.9.0 | Name:String, Token?:String, Icon?:String, Path?:String | Token:String | InvalidData |
Name:String | アプリケーション名。(任意) ユニークな名前を付けてください。 他のアプリと名前が被っても動作に影響はありません。 |
Token?:String | トークン。 指定されたトークンが登録済みの場合は、そのトークンをそのまま返します。 |
Icon?:String | アイコンPNG画像のBASE64文字列。 現在は指定してもエディタに表示されません。 |
Path?:String | アプリケーションのパス情報。 |
注意事項 RegisterPluginを最初に行い、ユーザーから許可を貰わない限り、以下のほぼすべての命令はPluginNotRegisteredのエラーを返し、APIによる操作を受け付けません。 |
ユーザーがこのアプリに対して通信を許可しているかどうかを取得します。
設定ダイアログの「許可」カラムのチェックボックスと連動しています。
Version | Request | Response | ErrorType |
0.9.0 | Result:Boolean | InvalidData |
パラメータIDを指定してモデルの現在のパラメータIDと値を取得します。
パラメータIDの指定がない場合はモデルの全パラメータIDと値を取得します。
Version | Request | Response | ErrorType |
0.9.0 | ModelUID:string, Ids?:Array<string> | Parameters:Array<{ Id:String, Value:Number }> | InvalidData InvalidModel |
指定のパラメータIDと値を設定します。
Version | Request | Response | ErrorType |
0.9.0 | ModelUID:String, Parameters:Array<{ Id:String, Value:Number }> | InvalidData InvalidModel InvalidParameter |
モデルがもつパラメータ一覧を取得します。
ModelUIDとDocumentUIDは省略可能ですがどちらかは必須となります。
Typeは ’0‘ が通常、 ‘1’ がブレンドシェイプになります。
モデルが組み込み用モデルトラックの場合、GroupUIDには空文字が返ります。
アニメーションファイル(.can3)のモデルがもつパラメータ一覧は取得できません。
Version | Request | Response | ErrorType |
0.9.0 | ModelUID?:String, DocumentUID?:String | Parameters:Array<{ Id:String, Name:String, GroupUID:String, Default:Number, Max:Number, Min:Number, Repeat:boolean Type:Number }> | InvalidData InvalidModel |
Id:String | パラメータID。 |
Name:String | パラメータ名。 |
GroupUID:String | 所属するパラメータグループのUID。 |
Default:Number | デフォルト値。 |
Max,Max:Number | 最大値、最小値。 |
Repeat:boolean | リピート。 |
Type:Number | パラメータタイプ。 1 : ブレンドシェイプ |
モデルがもつパラメータグループの一覧を取得します。
ModelUIDとDocumentUIDは省略可能ですがどちらかは必須となります。
モデルが組み込み用モデルトラックの場合、GroupUIDには空文字が返ります。
アニメーションファイル(.can3)に含まれるモデルがもつパラメータ一覧は取得できません。
Version | Request | Response | ErrorType |
0.9.0 | ModelUID?:String, DocumentUID?:String | Groups:Array<{ GroupUID:String, GroupName:String, }> | InvalidData InvalidModel |
ドキュメントの情報を返します。
物理演算、モデル編集と種類ごとに別れ、存在しない場合は0個のドキュメント配列を返します。1モデルの分割表示を行った場合は、Viewsが増えます。
Version | Request | Response | ErrorType |
0.9.0 | PhysicsDocuments:Array<{ DocumentUID:String, DocumentFilePath:String, ModelUID:String }>, ModelingDocuments:Array<{ DocumentUID:String, DocumentFilePath:String, Views:Array<{ ModelUID:String }> }> | InvalidData InvalidDocument |
現在エディタ上でカレントになっているモデルのUIDを返します。
アニメーションファイルに含まれるモデルのUIDは取得できません。
Version | Request | Response | ErrorType |
0.9.0 | ModelUID:String | InvalidData InvalidModel |
現在エディタ上でカレントになっている編集モードを返します。
Version | Request | Response | ErrorType |
0.9.0 | EditMode:String | InvalidData |
EditMode:String | 編集モード。 “Animation” : アニメーション編集 “ModelingMeshEdit” : メッシュ編集 |
イベントを扱う場合は、まずクライアントがサーバーに対して許可フラグを有効にする必要があります。
{ (省略) "Type": "Request", "Method": "NotifyMocFileExported", "Data": { "Enable" : true } } |
すると、サーバーは特定の処理(イベント)を行った際に、クライアントからのリクエストに関係なく、JSONを送信します。
{ (省略) "Type": "Response", "Method": "NotifyMocFileExported", "Data": { "Path" : "c:\\temp\\export.moc3", "ModelFilePath" : "c:\\models\\hoge03.cmo3" } } |
物理演算設定ファイルの書き出し時の通知設定を行います。
Version | Request | Response | Event | ErrorType |
0.9.0 | Enabled:Boolean | Accepted:Boolean | Path:String, ModelFilePath:String | InvalidData |
MOC3ファイルの書き出し時の通知設定を行います。
Version | Request | Response | Event | ErrorType |
0.9.0 | Enabled:Boolean | Accepted:Boolean | Path:String, ModelFilePath:String | InvalidData |
モーションファイルの書き出し時の通知設定を行います。
Version | Request | Response | Event | ErrorType |
0.9.0 | Enabled:Boolean | Accepted:Boolean | Path:String, ModelFilePath:String | InvalidData |
モーションシンク設定ファイルの書き出し時の通知設定を行います。
Version | Request | Response | Event | ErrorType |
0.9.0 | Enabled:Boolean | Accepted:Boolean | Path:String, ModelFilePath:String | InvalidData |
編集モードが切り替わったときの通知設定を行います。
EditModeについては「GetCurrentEditMode」をご覧ください。
Version | Request | Response | Event | ErrorType |
0.9.0 | Enabled:Boolean | Accepted:Boolean | EditMode:String | InvalidData |
名前 | 説明 | Since |
InvalidJson | JSON構造が正しくありません。 | 0.9.0 |
UnsupportedVersion | 互換性のないバージョンです。 | 0.9.0 |
MethodNotFound | 指定された命令が見つかりません。 | 0.9.0 |
InvalidType | Typeの設定が不正です。 | 0.9.0 |
InvalidData | 命令の引数が正しくありません。 | 0.9.0 |
PluginNotRegistered | プラグインの登録が完了していません。 | 0.9.0 |
InvalidParameter | 指定されたLive2Dパラメータが存在しません。 | 0.9.0 |
InvalidModel | 指定されたLive2Dモデルが存在しません。 | 0.9.0 |
InvalidDocument | 指定されたドキュメントがエディタに存在しません。 | 0.9.0 |
InvalidView | 指定されたビューが存在しません。 | 0.9.0 |
本alpha版では、一部未実装の機能や既知の不具合、その他懸念される項目について、特に明記すべき事柄を記載しています。通常は、alpha版のバージョンアップにより制限が解除される予定ですが、保証するものではありません。
アニメーションファイルに含まれるモデル情報は取得できません。
外部アプリケーションと連携するときに、API「RegisterPlugin」のIconに情報を設定しても外部アプリケーション連携設定ダイアログのUIには反映されません。