Qt/C++ で作成されたシンプルなプラグイン。
モデルの追加や削除などができる。
MIT ライセンスの下で作成されているので開発のベースとして使用可能。

nizima LIVE の MouseX/MouseY をウィンドウ内座標からモニター座標に拡張するプラグイン。
QML Sample をベースに作成した。
nizima LIVE からの起動時にはバックグランドで動作する。

Web プラグインのサンプル。
モデルのパラメータの現在値を表示できる。

nizima LIVE とプラグインがやり取りする際は、必ず以下の形式に沿った JSON を使用する。

型定義（TypeScript）

{
  nLPlugin: string,
  Timestamp?: number,
  Id?: string,
  Type: "Request" | "Response" | "Event" | "Error",
  Method: string,
  Data?: any
}

具体例（JSON）

{
  "nLPlugin": "1.0.0",
  "Timestamp": 1696233943287,
  "Id": "request13",
  "Type": "Request",
  "Method": "GetModelList",
  "Data": {}
}

これ以降では説明に必要な違いのある部分のみ記載し、共通の部分は省略されていることがある。

接続には WebSocket を使用する。
ローカルホスト限定で、リモートからは接続できない。
URL は ws://localhost:<port>/ で、port は nizima LIVE のプラグインマネージャーで確認できる。
port のデフォルトは 22022 となっている。

以下に API が使用可能になるまでのシーケンス図を示す。
通信内容の詳細な説明は後に続く。

sequenceDiagram
  actor user
  participant nl as nizima LIVE
  participant pl as Plugin Application

	user -) nl: 起動
	opt プラグイン機能が無効
		user -) nl: プラグイン機能を有効化
	end
  opt プラグインの自動起動が有効
    nl -) pl: "-l -p <port>" を引数として Plugin を実行
  end
  pl ->> nl: WebSocket で接続
  alt 初回接続
    pl ->>+ nl: Request RegisterPlugin(Name, ...)
    nl -) user: プラグインの追加を通知
    nl -->>- pl: Response RegisterPlugin(Token)
    Note over pl: Token を保存
  else 二回目以降
    Note over pl: Token を読込
    pl ->>+ nl: Request EstablishConnection(Name, Token, ...)
    alt Token が有効
      nl -->> pl: Response EstablishConnection(Enabled)
		  Note over nl, pl: ref: 各 Method の使用
    else Token が無効
      nl -->>- pl: Error EstablishConnection(InvalidToken)
      pl ->>+ nl: Request RegisterPlugin(Name, ...)
      nl -) user: プラグインの追加を通知
      nl -->>- pl: Response RegisterPlugin(Token)
      Note over pl: Token を保存
    end
  end
	user -) nl: プラグインを有効化
  nl -) pl: Event NotifyEnabledChanged(Enabled)
  opt Enabled が true
	  Note over nl, pl: ref: 各 Method の使用
  end

1. nizima LIVE を起動し、プラグイン機能を有効にする

2. WebSocket で nizima LIVE に接続

3. データ形式に沿って、以下のデータを送信する

   {
     "nLPlugin": "1.0.0",
     "Type": "Request",
     "Method": "RegisterPlugin",
     "Data": { "Name": "plugin name", "Developer": "your name" }
   }

   ここで送信する Data の内容は nizima LIVE のプラグインマネージャーの表示に使用される
   ほかにも設定できる項目があるので、必要があれば Method 一覧 の RegisterPlugin を参照すること

4. nizima LIVE から以下のデータが返ってくる

   {
     "nLPlugin": "1.0.0",
     "Type": "Response",
     "Method": "RegisterPlugin",
     "Data": { "Token": "f2jm8ASDe3..." }
   }

   Token は二回目以降の接続に使用するので保存しておく

5. nizima LIVE で登録したプラグインを有効にする

6. 以下のイベントが来るのを待つ

   {
     "nLPlugin": "1.0.0",
     "Type": "Event",
     "Method": "NotifyEnabledChanged",
     "Data": { "Enabled": true }
   }

   Data.Enabled が true であれば各 Method の使用が可能

1. WebSocket で nizima LIVE に接続

2. RegisterPlugin で登録した Name と取得した Token を用いて、以下のデータを送信する

   {
     "nLPlugin": "1.0.0",
     "Type": "Request",
     "Method": "EstablishConnection",
     "Data": {
       "Name": "plugin name",
       "Token": "f2jm8ASDe3..."
     }
   }

3. 応答を待つ

   • Error を受け取った場合

     {
       "nLPlugin": "1.0.0",
       "Type": "Error",
       "Method": "EstablishConnection",
       "Data": { "ErrorType": "InvalidToken" }
     }

     プラグインマネージャーから登録したプラグインを削除した場合は上記のエラーが返ってくる
     このままでは API の使用ができないので、初回接続の手順で再度登録する

   • Response を受け取った場合

     {
       "nLPlugin": "1.0.0",
       "Type": "Request",
       "Method": "EstablishConnection",
       "Data": { "Enabled": false }
     }

     Data.Enabled が true であれば各 Method の使用が可能
     false の場合は以下のイベントが来るのを待つ

     {
       "nLPlugin": "1.0.0",
       "Type": "Event",
       "Method": "NotifyEnabledChanged",
       "Data": { "Enabled": true }
     }

Method 一覧 に使用できる Method と説明が並べられている。
操作したい内容にあった Method を使用して Request を送信することで、nizima LIVE で処理が行われる。
処理が成功した場合は Response が、失敗した場合は Error が返ってくる。

sequenceDiagram
  participant nl as nizima LIVE
  participant pl as Plugin Application

  pl ->>+ nl: Request
  alt 処理に成功
	  nl -->> pl: Response
  else 処理に失敗
		nl -->>- pl: Error
  end

{
  "nLPlugin": "1.0.0",
  "Type": "Request",
  "Method": "GetCubismParameterValues",
  "Data": { "ModelId": "1" }
}

{
  "nLPlugin": "1.0.0",
  "Type": "Response",
  "Method": "GetCubismParameterValues",
  "Data": { "CubismParameterValues": [ { "Id": "ParamAngleX", "Value": 10.3 }, ... ] }
}

{
  "nLPlugin": "1.0.0",
  "Type": "Error",
  "Method": "GetCubismParameterValues",
  "Data": { "ErrorType": "InvalidModelId" }
}

イベント系の Method の名前は主に Notify~ で始まる。
一部のイベントを除き、使用するためにはイベントを有効にする必要がある。
イベントの有効状態は nizima LIVE に保存されないので、毎回有効にする必要がある。

sequenceDiagram
  participant nl as nizima LIVE
  participant pl as Plugin Application

  pl ->>+ nl: Request NotifyXxx(Enabled: true)
  nl -->>- pl: Response NotifyXxx()
  loop
    nl -) pl: Event NotifyXxx(...)
		break 止めたいとき
			pl ->>+ nl: Request NotifyXxx(Enabled: false)
		  nl -->>- pl: Response NotifyXxx()
    end
  end

{
  "nLPlugin": "1.0.0",
  "Type": "Request",
  "Method": "NotifyFrameUpdated"
}

{
  "nLPlugin": "1.0.0",
  "Type": "Response",
  "Method": "NotifyFrameUpdated"
}

{
  "nLPlugin": "1.0.0",
  "Type": "Event",
  "Method": "NotifyFrameUpdated",
  "Data": {
    "Models": [ {
      "ModelId": "1",
      "LiveParameterValues": [...],
      "CubismParameterValues": [...]
    }, ...]
  }
}

{
  "nLPlugin": "1.0.0",
  "Type": "Request",
  "Method": "NotifyFrameUpdated",
  "Data": { "Enabled": false }
}

Method の説明で使用される用語の説明

API を用いてどのようなことができるかは、Method 一覧 を参照すること。
ここでは Method 一覧 の見方について解説する。

• Xxx Data Type
  • それぞれ Request・Response・Event における Data の型を示す
  • 空の場合は {} と表記し、それ以外の場合は外側の {} は省略している
  • Request Data Type がある場合、Request を送信して Response を受信することができる
  • Event Data Type がある場合、Event を受信することができる
    • Event Data Type と Request Data Type の両方がある場合、Request を送信することで Event を有効にすることができる
• Error Types
  • 以下にある一般のエラー以外に発生し得るエラーを示す
    • InvalidPluginName
    • InvalidToken
    • InvalidApi
    • InvalidType
    • InvalidMethod
    • UnsupportedVersion
    • PluginDisabled
    • NotImplemented

{}

SceneId: string,
ModelId: string

{
  "nLPlugin": "1.0.0",
  "Timestamp": 1696233943287,
  "Id": "request1",
  "Type": "Request",
  "Method": "GetCurrentModelId",
  "Data": {}
}

{
  "nLPlugin": "1.0.0",
  "Timestamp": 1696233943531,
  "Id": "request1",
  "Type": "Response",
  "Method": "GetCurrentModelId",
  "Data": {
    "SceneId": "0",
    "ModelId": "1"
  }
}

Enabled?: boolean

{}

ModelId: string

{
  "nLPlugin": "1.0.0",
  "Timestamp": 1696233949432,
  "Id": "request2",
  "Type": "Request",
  "Method": "NotifyCurrentModelChanged",
  "Data": { "Enabled": true }
}

{
  "nLPlugin": "1.0.0",
  "Timestamp": 1696233949626,
  "Id": "request2",
  "Type": "Response",
  "Method": "GetCurrentModelId",
  "Data": {}
}

{
  "nLPlugin": "1.0.0",
  "Timestamp": 1696233951345,
  "Type": "Event",
  "Method": "GetCurrentModelId",
  "Data": { "ModelId": "2" }
}

{
  "nLPlugin": "1.0.0",
  "Timestamp": 1696233965395,
  "Id": "request3",
  "Type": "Request",
  "Method": "NotifyCurrentModelChanged",
  "Data": { "Enabled": false }
}

バージョンは セマンティックバージョニング 2.0.0 に従う。

互換性が切れる変更の時に上げる

新しい Method が追加されるときに上げる

Data の内容が追加されるときに上げる

*1: 非対応の Data が取得できなかったり無視されたりする

*2: 非対応の Method は使用できない

初回リリース