VTube Studio APIの使い方
本記事は以下リンクを日本語訳した記事です。
Link
GitHub - DenchiSoft/VTubeStudio: VTube Studio API Development Page
Event API
A.APIの詳細
VTube StudioのWebSocketサーバーはws://localhost:8001で実行されます。これはデフォルトですが、ユーザーはアプリ内でポートを変更することもできます。Websocketsは一般的にバイナリとテキストメッセージをサポートしていますが、VTube Studioは常にテキストメッセージで応答するように設計されており、APIにもテキストメッセージを送信することを推奨します。バイナリメッセージを送信することもできますが、その場合はUTF-8でエンコードされていることを確認してください。
あなたのプラグインがWebSocketサーバーに接続できない場合、ユーザーにポートが正しいか、接続を妨げるファイアウォール/アンチウイルス設定がないかを確認するように伝えてください。最も重要なことは、ユーザーにVTube Studioで「プラグインAPIアクセスを許可する」ように要求することです。これはVTSのメイン設定ページのオプションです。また、プラグインが接続に使用するポートを構成できるようにすることも重要です。
接続できた場合は、最初にセッションの状態を確認することができます。
REQUEST
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"requestID": "MyIDWithLessThan64Characters",
"messageType": "APIStateRequest"
}
RESPONSE
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"timestamp": 1625405710728,
"messageType": "APIStateResponse",
"requestID": "MyIDWithLessThan64Characters",
"data": {
"active": true,
"vTubeStudioVersion": "1.9.0",
"currentSessionAuthenticated": false
}
}
全てのリクエストには、"apiName" : "VTubeStudioPublicAPI" と使用されるAPIバージョンが含まれている必要があります。最初のリリース時点では、APIバージョンは "1.0" になります。
このAPIバージョンは、動作/ペイロードに非互換な変更があるまで同じままです。これは、APIに新しい機能が追加されることがあるため（既存のペイロードに新しいフィールドが含まれる場合を含む）、バージョンを増やさなくてもよいことを意味します。アプリがこれを処理できるようにし、逆シリアル化中に未知のフィールドに遭遇しても壊れないようにしてください。
非互換な変更の例としては、既存のフィールドの名前変更または完全に削除することが挙げられます。非互換な変更がある場合、APIバージョンがそれらのために増加するため、古いAPIはそのまま使用できます。
全てのリクエストに"requestID"フィールドを追加することができます。これはオプションですが、リクエストに対するレスポンスを識別することができるため、推奨されます。このIDは、VTube Studioログにリクエストを記録するためにも使用されます。何か問題が発生した場合、このIDを参照してログ内のこのリクエストに関連するエラーを確認できます。
同じIDまたは異なるIDを各リクエストに使用することができます。提供される場合、IDはASCII文字のみを含み、1文字以上64文字以下である必要があります。"requestID"フィールドを追加しない場合、VTube Studioはリクエストのランダムに生成されたUUIDを追加し、レスポンスと一緒に返します。
"currentSessionAuthenticated"は、現在のセッションがすでに認証されているかどうかを示します。
可能なすべてのエラーIDは、ErrorsID.cs.にリストされています。
接続すると、クライアントはいつでも現在のアプリ状態に関する情報をポーリングすることができます。
お試しコード
import asyncio
import json
import websockets
async def send_request():
uri = "ws://localhost:8001"
async with websockets.connect(uri) as websocket:
request = {
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"requestID": "MyIDWithLessThan64Characters",
"messageType": "APIStateRequest"
}
await websocket.send(json.dumps(request))
response = await websocket.recv()
print(f"Received: {response}")
asyncio.get_event_loop().run_until_complete(send_request())
実行結果
Received: {"apiName":"VTubeStudioPublicAPI","apiVersion":"1.0","timestamp":1681139800253,"messageType":"APIStateResponse","requestID":"MyIDWithLessThan64Characters","data":{"active":true,"vTubeStudioVersion":"1.24.12","currentSessionAuthenticated":false}}
B.API Server Discovery (UDP)
VTube Studioは、APIの状態をUDPでローカルネットワーク上に放送します。ポート番号は47779です。これは、ユーザーがAPIをオフにしていても、2秒ごとに実行されます。instanceIDは、VTube Studioインスタンスが開始されたときに生成されるランダムなIDです。このインスタンスが実行されている間は変更されないため、2つのVTube Studioインスタンスには異なるIDがあります。
windowTitleは、ウィンドウのタイトルテキストです。Windowsでは、これは異なるVTSインスタンスに対して異なります。複数のインスタンスが開始された場合、最初のインスタンスはタイトルがVTube Studio、2番目のインスタンスはタイトルがVTube Studio Window 2となります。macOSでは、すべてのインスタンスのタイトルはVTube Studioになります。
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"timestamp": 1630159656406,
"messageType": "VTubeStudioAPIStateBroadcast",
"requestID": "VTubeStudioAPIStateBroadcast",
"data": {
"active": false,
"port": 8001,
"instanceID": "93aa0d0494304fddb057ae8a295c4e59",
"windowTitle": "VTube Studio"
}
}
お試しコード
import socket
import json
def main():
# UDPソケットを作成し、ポート47779でリッスンします
udp_socket = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
udp_socket.bind(("0.0.0.0", 47779))
while True:
# UDPパケットを受信し、JSONデータを解析します
data, _ = udp_socket.recvfrom(1024)
json_data = json.loads(data.decode("utf-8"))
# messageTypeがVTubeStudioAPIStateBroadcastの場合、ウィンドウタイトルを表示します
if json_data.get("messageType") == "VTubeStudioAPIStateBroadcast":
window_title = json_data["data"]["windowTitle"]
print(f"Window Title: {window_title}")
if __name__ == "__main__":
main()
実行結果
Window Title: VTube Studio
Window Title: VTube Studio
Window Title: VTube Studio
C.認証
APIを使用する前に、一度だけ認証する必要があります。そのために、あなたのプラグイン名と開発者の名前を提供する必要があります。それぞれ3文字以上32文字以下である必要があります。
これは、あなたのプラグインのためのトークンをリクエストすることで行われます。次のリクエストを送信してください。
REQUEST
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"requestID": "SomeID",
"messageType": "AuthenticationTokenRequest",
"data": {
"pluginName": "My Cool Plugin",
"pluginDeveloper": "My Name",
"pluginIcon": "iVBORw0.........KGgoA="
}
}
ユーザーがAPIアクセスを有効にしている場合、これによりVTS内でポップアップがトリガーされ、ユーザーに対して"My Name"による"My Cool Plugin"がVTube Studioを制御することを許可するかどうかを尋ねます。 "pluginIcon"はオプションで追加できます。これは、128x128ピクセルの正確な寸法を持つ、Base64エンコードされたPNGまたはJPG画像である必要があります。これを追加すると、ユーザーに表示されるプラグインアクセスリクエストポップアップでアイコンが使用されます。ユーザーが「許可」をクリックすると、次のレスポンスが返されます。
RESPONSE
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"timestamp": 1625405710728,
"requestID": "SomeID",
"messageType": "AuthenticationTokenResponse",
"data": {
"authenticationToken": "adcd-123-ef09-some-token-string-abcd"
}
}
"authenticationToken"フィールドには、API認証に使用されるASCII文字列が含まれています。最大で64文字です。アクセスを拒否された場合、以下のエラーが発生します。
RESPONSE
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"timestamp": 1625405710728,
"requestID": "SomeID",
"messageType": "APIError",
"data": {
"errorID": 50,
"message": "User has denied API access for your plugin."
}
}
ユーザーは、VTube Studio内からあなたのプラグインに対するAPIアクセスをいつでも取り消すことができます。取り消された場合、リクエストを送信しようとするとこのエラーが返されます。この場合、再度認証を試みることができます。
トークンを取得する必要は1度だけです。このトークンを使用して、このセッションに対して認証することができます。次のセッション（たとえば、VTSが再起動される場合や、プラグインが何らかの理由でVTSに再接続する必要がある場合など）では、同じトークンを使用して再認証できます。これにより、再度トークンを取得するためにリクエストを送信する必要がなく、ユーザーにはプラグインを許可することについて1回だけ尋ねることができます。
1つのセッションに対して認証するには、次のリクエストをトークンと一緒に送信してください。
REQUEST
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"requestID": "SomeID",
"messageType": "AuthenticationRequest",
"data": {
"pluginName": "My Cool Plugin",
"pluginDeveloper": "My Name",
"authenticationToken": "adcd-123-ef09-some-token-string-abcd"
}
}
"pluginName"と"pluginDeveloper"は、トークンをリクエストしたときに使用した値と一致する必要があります。そうでない場合、認証リクエストは失敗します。
トークンが有効であり、ユーザーによってAPIアクセスが取り消されていない場合、次のレスポンスが返されます。
RESPONSE
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"timestamp": 1625405710728,
"requestID": "SomeID",
"messageType": "AuthenticationResponse",
"data": {
"authenticated": true,
"reason": "Token valid. The plugin is authenticated for the duration of this session."
}
}
おめでとうございます。認証され、VTube Studio APIを使用できます。
必須フィールドが欠落している場合は、エラーレスポンスが返されます。すべてのフィールドが存在し、適切にフォーマットされているが、トークンが無効であるか、ユーザーによって取り消された場合、"authenticated"はfalseとして返されます。
**data**フィールドに関する注意：一部のリクエストにはdataJSONオブジェクトフィールドが含まれ、一部には含まれません。あなたのために、データが必要ないリクエストにもこのフィールドを含めることができます。あなたがそれを空にしたり、null/undefinedに設定したとしても、VTube Studioはそれを無視します。VTube Studioは、逆シリアル化をプラグインで容易にするために、すべてのリクエストでこのフィールドを返します。応答にデータが含まれていない場合、フィールドには空のJSONオブジェクトが含まれます。
**timestamp**フィールドに関する注意：すべてのレスポンスには、あなたのリクエストが処理されたUNIXミリ秒タイムスタンプが含まれる"timestamp"フィールドがあります。リクエストに"timestamp"フィールドを含めることができますが、無視されます。
お試しコード(VTS上で認証する必要があります。)
import asyncio
import json
import websockets
async def request_token(websocket, plugin_name, plugin_developer, plugin_icon=None):
request = {
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"requestID": "TokenRequestID",
"messageType": "AuthenticationTokenRequest",
"data": {
"pluginName": plugin_name,
"pluginDeveloper": plugin_developer,
"pluginIcon": plugin_icon
}
}
await websocket.send(json.dumps(request))
response = await websocket.recv()
json_response = json.loads(response)
if json_response["messageType"] == "AuthenticationTokenResponse":
return json_response["data"]["authenticationToken"]
else:
return None
async def authenticate(websocket, plugin_name, plugin_developer, authentication_token):
request = {
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"requestID": "AuthenticationRequestID",
"messageType": "AuthenticationRequest",
"data": {
"pluginName": plugin_name,
"pluginDeveloper": plugin_developer,
"authenticationToken": authentication_token
}
}
await websocket.send(json.dumps(request))
response = await websocket.recv()
json_response = json.loads(response)
if json_response["messageType"] == "AuthenticationResponse":
return json_response["data"]["authenticated"]
else:
return False
async def main():
uri = "ws://localhost:8001"
async with websockets.connect(uri) as websocket:
plugin_name = "My Cool Plugin"
plugin_developer = "My Name"
authentication_token = await request_token(websocket, plugin_name, plugin_developer)
if authentication_token:
print(f"Token: {authentication_token}")
is_authenticated = await authenticate(websocket, plugin_name, plugin_developer, authentication_token)
print(f"Authenticated: {is_authenticated}")
else:
print("Token request failed")
asyncio.get_event_loop().run_until_complete(main())
実行結果
Token: 3c0ec7574c8728...........e9e2706f89eede0b4c
Authenticated: True
イベントの購読と購読解除
以前のAPIバージョンでは、ロードされたモデルやアイテムなどの情報を、プラグインが繰り返しポーリングする必要がありました。VTube Studioは、現在、プラグインが関連する何かが起こっているときにメッセージを送信するようになった「イベント」の購読をサポートしています。イベントには、アイテムがロードされたとき、トラッキングが失われた/回復したとき、モデルがクリックされたときなどが含まれます。
イベントに関するページをこちらで確認してください。
現在のVTS統計情報の取得
REQUEST
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"requestID": "SomeID",
"messageType": "StatisticsRequest"
}
RESPONSE
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"timestamp": 1625405710728,
"requestID": "SomeID",
"messageType": "StatisticsResponse",
"data": {
"uptime": 1439384,
"framerate": 73,
"vTubeStudioVersion": "1.9.0",
"allowedPlugins": 7,
"connectedPlugins": 2,
"startedWithSteam": true,
"windowWidth": 1031,
"windowHeight": 812,
"windowIsFullscreen": false
}
}
"uptime"には、VTube Studioが開始されてからのミリ秒数が含まれます。"framerate"は現在のレンダリングFPS値です。"allowedPlugins"は、ユーザーが現在VTube Studioを使用することを許可したプラグインの数、"connectedPlugins"は、現在VTube Studio APIに接続しているプラグインの数です。"startedWithSteam"は、アプリがSteamを使用して起動された場合はtrue、それ以外の場合はfalse（.batファイルを使用してSteamなしでVTSを起動した場合）です。
ウィンドウの幅と高さはピクセル単位です。
6:VTSフォルダーのリストを取得
VTube Studioのさまざまなフォルダーの名前を返します。これらは、ゲームファイルのStreamingAssetsフォルダーにあります。
REQUEST
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"requestID": "SomeID",
"messageType": "VTSFolderInfoRequest"
}
RESPONSE
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"timestamp": 1625405710728,
"requestID": "SomeID",
"messageType": "VTSFolderInfoResponse",
"data": {
"models": "Live2DModels",
"backgrounds": "Backgrounds",
"items": "Items",
"config": "Config",
"logs": "Logs",
"backup": "Backup"
}
}
7:現在読み込まれているモデルの取得
REQUEST
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"requestID": "SomeID",
"messageType": "CurrentModelRequest"
}
RESPONSE
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"timestamp": 1625405710728,
"requestID": "SomeID",
"messageType": "CurrentModelResponse",
"data": {
"modelLoaded": true,
"modelName": "My Currently Loaded Model",
"modelID": "UniqueIDToIdentifyThisModelBy",
"vtsModelName": "Model.vtube.json",
"vtsModelIconName": "ModelIconPNGorJPG.png",
"live2DModelName": "Model.model3.json",
"modelLoadTime": 3021,
"timeSinceModelLoaded": 419903,
"numberOfLive2DParameters": 29,
"numberOfLive2DArtmeshes": 136,
"hasPhysicsFile": true,
"numberOfTextures": 2,
"textureResolution": 4096,
"modelPosition": {
"positionX": -0.1,
"positionY": 0.4,
"rotation": 9.33,
"size": -61.9
}
}
}
"modelLoaded"は、現在モデルがロードされている場合はtrueになります。モデルがロードされていない場合、またはモデルが現在ロード中の場合は、falseになります。この場合、すべての他の値は空になります（整数の場合はゼロ）。
"modelLoadTime"は、現在のモデルをロードするのにかかった時間（ミリ秒単位）です。"timeSinceModelLoaded"には、モデルがロードされてからの経過時間（ミリ秒単位）が含まれます。
"vtsModelIconName"には、VTube Studioのモデル選択バーでこのモデルに使用されるアイコンの名前が含まれます。モデルにアイコンが設定されていない場合、これは空の文字列になります。このリクエストで返されるすべてのファイル名は、それぞれのモデルフォルダに相対的です。
"modelPosition"配列には、現在のモデルの位置、回転、サイズが含まれています。これらの値の解釈方法についての詳細については、MoveModelRequestを参照してください。
8:VTS対応モデル一覧の取得
REQUEST
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"requestID": "SomeID",
"messageType": "AvailableModelsRequest"
}
RESPONSE
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"timestamp": 1625405710728,
"requestID": "SomeID",
"messageType": "AvailableModelsResponse",
"data": {
"numberOfModels": 2,
"availableModels": [
{
"modelLoaded": false,
"modelName": "My First Model",
"modelID": "UniqueIDToIdentifyThisModelBy1",
"vtsModelName": "Model_1.vtube.json",
"vtsModelIconName": "ModelIconPNGorJPG_1.png"
},
{
"modelLoaded": true,
"modelName": "My Second Model",
"modelID": "UniqueIDToIdentifyThisModelBy2",
"vtsModelName": "Model_2.vtube.json",
"vtsModelIconName": "ModelIconPNGorJPG_1.png"
}
]
}
}
"modelLoaded"は、それぞれのモデルがVTube Studioに現在ロードされている場合はtrue、そうでない場合はfalseとなります。
9:VTSモデルをIDで読み込む
REQUEST
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"requestID": "SomeID",
"messageType": "ModelLoadRequest",
"data": {
"modelID": "UniqueIDOfModelToLoad"
}
}
RESPONSE
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"timestamp": 1625405710728,
"requestID": "SomeID",
"messageType": "ModelLoadResponse",
"data": {
"modelID": "UniqueIDOfModelThatWasJustLoaded"
}
}
このリクエストは、設定ウィンドウが開いている場合や、モデルのロード操作が既に進行中の場合など、現在モデルをロードできない状態にある場合には失敗し、エラーが返されることがあります。このリクエストには、グローバルな2秒間のクールダウンがあります。
10:現在ロードされているVTSモデルの移動
モデルがロードされている場合、その位置、回転、サイズを変更することができます。モデルがロードされていない場合、これはエラーを返します（ErrorsID.csを参照）。
このリクエストで必要なフィールドは、"timeInSeconds"と"valuesAreRelativeToModel"です。"timeInSeconds"は、移動にかかる時間（秒単位）であり、0から2の間の浮動小数点値である必要があります。これを0に設定すると、モデルはすぐに指定された位置に現れます。それ以上の値は、モデルを滑らかに移動、回転、拡大/縮小して指定された位置に移動させます（フェードイン/アウト）。移動中は、ユーザーは手動でモデルをドラッグして移動することはできません。モデルが移動先に到達した後、約半秒後に再び可能になります。
進行中のリクエストを待たずに、後続のMoveModelRequestを送信することができます。進行中のリクエストがある場合、新しいリクエストによって中断され、置き換えられます。フレームごとに1つのリクエストを送信して、"timeInSeconds"に0を設定することで、移動を完全に制御することもできます。
"size"は、-100（最小）から+100（最大）までの浮動小数点数で指定されます。「positionX」、「positionY」、「rotation」については、次の図を参照してください：
VTS座標系
猫の数字は、"positionX"と"positionY"を使用して渡すことができる[X/Y]座標を表します。たとえば、[0/0]を送信すると、モデルの中心が画面の中央に配置されます。"モデルの中心"は、Live2D Cubismで自由に設定でき、モデルによって異なる場合があります。もちろん、画面外にモデルを移動させるために、はるかに大きな/小さな値を送信することもできます。"positionX"と"positionY"は、-1000から1000の間でなければなりません。
円周の数字は、"rotation"を使用して設定できる角度を表します。このパラメータの値は、-360から360の間でなければなりません。各角度には、時計回りに回転する場合は正、反時計回りに回転する場合は負の2つの表現があります。どちらを使用するかは任意です。CurrentModelRequestを送信すると、レスポンスにはモデルの位置/回転/サイズも含まれます。このレスポンスでは、角度は常に正の表記で表されます。
リクエストですべての値を提供する必要はありません。たとえば、位置だけを提供したり、回転だけを提供したり、他の任意の組み合わせを提供できます。位置/回転/サイズを設定するときに含まれていないすべての値は無視されます。これにより、モデルのX座標のみを変更しつつ、他のすべてをそのままにすることができます。
"valuesAreRelativeToModel"がfalseに設定されている場合、リクエストからの値は絶対値として取得され、モデルはその位置に移動します。"valuesAreRelativeToModel"がtrueに設定されている場合、値は現在のモデル位置を基準に考慮されます。たとえば、回転に10を含めることだけをリクエストに含めた場合、現在の回転位置から時計回りに10度回転し、位置とサイズには何も変更されません。これは、画面のどこにあるかに関係なく、モデルを揺らすなど、場所を移動する効果を実装するのに非常に便利です。
モデルを固定ピクセル位置に移動させたり、特定のピクセル数だけ移動させたい場合は、StatisticsRequestを使用してピクセル単位でウィンドウの幅と高さを取得して、対応する座標を計算する必要があります。
REQUEST
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"requestID": "SomeID",
"messageType": "MoveModelRequest",
"data": {
"timeInSeconds": 0.2,
"valuesAreRelativeToModel": false,
"positionX": 0.1,
"positionY": -0.7,
"rotation": 16.3,
"size": -22.5
}
}
RESPONSE
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"timestamp": 1625405710728,
"requestID": "SomeID",
"messageType": "MoveModelResponse",
"data": { }
}
11:現行モデルまたは他のVTSモデルで使用可能なホットキーのリストを要求する
REQUEST
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"requestID": "SomeID",
"messageType": "HotkeysInCurrentModelRequest",
"data": {
"modelID": "Optional_UniqueIDOfModel",
"live2DItemFileName": "Optional_Live2DItemFileName"
}
}
この場合、"modelID"と"data"オブジェクトはオプションです。それらが提供されない場合、現在のモデルのホットキーが返されます。モデルIDが指定されている場合、指定されたモデルIDを持つモデルのホットキーが返されます。そのIDのモデルが見つからない場合はエラーが返されます（ErrorID.cs、ModelIDNotFoundを参照）。
これは利用可能なLive2Dアイテムのホットキーも返すことができます。その場合、単に"live2DItemFileName"フィールドにアイテムのファイル名を渡します。利用可能なすべてのLive2Dアイテムの（ユニークな）ファイル名は、ItemListRequestを使用して取得できます。
"modelID"と"live2DItemFileName"の両方が提供されている場合、使用されるのは"modelID"のみで、他のフィールドは無視されます。
RESPONSE
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"timestamp": 1625405710728,
"requestID": "SomeID",
"messageType": "HotkeysInCurrentModelResponse",
"data": {
"modelLoaded": true,
"modelName": "My Currently Loaded Model",
"modelID": "UniqueIDOfModel",
"availableHotkeys": [
{
"name": "My first hotkey",
"type": "ToggleExpression",
"description": "Toggles an expression",
"file": "myExpression_1.exp3.json",
"hotkeyID": "SomeUniqueIdToIdentifyHotkeyWith1",
"keyCombination": [],
"onScreenButtonID": 8
},
{
"name": "My second hotkey",
"type": "TriggerAnimation",
"description": "Triggers an animation",
"file": "myAnimation.motion3.json",
"hotkeyID": "SomeUniqueIdToIdentifyHotkeyWith2",
"keyCombination": [],
"onScreenButtonID": -1
},
{
"name": "My third hotkey",
"type": "ChangeVTSModel",
"description": "Changes the VTS model",
"file": "someOtherModel.vtube.json",
"hotkeyID": "SomeUniqueIdToIdentifyHotkeyWith3",
"keyCombination": [],
"onScreenButtonID": -1
},
{
"name": "My fourth hotkey",
"type": "MoveModel",
"description": "Moves the Live2D model",
"file": "",
"hotkeyID": "SomeUniqueIdToIdentifyHotkeyWith4",
"keyCombination": [],
"onScreenButtonID": -1
},
{
"name": "My fifth hotkey",
"type": "Unset",
"description": "No action set for hotkey",
"file": "",
"hotkeyID": "SomeUniqueIdToIdentifyHotkeyWith5",
"keyCombination": [],
"onScreenButtonID": 5
}
]
}
}
リクエストでモデルIDが指定されておらず、モデルがロードされていない場合、"modelLoaded"はfalseで、"availableHotkeys"配列は空になります。IDが指定された場合、"modelLoaded"フィールドは、指定されたIDのモデルが現在ロードされているかどうかに応じてtrueまたはfalseになります。
"file"フィールドには、TriggerAnimation、ChangeIdleAnimation、ToggleExpression、ChangeVTSModelタイプのホットキーの式/アニメーション/モデルのファイル名が含まれます。ChangeBackgroundホットキーの場合、これにはファイル拡張子を除いた背景名が含まれます。その他のタイプについては、空の文字列が含まれます。
"description"フィールドには、ホットキーの動作内容が記述されています。プラグインが知らないホットキータイプに遭遇した場合、この文字列をプラグインUIに表示できます。これは、VTube Studioに新しく追加されたホットキータイプなどです。
"keyCombination"配列には、ホットキーをトリガーするキーボード（またはマウスのキー）の組み合わせが含まれます。すべての可能な値については、「RestrictedRawKey.cs」を参照してください。配列が空の場合、キーの組み合わせは設定されていません。重要な注意点：セキュリティ上の理由から、"keyCombination"配列は現在常に空になるため、このデータは今のところプラグインで利用できません。将来の更新で再追加される可能性があります。
"onScreenButtonID"フィールドには、ホットキーをトリガーするすべてのオンスクリーンボタンID（1（上）から8（下）または-1）が含まれます。値が-1の場合、このホットキーに対してオンスクリーンボタンが設定されていません。
すべてのホットキータイプ文字列は、「HotkeyActions.cs」ページで見つけることができます。
12:ホットキーの実行を要求する
REQUEST
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"requestID": "SomeID",
"messageType": "HotkeyTriggerRequest",
"data": {
"hotkeyID": "HotkeyNameOrUniqueIdOfHotkeyToExecute",
"itemInstanceID": "Optional_ItemInstanceIdOfLive2DItemToTriggerThisHotkeyFor"
}
}
RESPONSE
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"timestamp": 1625405710728,
"requestID": "SomeID",
"messageType": "HotkeyTriggerResponse",
"data": {
"hotkeyID": "UniqueIdOfHotkeyThatWasExecuted"
}
}
"itemInstanceID"を空にした場合、またはまったく提供しなかった場合、現在ロードされているVTube Studioモデルのホットキーをトリガーします。このフィールドにIDを指定すると、指定されたLive2Dアイテムモデルのホットキーがトリガーされます（詳細については以下を参照）。
ホットキーは、一意のIDまたはホットキー名（大文字と小文字を区別しない）でトリガーできます。同じ名前を持つ複数のホットキーがある場合、最初のものだけが実行されます（順序はUIに表示される順序です）。名前が空のホットキーはIDでしかトリガーできません。
ホットキーIDまたは名前が見つからなかった場合、またはホットキーが何らかの理由で実行できなかった場合、エラーが返される場合があります。理由には、現在モデルがロードされていないか、ホットキーのクールダウンが終了していない（特定のホットキーは5フレームごとに1回しかトリガーできない）などが含まれます。連続して異なるホットキーを送信することができ、それらがキューに入れられます。5フレームごとに、キューから1つのホットキーが取り出されて実行されます。キューには32個のホットキーが保持されます。キューがいっぱいで、それ以上のホットキーを送信しようとすると、エラーが返されます。
Live2Dアイテムでホットキーをトリガーする
このリクエストを使用して、Live2Dアイテムでホットキーをトリガーすることもできます。一般的なLive2Dアイテムについては、このページを参照してください。
これを行うには、単に"itemInstanceID"をLive2DアイテムのインスタンスIDに設定します。そのインスタンスIDを持つLive2Dアイテムが現在ロードされていない場合は、エラーが返されます。現在ロードされているすべてのアイテムのインスタンスIDを取得するには、ItemListRequestを使用できます。
13:現在の表現状態リストを要求する
現在の表情の状態（アクティブまたは非アクティブ）を、特定の表情またはすべての表情について取得することができます。"expressionFile"を含めると、その表情の状態のみが返されます。含めない場合、または空の文字列にする場合は、現在のモデルのすべての表情の状態が返されます。
ファイル名を含める場合、無効なファイル名（.exp3.jsonで終わらない）であるか、現在のモデルに存在しない場合は、エラーが返されます（「ErrorID.cs」を参照）。
"details"をtrueに設定すると、応答にいくつかの詳細が返されます（具体的には、"details"がfalseに設定されている場合、"usedInHotkeys"と"parameters"の配列が空になります）。
REQUEST
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"requestID": "SomeID",
"messageType": "ExpressionStateRequest",
"data": {
"details": true,
"expressionFile": "myExpression_optional_1.exp3.json",
}
}
モデルがロードされていない場合、表情の配列は空になります。それ以外の場合、現在ロードされているモデルで利用可能な表情に関する情報が含まれます。
"file"フィールドは、モデルフォルダに保存されている表情のファイル名です。"name"は、.exp3.json拡張子を除いた同じものです。"active"は、表情が現在アクティブかどうかを示します。
表情がホットキーを使用してアクティブ化された場合、"deactivateWhenKeyIsLetGo"と"autoDeactivateAfterSeconds"は、これらのオプションが表情ホットキーに対してアクティブ化されたかどうかを示します。"autoDeactivateAfterSeconds"がtrueの場合、"secondsRemaining"に自動的に非アクティブ化されるまでの残り時間が返されます（そうでない場合は0になります）。
リクエストで"details"がtrueに設定されている場合、"usedInHotkeys"配列には、この表情が使用されているすべてのホットキーのリストが含まれます。"parameters"配列には、表情で使用されるすべてのパラメータのLive2DパラメータIDとターゲット値が含まれます。
RESPONSE
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"timestamp": 1625405710728,
"requestID": "SomeID",
"messageType": "ExpressionStateResponse",
"data": {
"modelLoaded": true,
"modelName": "My Currently Loaded Model",
"modelID": "UniqueIDOfModel",
"expressions": [
{
"name": "myExpression_optional_1",
"file": "myExpression_optional_1 .exp3.json",
"active": false,
"deactivateWhenKeyIsLetGo": false,
"autoDeactivateAfterSeconds": false,
"secondsRemaining": 0,
"usedInHotkeys": [
{
"name": "Some Hotkey",
"id": "SomeUniqueIdToIdentifyHotkeyWith1"
},
{
"name": "Some other Hotkey",
"id": "SomeUniqueIdToIdentifyHotkeyWith2"
}
],
"parameters": [
{
"name": "SomeLive2DParamID",
"value": 0
}
]
}
]
}
}
14:表現の活性化・非活性化の要求
表情をアクティブ化する場合は、ホットキーを使用することをお勧めします。それ以外の場合、ユーザーがホットキーを設定していない表情をアクティブ化してしまい、非アクティブ化できなくなる可能性があります。ただし、必要に応じて直接ホットキーをアクティブ化または非アクティブ化することもできます。これを行うには、表情ファイル名と、表情をアクティブ化するか非アクティブ化するかを指定します。
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"requestID": "SomeID",
"messageType": "ExpressionActivationRequest",
"data": {
"expressionFile": "myExpression_1.exp3.json",
"active": true
}
}
リクエストが成功した場合、空の応答が返されます。ファイル名が無効な場合（.exp3.jsonで終わらない）、現在のモデルに存在しない場合、またはモデルがロードされていない場合は、エラーが返されます（"ErrorID.cs"を参照）。
RESPONSE
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"timestamp": 1625405710728,
"requestID": "SomeID",
"messageType": "ExpressionActivationResponse",
"data": { }
}
15:現行モデルのArtMeshesのリストを要求する。
APIではArtMesh Nameという用語を使用していますが、これは実際にはArtMesh IDを指します。ArtMesh IDはLive2D Cubism Editorによって強制されるため、モデルごとにユニークです。ArtMesh Tagsは、ArtMeshを選択してUserDataフィールドに書き込むことで追加できます。タグを使用する場合は、Export UserData file (userdata3.json) をチェックしてください。その後、モデルをVTube Studio Live2DModelsフォルダにコピーする際に、.userdata3.jsonファイルを含める必要があります。
"artMeshTags"配列に返されるArtMeshタグには、重複するタグは含まれません。
モデルがロードされていない場合、"modelLoaded"はfalseになり、配列は空になります。
「tags」についての注意事項：Live2D Cubism Editorの「UserData」フィールドにArtMeshにタグを追加できます。エディターでそのフィールドに任意のテキストを追加できます。VTube Studioはそのテキストをスペースと改行文字で分割します。つまり、タグテキストが「my tag」の場合、VTSでは「my」と「tag」の2つのタグになります。各ArtMeshにタグを任意の数追加できます。
REQUEST
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"requestID": "SomeID",
"messageType": "ArtMeshListRequest"
}
RESPONSE
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"timestamp": 1625405710728,
"requestID": "SomeID",
"messageType": "ArtMeshListResponse",
"data": {
"modelLoaded": true,
"numberOfArtMeshNames": 5,
"numberOfArtMeshTags": 2,
"artMeshNames": ["ArtMesh1", "ArtMesh2", "HairFront1", "HairFront2", "SomeArtMesh"],
"artMeshTags": ["my_tag", "SomeOtherTag"]
}
}
16:ティントアートメッシュをカラーで表現
指定したカラーとマッチング条件でArtMeshを着色できます。指定された条件に一致する任意のArtMeshは、指定されたカラーで着色されます。ArtMeshの色をリセットするには、白で着色します（R=G=B=A=255）。このリクエストでArtMeshを白くすることはできません。
カラー値のいずれかを指定しない場合、または範囲外の場合は、エラーが返されます。モデルがロードされていない場合にこのリクエストを送信しようとすると、エラーが返されます。
オプションで、0から1までのmixWithSceneLightingColorを指定することもできます。指定すると、この色はシーンライティングシステムの色と混合されます（詳細についてはこちらを参照）。1に設定すると、指定した色の値は、シーンライティングによって設定された値を完全に上書きします。0に設定すると、シーンライティングの色が指定した色を上書きします。その間のどこかで2つの色が混合されます。シーンライティングがオフの場合、これは何の効果もありません。mixWithSceneLightingColorを指定しない場合、デフォルトで1に設定され、指定した色がシーンライティングを完全に上書きします。
"artMeshMatcher"オブジェクトに含まれるすべての配列はオプションです。これらを含めると、ArtMesh名やタグが与えられた文字列と完全に一致するかどうか、または含まれるかどうか（"nameContains"/"tagContains"配列を使用する場合）に基づいてArtMeshを選択します。"artMeshNumber"配列を使用すると、モデル内の順序に基づいてArtMeshを選択できます。モデル全体を着色する場合は、matcher配列のいずれかを含めず、代わりに"tintAll"をtrueに設定してください。
セッションが切断されると、このセッションで着色されたすべてのArtMeshがデフォルトにリセットされます（完全に不透明な白）。複数のプラグイン/セッションがArtMeshの色を上書きする場合、最新のリクエストで設定された色になります。
マッチングは常に大文字と小文字を区別せずに実行されます。
REQUEST
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"requestID": "SomeID",
"messageType": "ColorTintRequest",
"data": {
"colorTint": {
"colorR": 255,
"colorG": 150,
"colorB": 0,
"colorA": 255,
"mixWithSceneLightingColor": 1
},
"artMeshMatcher": {
"tintAll": false,
"artMeshNumber": [1, 3, 5],
"nameExact": ["eye_white_left", "eye_white_right"],
"nameContains": ["mouth"],
"tagExact": [],
"tagContains": ["MyTag"]
}
}
}
超秘密メモ："colorTint"オブジェクトに"jeb_": trueを追加すると、一致するArtMeshに対して虹のアニメーションモードがアクティブになります。
RESPONSE
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"timestamp": 1625405710728,
"requestID": "SomeID",
"messageType": "ColorTintResponse",
"data": {
"matchedArtMeshes": 3
}
}
17:シーンライティングのオーバーレイカラーを取得する
VTube Studioには、スクリーン（macOS / Windows）または特定のウィンドウ（Windowsのみ）からキャプチャされた平均色でモデルをオーバーレイする機能があります。詳細については、ドキュメントのこのページを参照してください。
APIを使用して、シーンライティングオーバーレイシステムの現在のユーザー構成と色を取得できます。
レスポンスのトップレベルには、オーバーレイがオンになっているかどうかを示すactiveフィールドがあります。itemsIncludedがtrueの場合、すべてのアイテムがライティングオーバーレイの影響を受けます。isWindowCaptureがtrueの場合、VTube Studioはウィンドウの平均色をキャプチャするように設定されています。これがfalseの場合、キャプチャは画面に設定されます。
baseBrightness（0から100まで）、colorBoost（0から100まで）、smoothing（0から60まで）は、ユーザーがUI上のスライダーを使用して選択できる3つの値です。説明については、この機能のドキュメントページを確認してください。
leftCapturePart、middleCapturePart、rightCapturePartは、キャプチャされたウィンドウまたは画面のそれぞれの部分の平均色を説明します。そのactiveフィールドは、ユーザーによって画面部分がアクティブ化されたかどうかを示します。
すべてのアクティブ化された画面部分から計算された平均色は、colorAvgフィールドで見つけることができます（R、G、Bは0から255まで）。
アートメッシュをオーバーレイするために使用される最終的な色は、colorOverlayフィールドにあります（R、G、Bは0から459まで）。値が255より大きい場合があることに注意してください。最終的な色は次のように計算されます。
colorAvg *（colorBoost / 50）+ WHITE_COLOR *（baseBrightness / 100）
これにより、R、G、Bに2 * 255のような高い値が生成される場合があります。値は、1.8 * 255 = 459でキャップされます。
ライティングオーバーレイシステムがオフになっている場合、トップペイロードレベルでアクティブがfalseになり、すべての色が白に戻ります。
REQUEST
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"requestID": "SomeID",
"messageType": "SceneColorOverlayInfoRequest"
}
RESPONSE
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"requestID": "SomeID",
"messageType": "SceneColorOverlayInfoResponse",
"data": {
"active": true,
"itemsIncluded": true,
"isWindowCapture": false,
"baseBrightness": 16,
"colorBoost": 35,
"smoothing": 6,
"colorOverlayR": 206,
"colorOverlayG": 150,
"colorOverlayB": 153,
"colorAvgR": 237,
"colorAvgG": 157,
"colorAvgB": 162,
"leftCapturePart": {
"active": true,
"colorR": 243,
"colorG": 231,
"colorB": 234
},
"middleCapturePart": {
"active": true,
"colorR": 230,
"colorG": 83,
"colorB": 89
},
"rightCapturePart": {
"active": false,
"colorR": 235,
"colorG": 95,
"colorB": 101
}
}
}
18:顔がトラッカーに見つかっているかどうかのチェック
現在アクティブなトラッカー（ネットワーク/USBを介したスマートフォンまたはWebカメラトラッカー）によって、顔が現在検出されているかどうかを返します。
REQUEST
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"requestID": "SomeID",
"messageType": "FaceFoundRequest"
}
RESPONSE
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"timestamp": 1625405710728,
"requestID": "SomeID",
"messageType": "FaceFoundResponse",
"data": {
"found": true
}
}
19:使用可能なトラッキングパラメーターのリストを要求する
現在VTube Studioで利用可能なパラメーターのリストをリクエストできます。これには、すべての通常のパラメーターとプラグインによって作成されたすべてのカスタムパラメーターが含まれます。プラグインによって作成されたパラメーターは、VTube Studioのパラメーターリストから選択するときに、それがどのプラグインによって作成されたかを示します。プラグイン名も表示されます。
重要: これは多くのデータを返す可能性があります。遅いPCでパフォーマンスの問題が発生する可能性があるため、高い頻度（60 FPS以上）でこのリクエストを送信することはお勧めできません。
REQUEST
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"requestID": "SomeID",
"messageType": "InputParameterListRequest"
}
RESPONSE
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"timestamp": 1625405710728,
"requestID": "SomeID",
"messageType": "InputParameterListResponse",
"data": {
"modelLoaded": true,
"modelName": "My Currently Loaded Model",
"modelID": "UniqueIDOfModel",
"customParameters": [
{
"name": "MyCustomParamName1",
"addedBy": "My Plugin Name",
"value": 12.4,
"min": -30,
"max": 30,
"defaultValue": 0
},
{
"name": "MyCustomParamName2",
"addedBy": "My Plugin Name",
"value": 0.833,
"min": -10,
"max": 10,
"defaultValue": 0
},
{
"name": "MyCustomParamName3",
"addedBy": "My Other Plugin Name",
"value": 0,
"min": 0,
"max": 1,
"defaultValue": 0
}
],
"defaultParameters": [
{
"name": "FaceAngleX",
"addedBy": "VTube Studio",
"value": 45.78,
"min": -30,
"max": 30,
"defaultValue": 0
},
{
"name": "FacePositionX",
"addedBy": "VTube Studio",
"value": 8.33,
"min": -10,
"max": 10,
"defaultValue": 0
}
]
}
}
注：このペイロード例では、"defaultParameters"配列は不完全なものです。これには、VTube Studioが提供するすべてのデフォルトの顔/マウス/その他のトラッキングパラメータが含まれます。
20:特定の1つのパラメータ（デフォルトまたはカスタム）の値を取得します。
要求された入力パラメータが存在しない場合、エラーが返されます。
REQUEST
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"requestID": "SomeID",
"messageType": "ParameterValueRequest",
"data": {
"name": "MyCustomParamName1"
}
}
RESPONSE
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"timestamp": 1625405710728,
"requestID": "SomeID",
"messageType": "ParameterValueResponse",
"data": {
"name": "MyCustomParamName1",
"addedBy": "My Plugin Name",
"value": 12.4,
"min": -30,
"max": 30,
"defaultValue": 0
}
}
21:現在のモデルにおけるすべてのLive2Dパラメータの値を取得する
現在のモデルのすべてのLive2Dパラメーターの値を取得できます。モデルが読み込まれていない場合は、エラーが返されます。
REQUEST
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"requestID": "SomeID",
"messageType": "Live2DParameterListRequest"
}
RESPONSE
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"timestamp": 1625405710728,
"requestID": "SomeID",
"messageType": "Live2DParameterListResponse",
"data": {
"modelLoaded": true,
"modelName": "My Currently Loaded Model",
"modelID": "UniqueIDOfModel",
"parameters": [
{
"name": "MyLive2DParameterID1",
"value": 12.4,
"min": -30,
"max": 30,
"defaultValue": 0
},
{
"name": "MyLive2DParameterID2",
"value": 0,
"min": 0,
"max": 1,
"defaultValue": 0
}
]
}
}
モデルが読み込まれていない場合、"modelLoaded"はfalseになり、パラメーター配列は空になります。すべてのその他のフィールドは空の文字列になります。
22:新しいトラッキングパラメータ（「カスタムパラメータ」）を追加する。
あなたはまた、独自の新しいトラッキングパラメータを追加し、VTube Studioモデルで使用することができます。これらは「カスタム」パラメータと呼ばれます。あなたのプラグインによって追加された後、ユーザーはあなたのパラメータをLive2Dパラメータマッピングの入力として選択することができます。
パラメータ名はユニークでアルファベット数字のみで構成され、スペースは使用できず、4文字から32文字の長さでなければなりません。新しいトラッキングパラメータは次のように作成されます：
REQUEST
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"requestID": "SomeID",
"messageType": "ParameterCreationRequest",
"data": {
"parameterName": "MyNewParamName",
"explanation": "This is my new parameter.",
"min": -50,
"max": 50,
"defaultValue": 10
}
}
RESPONSE
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"timestamp": 1625405710728,
"requestID": "SomeID",
"messageType": "ParameterCreationResponse",
"data": {
"parameterName": "MyNewParamName"
}
}
このリクエストは、パラメータ名が無効な場合や、別のプラグインによって作成された同じ名前のパラメータが既に存在する場合は失敗し、エラーが返されます。同じプラグイン名で複数回パラメータを作成すると、リクエストは成功します。この方法で最小値、最大値、デフォルト値を上書きすることもできます。
最小値/最大値/デフォルト値は、-1000000から1000000の範囲内の浮動小数点数である必要があります。最小値/最大値は、実際にパラメータで許容される最小値/最大値ではありません。これらは、このパラメータを使用して新しいパラメータマッピングが作成されるときに、デフォルトの下限値と上限値として使用されます。
説明は、オプションで、パラメータが何を行い、ユーザーがモデルでどのように使用するかを説明する、256文字未満の短い説明です。これをリクエストに含めると、ユーザーがこのカスタムパラメータの詳細を表示するときに表示されます。
VTS全体でのカスタムパラメータの上限は300個で、1つのプラグインで作成できるカスタムパラメータの上限は100個です。これ以上作成しようとすると、エラーが返されます。
作成したカスタムパラメータは、VTube Studioの設定に含まれ、VTube Studio StreamingAssetsフォルダにあるConfigフォルダにあるcustom_parameters.jsonというファイルに保存されます。プラグインから認証トークンを取り消すと、このプラグインが作成したすべてのカスタムパラメータも削除されます。これらのパラメータは、使用したVTube Studioモデルに設定されたままですが、存在しない入力パラメータを示す赤いテキストで表示されます。プラグインはいつでもトークンを取得してこれらのパラメータを再作成し、引き続き使用できます。
23:カスタムパラメータを削除する
カスタムパラメーターを削除することができます。デフォルトのパラメーターは削除できません。また、このセッションの認証に使用したプラグイン以外のプラグインが作成したパラメータを削除することはできません。
REQUEST
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"requestID": "SomeID",
"messageType": "ParameterDeletionRequest",
"data": {
"parameterName": "MyNewParamName"
}
}
RESPONSE
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"timestamp": 1625405710728,
"requestID": "SomeID",
"messageType": "ParameterDeletionResponse",
"data": {
"parameterName": "MyNewParamName"
}
}
24:デフォルトまたはカスタムパラメーターのデータを投入する
デフォルトまたはカスタム・パラメータのデータを入力することができます。これらのトラッキング・パラメータは、ロードされたVTube StudioモデルやロードされたLive2Dアイテムの入力として使用されます。
ペイロードはこのようになります：
REQUEST
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"requestID": "SomeID",
"messageType": "InjectParameterDataRequest",
"data": {
"faceFound": false,
"mode": "set",
"parameterValues": [
{
"id": "FaceAngleX",
"value": 12.31
},
{
"id": "MyNewParamName",
"weight": 0.8,
"value": 0.7
}
]
}
}
RESPONSE
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"timestamp": 1625405710728,
"requestID": "SomeID",
"messageType": "InjectParameterDataResponse",
"data": { }
}
このリクエストは、1つまたは複数のパラメータが存在しない場合はエラーが返されます。
値は、-1000000から1000000の範囲内である必要があります。この範囲外の値はエラーが返されます。
Webカメラ、iOS、Androidのトラッキングから値が存在する場合、APIからの値はAPIを介してデータを送信する限り上書きされます。パラメータをコントロールするためにプラグインでデータを再送信する必要があります。これを行わないと、パラメータは「失われ」と見なされ、以前にコントロールしていたものに戻ります。それ以外に何もコントロールしていない場合、デフォルト値に戻ります。
オプションで「weight」パラメータを0から1の間で追加することもできます。これは、「value」をフェイストラッキングから設定された値と混合するために使用できます。たとえば、パラメータをフェイストラッキングで50％、APIで50％コントロールすることができます。ただし、1つのAPIプラグインは1つのパラメータに対して書き込むことしかできません。これを使用する1つのユースケースは、APIを介してコントロールするために、フェイストラッキングパラメータをフェードイン/アウトすることです。これにより、ジャンプせずに制御が切り替わります。パラメータのリクエストに「weight」パラメータが含まれていない場合、重みは1と見なされます。つまり、ターゲットパラメータは、プラグインが提供する値に瞬時に設定されます。
これらのパラメータは、通常のトラッキングパラメータと同様に扱われます。そのため、VTube Studioパラメータマッピングの通常の入力として選択し、UIのスライダーを使用してスムージングを適用できます。また、モデルで使用中の場合でもカスタムパラメータを削除しても問題は発生せず、いつでも再作成できます。
オプションで、「faceFound」: trueを渡すことができ、これにより、ユーザーの顔が検出されたと判断されます。これにより、「トラッキングロスト」アニメーションが再生されるタイミングを制御できます。
1つのパラメータを複数のプラグインで制御する
このリクエストは、別のプラグインが既にデフォルトまたはカスタムのパラメータを制御している場合、一般的にエラーが返されます。これは、1つのプラグインしか1つのパラメータを「設定」（上書き）できないためです。これは、このリクエストのデフォルトモードです。これは、 "mode"フィールドに値を提供しない場合または "set"と設定する場合に使用されるモードです。
代わりに、 "mode"フィールドを "add"に設定することができます。これにより、送信する値が現在のパラメータ値に追加されます。この場合、 "weight"値は使用されません。同じパラメータに対して何個のプラグインでも "add"モードを使用できます。これは、ボンク/投げるタイプのプラグインなど、他のユースケースに役立ちます。
25:現在読み込まれているVTSモデルの物理設定を取得する
ユーザーはVTube Studioで物理エフェクトの設定をカスタマイズすることができます。以下の設定を変更できます。
・基本の物理強度（モデルごと）：0（オフ）から100（最大）の整数。デフォルトは50で、これは物理エフェクトがLive2D Cubism Editorのように動作することを意味します。 ・基本風強度（モデルごと）：0（オフ）から100（最大）の整数。デフォルトは0です。 ・物理乗数（物理グループごと）：各物理グループ（Live2D Cubismで設定できます）ごとに、ユーザーは乗数を設定できます。対応する物理グループの処理時に、基本の物理値はこの値で乗算されます。0から2までの小数で、デフォルトは1で、基本値は変更されません。 ・風乗数（物理グループごと）：各物理グループ（Live2D Cubismで設定できます）ごとに、ユーザーは乗数を設定できます。対応する物理グループの処理時に、基本の風値はこの値で乗算されます。0から2までの小数で、デフォルトは1で、基本値は変更されません。
これらのユーザーによって設定された値はAPIで読み取ることができ、一時的に上書きすることもできます（SetCurrentModelPhysicsRequestを参照）。
現在ロードされているモデルの値を読み取るには、次の要求を使用します。
REQUEST
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"requestID": "SomeID",
"messageType": "GetCurrentModelPhysicsRequest"
}
RESPONSE
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"timestamp": 1625405710728,
"requestID": "SomeID",
"messageType": "GetCurrentModelPhysicsResponse",
"data": {
"modelLoaded": true,
"modelName": "My Currently Loaded Model",
"modelID": "UniqueIDOfModel",
"modelHasPhysics": true,
"physicsSwitchedOn": true,
"usingLegacyPhysics": false,
"physicsFPSSetting": -1,
"baseStrength": 50,
"baseWind": 17,
"apiPhysicsOverrideActive": false,
"apiPhysicsOverridePluginName": "",
"physicsGroups": [
{
"groupID": "PhysicsSetting1",
"groupName": "Hair Front Physics",
"strengthMultiplier": 1.5,
"windMultiplier": 0.3
},
{
"groupID": "PhysicsSetting2",
"groupName": "Clothes Physics",
"strengthMultiplier": 1,
"windMultiplier": 2
}
]
}
}
もしモデルがロードされていない場合、modelLoadedはfalseになります。その場合、他のすべての値は意味を持ちませんし、physicsGroups配列は空になります。
モデルがロードされている場合、modelHasPhysicsフィールドは、モデルに有効な物理エフェクトが設定されているかどうかを示します。一部のモデルは物理エフェクトが設定されていないか、壊れた物理ファイルを持っているため、物理システムが正しく起動しないことがあります。physicsSwitchedOnは、ユーザーがVTube Studioでこのモデルの「物理エフェクトを使用する」トグルをオンにした場合にtrueになります。usingLegacyPhysicsはLegacy Physicsトグルの状態です。
physicsFPSSettingには、このモデルの物理FPS設定が含まれており、30、60、120、または-1のいずれかで、-1はユーザーが「アプリと同じFPSを使用する」を選択したことを示します。
apiPhysicsOverrideActiveとapiPhysicsOverridePluginNameフィールドは、プラグインが現在いくつかの物理設定をオーバーライドしているかどうかを示します。activeフィールドがtrueの場合、nameフィールドにはプラグインの名前が含まれます。一度に物理システムを制御できるプラグインは1つだけです。これは、SetCurrentModelPhysicsRequest要求の一部として説明されます。
SetCurrentModelPhysicsRequestを使用して、物理または風のベース値または乗数をオーバーライドする場合、これらの変更はこのGetリクエストに反映されません。自分で物理オーバーライドを覚えておく必要があります。
physicsGroup配列についての注記：すべてのグループにはIDがありますが、すべてのグループが名前を持つ必要はありません。その場合、対応するgroupNameフィールドは空の文字列になります。
26:現在ロードされているVTSモデルの物理設定をオーバーライドする。
現在ロードされているモデルの物理設定をオーバーライドするには、このリクエストを使用します。このAPIを介して1つのプラグインが物理システムの制御を取得すると、他のプラグインは最初のプラグインが制御を放棄するまで、このAPIを使用することはできません。そうしようとすると、対応するエラー（SetCurrentModelPhysicsRequestPhysicsControlledByOtherPluginを参照）が返されます。また、モデルがロードされていない場合、提供された物理グループIDのいずれかが現在のモデルに存在しない場合、またはオーバーライドに値が追加されていない場合、エラーが返されます。
ユーザーが現在ロードされているモデルの物理エフェクトをオフにした場合、このAPIを使用して物理エフェクトをオンにすることはできません。物理/風のベース値と乗数をオーバーライドするためにのみ、このAPIを使用できます。
上記のGetCurrentModelPhysicsRequestセクションで説明したように、物理/風の乗数の値は0から2の間で、物理/風の基本値の値は0から100の間の整数である必要があります（これはアプリでユーザーに表示される方法でもあるため）。その範囲外の値は自動的にクランプされます。
特定の物理グループの強度または風の乗数を設定する場合は、respective group IDとsetBaseValueがfalseに設定されたstrengthOverridesおよびwindOverrides配列を使用します。setBaseValueをtrueに設定すると、提供された値が特定のグループではなく、物理強度または風の基本値として設定されます。その場合、グループID（id）は空にしておくことができます。
一般的に、このAPIを使用して設定された値は、アプリでユーザーが設定した値をオーバーライドするために使用されます。これらの値は実際にはUIに表示されず、保存されません。このAPIを使用して設定されたオーバーライド値は、タイマーが時間切れになると自動的に解除されます（overrideSecondsで設定した値）。オーバーライド値を維持する場合は、このリクエストを繰り返し送信する必要があります。
すべてのタイマーが切れると、APIはあなたのプラグインが物理システムを制御しているとは見なさなくなるので、別のプラグインが物理システムの制御を始めることができます。
オーバーライドタイマーの値は、0.5秒から5秒の間である必要があります。その範囲外の値は、自動的にクランプされます。
REQUEST
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"requestID": "SomeID",
"messageType": "SetCurrentModelPhysicsRequest",
"data": {
"strengthOverrides": [
{
"id": "PhysicsSetting1",
"value": 1.5,
"setBaseValue": false,
"overrideSeconds": 2
}
],
"windOverrides": [
{
"id": "",
"value": 85,
"setBaseValue": true,
"overrideSeconds": 5
}
]
}
}
RESPONSE
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"timestamp": 1625405710728,
"requestID": "SomeID",
"messageType": "SetCurrentModelPhysicsResponse",
"data": { }
}
27:NDIの設定を取得・設定する
NDIの設定をリクエストし、APIを介して変更することができます。これにより、NDIのオン/オフ、カスタム固定解像度の設定などが可能になります。
NDIに関する情報や、VTube Studioでの使用方法については、このページを参照してください：https://github.com/DenchiSoft/VTubeStudio/wiki/Streaming-to-Mac-PC
「setNewConfig」をfalseに設定すると、現在の設定のみを返します。その場合、他のすべてのフィールドは無視されます。trueに設定すると、指定された設定が有効であれば、その設定が設定されます。
「ndiActive」は、NDIをオン/オフにします。NDIがオンの場合、「useNDI5」はNDI 4の代わりにNDI 5を使用します（NDI 5の使用を推奨します）。
「useCustomResolution」をtrueに設定すると、NDIストリームはVTube Studioウィンドウと同じ解像度を持たなくなり、代わりにUIで設定したカスタム解像度を使用します。「customWidthNDI」と「customHeightNDI」フィールドを使用して、APIを介してこの解像度も変更できます。両方の値は256から8192の間でなければなりません。幅は16の倍数で、高さは8の倍数である必要があります。リクエストで両方の値を-1に設定すると、値の設定をスキップしてブール値フィールドのみを設定することができます。これにより、たとえば解像度を変更せずにNDIをオン/オフにすることができます。
NDIの解像度がウィンドウの解像度と一致しない場合、VTube Studioは自動的にビデオストリームをカットしてスケーリングします。 VTube Studioは、トップ/ボトムまたは左/右の部分を切り取ることがあっても、常にアスペクト比が正しいことを確認します。
重要：このリクエストには3秒間のクールダウン期間があります。速すぎるトリガーは、NDIConfigCooldownNotOver（「ErrorID.cs」を参照）タイプのエラーを返します。
REQUEST
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"requestID": "SomeID",
"messageType": "NDIConfigRequest",
"data": {
"setNewConfig": true,
"ndiActive": true,
"useNDI5": true,
"useCustomResolution": true,
"customWidthNDI": 1024,
"customHeightNDI": 512
}
}
レスポンスには、現在の設定（新しいコンフィグを設定するようリクエストした場合は新しい設定）が含まれるだけです。setNewConfig "フィールドは、レスポンスの中で何の意味も持ちません。
RESPONSE
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"timestamp": 1625405710728,
"requestID": "SomeID",
"messageType": "NDIConfigResponse",
"data": {
"setNewConfig": true,
"ndiActive": true,
"useNDI5": true,
"useCustomResolution": true,
"customWidthNDI": 1024,
"customHeightNDI": 512
}
}
28.使用可能なアイテムやシーン内のアイテムのリストを要求する。
アイテムのリストをリクエストすることができます。現在シーンに存在しているアイテムのリストを取得することができます。また、Live2Dアイテム、アニメーションフォルダなどのPCに存在するアイテムファイルのリストも取得できます。
現在アイテムをロードできる注文スポットを知りたい場合は、「includeAvailableSpots」をtrueに設定してください。そうでない場合、レスポンスの「availableSpots」配列は空になります。
現在シーンにロードされているアイテムを知りたい場合は、「includeItemInstancesInScene」をtrueに設定してください。そうでない場合、レスポンスの「itemInstancesInScene」配列は空になります。
ロード可能なアイテムファイルを知りたい場合は、「includeAvailableItemFiles」をtrueに設定してください。そうでない場合、レスポンスの「availableItemFiles」配列は空になります。重要：これはユーザーPCからアイテムファイルの完全なリストを読み取ります。これにより、アプリが一時的に遅くなる場合があるため、「includeAvailableItemFiles」をtrueに設定してこのリクエストを頻繁に使用しないでください。アイテムファイルのリストを更新する必要がある場合にのみ使用してください。それ以外の場合はfalseに設定してください。
特定のアイテムのみをフィルタリングする場合
特定のアイテムインスタンスIDまたは特定のファイル名を持つアイテムのみを含めたい場合は、「onlyItemsWithInstanceID」と「onlyItemsWithFileName」フィールドにそれぞれ指定することができます。
同じインスタンスIDを持つアイテムは常に最大で1つだけ存在しますが、同じファイル名を持つ多くのアイテムが存在する可能性があるため、その場合は多くのアイテムインスタンスを同じアイテムファイルをベースにロードできます。
また、アイテムのファイル名は一意であり、同じファイル名を持つ2つのアイテムファイルは存在しないことに注意してください。また、大文字と小文字が区別されるため、特定のファイルを参照する場合は大文字と小文字を変更しないようにしてください。
REQUEST
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"requestID": "SomeID",
"messageType": "ItemListRequest",
"data": {
"includeAvailableSpots": true,
"includeItemInstancesInScene": true,
"includeAvailableItemFiles": false,
"onlyItemsWithFileName": "OPTIONAL_my_item_filename.png",
"onlyItemsWithInstanceID": "OPTIONAL_InstanceIdOfItemInScene"
}
}
レスポンスのフィールドはほとんど自己説明的です。
ファイル名はアイテムファイルの名前です。これは、アイテムのインスタンスをシーンにロードするために使用できる名前です。JPG/PNG/GIFアイテムの場合、これはファイル名拡張子を含む完全なファイル名（パスなし）です（例：「my_item.jpg」）。アニメーションフォルダの場合、これはフォルダ名です。Live2Dアイテムの場合も、これはフォルダ名です。
アイテムの種類は「type」フィールドで見つけることができます。可能な値は、PNG、JPG、GIF、AnimationFolder、またはLive2Dです。別の可能な値はUnknownです。これは、APIが更新される前にVTube Studioに別のアイテムタイプが追加された場合にのみ発生するため、実際には起こらないはずです。
「canLoadItemsRightNow」がfalseの場合、ユーザーがVTube Studioで特定のメニューやダイアログを開いている可能性があります。これは、アイテムのロード、ホットキーの使用などのアクションを防ぐためのものです。
「framerate」と「frameCount」は、アニメーションされたアイテム（GIFおよびアニメーションフレームフォルダ）でのみ使用可能です。
「pinnedToModel」がtrueの場合、「pinnedModelID」にはアイテムが固定されているモデルのIDが含まれ、「pinnedArtMeshID」にはアイテムが固定されているArtMeshのIDが含まれます。
「includeAvailableItemFiles」をtrueに設定すると、「availableItemFiles」にはユーザーのアイテムフォルダにあるすべてのアイテムファイルのリストが含まれます。ここで返されるファイル名を使用して、ItemLoadRequestを使用してアイテムをシーンにロードすることができます。
RESPONSE
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"timestamp": 1625405710728,
"messageType": "ItemListResponse",
"requestID": "SomeID",
"data": {
"itemsInSceneCount": 2,
"totalItemsAllowedCount": 60,
"canLoadItemsRightNow": true,
"availableSpots":
[
-30,-29,-28,-27,-26,-25,-24,-23,-22,-21,-20,-19,-18,-17,-16,-15,-14,
-13,-12,-11,-10,-9,-8,-7,-6,-5,-4,-3,-2,-1,3,4,5,6,7,8,9,10,11,12,13,
14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30
],
"itemInstancesInScene": [
{
"fileName": "Ribbon (@denchisoft)",
"instanceID": "18de53dc47154b00afdd382a6ebd2194",
"order": 1,
"type": "Live2D",
"censored": false,
"flipped": false,
"locked": false,
"smoothing": 0.0,
"framerate": 0.0,
"frameCount": -1,
"currentFrame": -1,
"pinnedToModel": true,
"pinnedModelID": "47c71722c5304a039b0570b60a189875",
"pinnedArtMeshID": "D_FACE_00",
"groupName": "",
"sceneName": "",
"fromWorkshop": false
},
{
"fileName": "akari_fly (@walfieee)",
"instanceID": "716cddf2e12a438ab5da05bbbf8b341c",
"order": 2,
"type": "AnimationFolder",
"censored": false,
"flipped": false,
"locked": false,
"smoothing": 0.0,
"framerate": 15.0,
"frameCount": 7,
"currentFrame": 0,
"pinnedToModel": false,
"pinnedModelID": "",
"pinnedArtMeshID": "",
"groupName": "",
"sceneName": "",
"fromWorkshop": false
}
],
"availableItemFiles": [
{
"fileName": "Ribbon (@denchisoft)",
"type": "Live2D",
"loadedCount": 1
},
{
"fileName": "ANIM_headpat",
"type": "AnimationFolder",
"loadedCount": 0
},
{
"fileName": "workshop_2801215328_ANIM_loading gif",
"type": "AnimationFolder",
"loadedCount": 0
},
{
"fileName": "akari_fly (@walfieee)",
"type": "AnimationFolder",
"loadedCount": 1
},
{
"fileName": "b_woozy (@denchisoft).png",
"type": "PNG",
"loadedCount": 0
}
]
}
}
29.アイテムをシーンに読み込む
このリクエストを使用すると、アイテムをシーンにロードすることができます。アイテムは、ユーザーのPC上の「Items」フォルダからロードされます。
利用可能なアイテムファイルのリストを取得するには、ItemListRequestを使用します。これらの名前を「fileName」フィールドに使用できます。
アイテムは、「positionX/Y」、「size」、および「rotation」フィールドを使用して位置/スケール/回転することができます。これらの値の使用方法については、VTube Studio座標系を示す画像を参照してください。サイズについては、0から1の間でなければならず、0.32はユーザーが手動でロードした場合、アイテムが「デフォルト」のサイズになることを示します。
プラグインがアイテムをクリーンアップするようにする必要があります。ユーザーが「シーン内のすべてのアイテムを削除」ボタンを使用しなくても、アイテムを見えない場所に残すことは絶対に避けるべきです。これを簡単にするために、unloadWhenPluginDisconnectsをtrueに設定できます。
「fadeTime」フィールドを使用して、アイテムのフェードイン/アウト時間を0から2秒の間で指定できます。0に設定すると、アイテムは瞬時に表示されます。
「order」フィールドを使用して、アイテムがシーンにロードされるソート順序を指定できます。その順序が取られている場合、アイテムは自動的に次に利用可能なより高い順序にロードされ、すべての高い順序が埋まっている場合は、より低い順序をチェックします。リクエストされた順序が取られている場合、アイテムのロードを失敗させたい場合は、failIfOrderTakenをtrueに設定します。その場合、ItemOrderAlreadyTakenのタイプのエラーが返されます（ErrorsID.csを参照）。
一部の値には制限もあります。具体的には、サイズは0から1の間で、位置は-1000から1000の間でなければなりません（ただし-1/1は画面の端）、フェード時間は0から2秒の間で、スムージングは0から1の間でなければなりません。これらの制限を超えると、ItemLoadValuesInvalidのタイプのエラーが返されます。
REQUEST
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"requestID": "SomeID",
"messageType": "ItemLoadRequest",
"data": {
"fileName": "some_item_name.jpg",
"positionX": 0,
"positionY": 0.5,
"size": 0.33,
"rotation": 90,
"fadeTime": 0.5,
"order": 4,
"failIfOrderTaken": false,
"smoothing": 0,
"censored": false,
"flipped": false,
"locked": false,
"unloadWhenPluginDisconnects": true
}
}
レスポンスには、instanceID フィールドに新しく読み込まれたアイテムのインスタンス ID が格納されます。
RESPONSE
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"timestamp": 1625405710728,
"requestID": "SomeID",
"messageType": "ItemLoadResponse",
"data": {
"instanceID": "SomeUniqueItemInstanceId"
}
}
30.アイテムをシーンから削除する
このリクエストを使用すると、現在シーンにロードされているアイテムをアンロードできます。
「unloadAllInScene」をtrueに設定すると、すべてのアイテムがアンロードされます。その場合、その他のフィールドは無視されます。
「unloadAllLoadedByThisPlugin」をtrueに設定すると、このプラグインによってロードされたすべてのアイテムがアンロードされます。
特定のアイテムインスタンスまたは特定のファイル名からロードされたアイテムインスタンスを要求する場合は、オプションの「instanceIDs」と「fileNames」配列を使用できます。これらのアイテムがシーンで見つからなくても、リクエストはエラーを返しません。空の配列を含むレスポンスを返します。
ユーザーがVTSのアイテムのロード/アンロードを妨げるメニューを開いている場合、このリクエストは「CannotCurrentlyUnloadItem」というタイプのエラーを返す場合があります。
REQUEST
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"requestID": "SomeID",
"messageType": "ItemUnloadRequest",
"data": {
"unloadAllInScene": false,
"unloadAllLoadedByThisPlugin": false,
"allowUnloadingItemsLoadedByUserOrOtherPlugins": true,
"instanceIDs":
[
"SomeInstanceIdOfItemToUnload", "SomeOtherInstanceIdOfItemToUnload"
],
"fileNames":
[
"UnloadAllItemInstancesWithThisFileName", "SomeOtherFileName"
]
}
}
レスポンスには、アンロードされたアイテムのインスタンス ID とファイル名が含まれる。
RESPONSE
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"timestamp": 1625405710728,
"requestID": "SomeID",
"messageType": "ItemUnloadResponse",
"data": {
"unloadedItems":
[
{
"instanceID": "SomeInstanceId",
"fileName": "SomeFileName"
},
{
"instanceID": "SomeOtherInstanceId",
"fileName": "SomeFileName"
}
]
}
}
31.アイテムとアイテムアニメーションのコントロール
シーン内のアイテムの特定の側面を制御することができます。このリクエストを使用すると、アイテムを暗くすることができます（黒いオーバーレイ）、不透明度を変更できます。また、アニメーション付きアイテムのアニメーションを制御できます。ただし、このリクエストはLive2Dアイテムでは動作せず、試すと、ItemAnimationControlUnsupportedItemTypeエラーが返されます。これは、リアクティブPNGタイプのプラグインなどに役立ちます。
アニメーション付きアイテムでは、フレームレートを設定できます（フレーム毎秒で、自動的に0.1から120にクランプされます）。また、 "frame"フィールドを使用してアニメーションを手動で特定のフレームにジャンプさせることもできます。そのフレームインデックスが無効な場合は、エラーが返されます。たとえば、20フレームのアニメーション付きアイテムの場合、有効なフレームインデックスは0（最初のフレーム）から19（最後のフレーム）までです。アニメーション付きアイテムのフレームカウントは、ItemListRequestを使用して要求できます。通常のJPG / PNGアイテムに対してこれを試すと、ItemAnimationControlSimpleImageDoesNotSupportAnimエラーが返されます。
フレームレート、現在のフレーム、明るさ、または不透明度を変更したくない場合は、これらのフィールドに-1を渡すことができます（また、フィールドをペイロードから省略した場合、デフォルトが-1です）。
animationPlayState "フィールドを使用して、アニメーションを開始/停止することができます（true = アニメーションを再生、false = アニメーションを停止）。このフィールドは、"setAnimationPlayState "をtrueに設定した場合のみ使用され、それ以外の場合は、アニメーションの再生状態は変更されません。 オートストップフレームの使用
autoStopFrames "配列を使用して、アニメーションが自動的に再生を停止するフレームインデックスのリストを設定することができます。この配列は、"setAutoStopFrames "をtrueに設定した場合のみ使用され、それ以外の場合は自動停止フレームを変更することはありません。自動停止フレームを削除したい場合は、"setAutoStopFrames "をtrueに設定し、"autoStopFrames "に空配列を設定してください。自動停止フレームは最大1024個まで持つことができます。
アニメーションの再生がこれらのフレームの1つに達すると、再生が停止し、このリクエストを使ってAPIからアニメーションの再生状態をtrueに設定することによってのみ、再び開始することができます（上記を参照）。
REQUEST
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"requestID": "SomeID",
"messageType": "ItemAnimationControlRequest",
"data": {
"itemInstanceID": "ItemInstanceId",
"framerate": 12,
"frame": 3,
"brightness": 1,
"opacity": 1,
"setAutoStopFrames": true,
"autoStopFrames": [0, 7, 26],
"setAnimationPlayState": true,
"animationPlayState": true
}
}
応答には、現在のフレームインデックスと、アニメーションが現在再生されているかどうかが含まれます（アニメーションアイテムのみ、他のアイテムタイプではこれらのフィールドは無視されるべきです）。
RESPONSE
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"timestamp": 1625405710728,
"requestID": "SomeID",
"messageType": "ItemAnimationControlResponse",
"data": {
"frame": 3,
"animationPlaying": true
}
}
32.シーン内のアイテムを移動させる
シーン内のアイテムを移動させることができます。移動させるには、"itemsToMove "配列に移動させたいアイテムをすべて格納します。レスポンス配列（"movedItems"）には、リクエストされたアイテムごとに1つのエントリーが含まれ、移動リクエストが成功したかどうかが示されます（それぞれの "success "フィールド参照）。成功しなかった場合、"errorID "フィールドにエラーコードが格納され、何が問題だったかがわかる（ErrorsID.csを参照）。成功した場合は、successはtrue、errorIDは-1となる。
itemsToMove」配列には、最大64個の項目を指定することができます。それ以上の項目はすべて無視されます。配列に重複するアイテムIDがある場合は、そのIDの配列の最後のエントリーが使用されます。
瞬時に位置を設定したい場合（例えば毎フレーム新しい位置を設定したい場合）には、「timeInSeconds」を0に設定します。それ以外の場合は、このフィールドを使って、移動フェードに使用する時間（0〜30秒の間でクランプされます）を設定します。
アイテムのフリップ状態を設定したい場合は、"setFlip "をtrueに設定します。その後、"flip "フィールドを使用してフリップ状態を設定することができます。
アイテムの順序を変更したい場合は、"order "フィールドを使用することができます。オーダーを変更できるのは、撮影されていないスポットへのオーダーのみである（ItemListResponseを参照）。順番を変更したくない場合は、このフィールドに-1000以下を設定するか、代わりにアイテムの現在の注文値を設定することができます。また、ユーザーが何らかの設定ウィンドウを開いているときは、順序を変更することはできません。オーダーは、他のパラメータ（リクエストされた場合）のように実際にフェードアウトするのではなく、リクエストを受信すると即座にリクエストされた値に変更されます。
移動の対象を設定するフィールド（「positionX」、「positionY」、「size」、「rotation」）については、ItemLoadRequestのドキュメントを参照してください。唯一の違いは、このItemMoveRequestは、与えられた値が高すぎる/低すぎる場合にエラーを返さないということです。その代わり、各フィールドを無視したい場合は、-1000以下の値を設定することができます。その場合、このフィールドは移動に含まれず、代わりにそれぞれの現在の値が使用されます。 アイテム移動のフェードタイプ
fadeMode "フィールドを使用して、位置/回転/サイズフェードの動作タイプを設定することができます。設定可能な値は、"linear"、"easeIn"、"easeOut"、"easeBoth"、"overshoot"、"zip "です。これらは、"timeInSeconds "フィールドが0より高く設定されている場合にのみ使用されます。
移動中にアイテムをクリック／ドラッグして移動を停止させたい場合は、「userCanStop」をtrueに設定します。falseに設定すると、ユーザーは移動中にアイテムを操作することができなくなります。
以下は、移動モードの視覚的な表現です：
REQUEST
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"requestID": "SomeID",
"messageType": "ItemMoveRequest",
"data": {
"itemsToMove":
[
{
"itemInstanceID": "ItemInstanceId",
"timeInSeconds": 1,
"fadeMode": "easeOut",
"positionX": 0.2,
"positionY": -0.8,
"size": 0.6,
"rotation": 180,
"order": -1000,
"setFlip": true,
"flip": false,
"userCanStop": true
},
{
"itemInstanceID": "SomeOther_ItemInstanceId",
"timeInSeconds": 0.5,
"fadeMode": "zip",
"positionX": 1,
"positionY": 1,
"size": 0.3,
"rotation": 0,
"order": 25,
"setFlip": false,
"flip": false,
"userCanStop": false
}
]
}
}
リクエストに成功した場合、リクエストされたすべてのアイテムのステータスを含むレスポンスを受け取ることができます。
RESPONSE
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"timestamp": 1625405710728,
"requestID": "SomeID",
"messageType": "ItemMoveResponse",
"data": {
"movedItems":
[
{
"itemInstanceID": "ItemInstanceId",
"success": true,
"errorID": -1
},
{
"itemInstanceID": "SomeOther_ItemInstanceId",
"success": false,
"errorID": 900
}
]
}
}
33.ArtMeshesを選択するようユーザーに求める
このリクエストを使って、現在ロードされているメインLive2DモデルのすべてのArtMeshを含むリストをVTube Studioに表示し、ユーザーに1つまたは複数のArtMeshを選択させることができます。ユーザーがArtMeshを選択し終わると、ArtMesh IDが返されます。これらのArtMesh IDは、例えば、色合いを適用したり、不可視にしたりと、他の様々なAPIリクエストで使用することができます。
現在、モデルが読み込まれていない場合や、他のウィンドウが開いている場合、リクエストはエラーを返します。
ユーザーはArtMeshesにカーソルを合わせるとIDが表示され、クリックするとクリック位置の下にあるすべてのArtMeshesについて表示リストをフィルタリングすることができます。このリクエストによって表示されるUIは次のようになります：
requestedArtMeshCountフィールドを使用して、ユーザーがアクティブにしなければならないArtMeshの数を指定します。ちょうどその数のArtMeshがアクティブになるまで、「OK」ボタンは使用できなくなります。requestedArtMeshCountを0以下に設定すると、ユーザーは任意の数のArtMesh（ただし最低1つ）を選択するように要求されます。
リスト内のArtMeshをあらかじめアクティブにしたい場合は、activeArtMeshesリストを使用し、いくつかのArtMesh IDを渡すことができます。それらのIDのいずれかが現在のモデルに含まれていない場合、エラーが返されます。現在ロードされているモデル内のすべてのArtMeshのリストが必要な場合は、ArtMeshListRequestを使用します。
上のスクリーンショットにあるように、リストにはいくつかのデフォルトのテキストが表示され、プラグインのArtMeshesを選択するようユーザーに要求します。同じテキストは、右上の ? ボタン（ヘルプ）を押したときにポップアップで表示されます。これらの文字列は、それぞれtextOverrideとhelpOverrideフィールドを使用して上書きすることができます。これらの文字列を空（空文字列）、NULL、またはペイロードから外した場合、上に示したデフォルトのメッセージが使用されます。これらのメッセージを上書きしたい場合は、4文字以上1024文字以下の文字列を指定する必要があり、そうでない場合はデフォルトが使用されます。提供された文字列の改行にはⅮを使用することができます。
REQUEST
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"requestID": "SomeID",
"messageType": "ArtMeshSelectionRequest",
"data": {
"textOverride": "This text is shown over the ArtMesh selection list.",
"helpOverride": "This text is shown when the user presses the ? button."
"requestedArtMeshCount": 5
"activeArtMeshes": [
"D_BODY_00",
"D_ARM_R_05"
]
}
}
リクエストに成功すると、選択リストがユーザーに表示されます。即座の応答はありません。応答は、ユーザーが「OK」または「キャンセル」ボタンをクリックした後に行われます。キャンセル」ボタンは常に利用可能ですが、「OK」ボタンは、要求された量のArtMeshesが選択された場合にのみクリック可能になります。
アクティブになったアートメッシュと非アクティブになったアートメッシュは、それぞれactiveArtMeshes配列とinactiveArtMeshes配列に返されます。これらの配列の間には重複がないので、これらの配列のArtMeshesを組み合わせると、モデル内のすべてのArtMeshesのリストを持つことになります。
ユーザーが「OK」をクリックした場合、成功フィールドはtrueになります。ユーザーが「Cancel」をクリックした場合、成功フィールドはfalseになります（この場合、activeArtMeshes配列とinactiveArtMeshes配列は無視する必要がありますが、それらはまだ返されます）。
RESPONSE
{
"apiName": "VTubeStudioPublicAPI",
"apiVersion": "1.0",
"timestamp": 1625405710728,
"requestID": "SomeID",
"messageType": "ArtMeshSelectionResponse",
"data": {
"success": true
"activeArtMeshes": [
"D_BROW_00",
"D_EYE_BALL_03",
"D_EYE_BALL_02",
"D_EYE_BALL_01",
"D_EYE_BALL_00",
"D_EYE_11"
],
"inactiveArtMeshes": [
"D_EAR_06",
"D_BODY_00",
"D_ARM_R_05"
]
}
}
この記事が気に入ったらサポートをしてみませんか？