API reference

API reference#

pyvts.vts#

class pyvts.vts(plugin_info={'authentication_token_path': './pyvts_token.txt', 'developer': 'genteki', 'plugin_icon': None, 'plugin_name': 'pyvts'}, vts_api_info={'host': 'localhost', 'name': 'VTubeStudioPublicAPI', 'port': 8001, 'version': '1.0'}, **kwargs)#

Bases: object

VtubeStudio API Connector

Parameters:

  • plugin_info (dict of {"plugin_name", "developer", "plugin_icon", "authentication_token_path"}) -- Information about your plugin.

  • vts_api_info (dict of {"version", "name", "port"}) -- Information about VTubeStudio API.

  • **kwarg -- In case you just want to change serveral of the plugin/api Args, input your data here

Examples

Using Args

>>> info = {"plugin_name": "a","developer": "b",
...         "authentication_token_path": "./token.txt"}
>>> pyvts.vts(plugin_info=info)

Using **kwarg

>>> pyvts.vts(plugin_name="a", developer="b")
async close()#

Close connection

Return type:

None

async connect()#

Connect to VtubeStudio API server

Return type:

None

async event_subscribe(msg)#

subscribe event from vts api

Return type:

dict

Parameters:

msg (dict) -- Event subscription message generated from method of VTSRequest

Returns:

Message returned from VTube Studio API

get_authentic_status()#

Get authentic status

Return type:

int

Returns:

Authentic status, 0 - no authen & token, 1 - has token, 2 - authen, -1 - wrong token

get_connection_status()#

Get connection status

Return type:

int

Returns:

Connection status, 0: not connected, 1: connected

load_icon(icon_path)#

Load your plugin icon

Return type:

None

Parameters:

icon_path (str)

Args:#

icon_path :str

path to icon image

async read_token()#

Read authentic token from the token file wrote before

Return type:

str

Return type:

Token string

async request(request_msg)#

Send request to VTubeStudio

Return type:

dict

Parameters:

request_msg (dict) -- Message generated from VTSRequest

Returns:

Message from VTubeStudio API, data is stored in return_dict["data"]

Return type:

response_dict

Examples

>>> recv_msg = await myvts.request(send_msg)
>>> recv_data = recv_msg["data"]
async request_authenticate()#

Get authenticated from vtubestudio to have more access

Return type:

bool

Returns:

Whether the plugin has been authenticated by VTS

async request_authenticate_token(force=False)#

Get authentication code from VTubeStudio

Return type:

None

async write_token()#

Write authentic token into localfile

Return type:

None

pyvts.VTSRequest#

class pyvts.VTSRequest(developer='genteki', plugin_name='pyvts', plugin_icon=None, **kwargs)#

Bases: object

VtubeStudio API Request Generator

Parameters:

  • developer (str) -- developer the your plugin

  • plugin_name (dict) -- plugin name

  • plugin_icon (str) -- plugin icon

  • **kwargs (optional) -- other parameters like api_version,

BaseRequest(message_type, data=None, request_id='SomeID')#

Standard Request

Return type:

dict

Parameters:

  • message_type (str) -- Message type of request

  • data (dict, optional) -- Relavent data sending to VTubeStudio API

  • request_id (str, optional) -- String to mark the request, not important

Returns:

Organized message sending to Vtubestudio API

ColorTintRequest(red=0, green=0, blue=0, alpha=255, jeb=False, mix_with_scene_lighting_color=1, tint_all=False, art_mesh_number=[], name_exact=[], name_contains=[], tag_exact=[], tag_contains=[])#

Alter the color of an Artmesh on the current model

Return type:

dict

Parameters:

  • red (int, optional) -- red value of tint (0-255)

  • green (int, optional) -- green value of tint (0-255)

  • blue (int, optional) -- blue value of tint (0-255)

  • alpha (int, optional) -- alpha value of tint (0-255)

  • jeb (bool, optional) -- boolean option to activate "jeb mode"(rainbow cycle) on art meshes

  • mix_with_scene_lighting_color (float, optional) -- float between 0 and 1, determines how much tint is mixed with scene lighting

  • tint_all (bool, optional) -- boolean option to tint all

  • art_mesh_number (list, optional) -- list of ints corresponding to art mesh numbers to color

  • name_exact (list, optional) -- list of strings of exact names of meshes to color

  • name_contains (list, optional) -- list of strings of partial names of meshes to color

  • tag_exact (list, optional) -- list of strings of exact tags of meshes to color

  • tag_contains (list, optional) -- list of strings of partial names of tags of meshes to color

Returns:

the organized message sending to Vtubestudio API

authentication(token)#

use auth_token to get more access

Return type:

dict

Parameters:

token (str) -- authenication token

Returns:

the organized message sending to Vtubestudio API

authentication_token()#

generate request msg to requirer authentication_token

Return type:

dict

Returns:

the organized message sending to Vtubestudio API

Examples

>>> message = myvts.vts_request.authentication_token()
>>> return_msg = await myvts.request(message)
eventSubscribtionModelMoved()#

Subscribe message of model moved/resized/rotated

Return type:

dict

Returns:

Organized subscription request message.

eventSubscription(event_name, on=True, cfg={'0': 0})#

subscribe event from vtubestudio api (base function, seldom directly used)

Return type:

dict

Parameters:

  • event_name (string) -- event name you want to substribe

  • on (bool, optional) -- turn on or turn off

  • cfg (dict, optional) -- config message

Returns:

organized message sending to Vtubestudio API

eventSubscriptionModelLoaded(modelID=[])#

Subscribe message of model loaded/unloaded Args :rtype: dict

Returns:

Organized subscription request message.

Parameters:

modelID (list)

Return type:

dict

eventSubscriptionTest(test_msg='text the event will return')#

Subscribe test event

Return type:

dict

Parameters:

test_msg (str, optional) -- Text of test message.

Returns:

Organized subscription request message.

eventSubscriptionTrackingStatusChanged()#

subscribe message of tracking lost/found

Return type:

dict

Returns:

Organized subscription request message.

eventSubsribtionModelOutline(draw=False)#

Subscribe message of model outline

Return type:

dict

Returns:

Organized subscription request message.

requestCustomParameter(parameter, min=0, max=1, default_value=0, info='')#

Add your own new tracking parameters and use them in your VTube Studio models

Return type:

dict

Parameters:

  • parameter (str) -- Name of parameter

  • min (float, optional) -- Minimum bound for the parameter

  • max (float, optional) -- Maximum bound for the parameter

  • default_value (float, optional) -- Default value of this parameter

  • info (str, optional) -- Description of this parameter

Returns:

the organized message sending to Vtubestudio API

requestDeleteCustomParameter(parameter)#

Delete custom parameter

Return type:

dict

Parameters:

parameter (str) -- Name of the parameter to delete

Returns:

organized message sending to Vtubestudio API

requestHotKeyList()#
Return type:

dict

requestMoveModel(x, y, rot=0, size=1, relative=True, move_time=0.2)#

request to move the model

Return type:

dict

Parameters:

  • x (float) -- Location of model, x

  • y (float) -- Location of model, y

  • rot (float, optional) -- Rotating angle, range [-360, 360]

  • size (float, optional) -- Zoom ratio, default: 1

  • relative (bool, optional) -- Whether the values are considered to be relative to the current model position

  • move_time (float, optional) -- Time of the move motion

Returns:

Organized message sending to Vtubestudio API

requestParameterValue(parameter)#
Return type:

dict

Parameters:

parameter (str)

requestSetMultiParameterValue(parameters, values, weight=1, face_found=False, mode='set')#

Set values for any default or custom parameters.

Return type:

dict

Parameters:

  • parameter (list[str]) -- Names of the parameters

  • value (list[float]) -- Values of the data, [-1000000, 1000000]

  • weight (float, optional) -- You can mix the your value with vts face tracking parameter, from 0 to 1,

  • face_found (bool, optional) -- if true, you will tell VTubeStudio to consider the user face as found, s.t. you can control when the "tracking lost"

  • parameters (list[str])

  • values (list[float])

Returns:

organized message sending to Vtubestudio API

requestSetParameterValue(parameter, value, weight=1, face_found=False, mode='set')#

Set value for any default or custom parameter.

Return type:

dict

Parameters:

  • parameter (str) -- Name of the parameter

  • value (float) -- Value of the data, [-1000000, 1000000]

  • weight (float, optional) -- You can mix the your value with vts face tracking parameter, from 0 to 1,

  • face_found (bool, optional) -- if true, you will tell VTubeStudio to consider the user face as found, s.t. you can control when the "tracking lost"

Returns:

organized message sending to Vtubestudio API

requestTrackingParameterList()#
Return type:

dict

requestTriggerHotKey(hotkeyID, itemInstanceID=None)#

Trigger hotkey. # TODO, handle itemInstanceID

Return type:

dict

Parameters:

  • hotkeyID (str) -- Hotkey name or unique id of hotkey to execute, can be obtained via VTSRequest.requestHotKeyList()

  • itemInstanceID (str, optional) -- Model ID of the hotkey. If left blank, it will trigger a hotkey for the currently loaded VTubeStudio model.

Returns:

Organized message sending to Vtubestudio API

Contents