vtpy Package

VTS Class

VTS class for managing WebSocket connection and API interactions with VTube Studio.

class vtpy.vts.VTS(plugin_name: str, plugin_developer: str, plugin_icon: str | None = None)[source]

Bases: object

Main class for interacting with VTube Studio via WebSocket API.

This class manages the WebSocket connection, handles authentication, and provides an event-driven interface for subscribing to VTube Studio events.

__init__(plugin_name: str, plugin_developer: str, plugin_icon: str | None = None)[source]

Initialize VTS client.

Parameters:

plugin_name – Name of your plugin
plugin_developer – Developer name
plugin_icon – Optional base64 encoded icon (not used in current implementation)

property connected: bool: Check if connected to VTube Studio.

property authenticated: bool: Check if authenticated with VTube Studio.

async start(host: str = 'localhost', port: int = 8001, auth_token: str | None = None, auth_file: str | Path = 'vts_token.txt', save_auth_token: bool = True) → str[source]

Connect to VTube Studio and authenticate.

Parameters:

host – VTube Studio WebSocket host (default: “localhost”)
port – VTube Studio WebSocket port (default: 8001)
auth_token – Authentication token as string, Path to token file, or None to request new token

Returns:

Authentication token string

Raises:

ConnectionError – If connection fails
ValueError – If authentication fails

async close() → None[source]: Close the WebSocket connection.

generate_request_id() → str[source]

Generate a unique request ID.

Returns:: A unique request ID string

on_event(event_type: EventType, handler: Callable[[BaseEvent], Awaitable[None]]) → None[source]

Register an event handler for a specific event type.

Parameters:

event_type – The type of event to listen for
handler – Async function that will be called when the event occurs. The function should accept one parameter (the event object).

remove_event_handler(event_type: EventType, handler: Callable[[BaseEvent], Awaitable[None]] | None = None) → None[source]

Remove an event handler.

Parameters:

event_type – The event type
handler – The handler function to remove

Raises:

ValueError – If handler is not registered

async event_sub_test(data: TestEventSubscriptionRequestData) → EventSubscriptionResponse[source]

async event_sub_model_loaded(data: ModelLoadedEventSubscriptionRequestData) → EventSubscriptionResponse[source]

async event_sub_tracking_status_changed(data: TrackingStatusChangedEventSubscriptionRequestData) → EventSubscriptionResponse[source]

async event_sub_background_changed(data: BackgroundChangedEventSubscriptionRequestData) → EventSubscriptionResponse[source]

async event_sub_model_config_modified(data: ModelConfigChangedEventSubscriptionRequestData) → EventSubscriptionResponse[source]

async event_sub_model_moved(data: ModelMovedEventSubscriptionRequestData) → EventSubscriptionResponse[source]

async event_sub_model_outline(data: ModelOutlineEventSubscriptionRequestData) → EventSubscriptionResponse[source]

async event_sub_hotkey_triggered(data: HotkeyTriggeredEventSubscriptionRequestData) → EventSubscriptionResponse[source]

async event_sub_model_animation(data: ModelAnimationEventSubscriptionRequestData) → EventSubscriptionResponse[source]

async event_sub_item(data: ItemEventSubscriptionRequestData) → EventSubscriptionResponse[source]

async event_sub_model_clicked(data: ModelClickedEventSubscriptionRequestData) → EventSubscriptionResponse[source]

async event_sub_post_processing(data: PostProcessingEventSubscriptionRequestData) → EventSubscriptionResponse[source]

async event_sub_live2d_cubism_editor_connected(data: Live2DCubismEditorConnectedEventSubscriptionRequestData) → EventSubscriptionResponse[source]

async request_permission(permission: PermissionRequestData) → PermissionResponse[source]

async request_authentication(data: AuthenticationRequestData) → AuthenticationResponse[source]

async request_authentication_token(data: AuthenticationTokenRequestData) → AuthenticationTokenResponse[source]

async request_statistics(data: StatisticsRequestData) → StatisticsResponse[source]

async request_vts_folder_info(data: VTSFolderInfoRequestData) → VTSFolderInfoResponse[source]

async request_current_model(data: CurrentModelRequestData) → CurrentModelResponse[source]

async request_available_models(data: AvailableModelsRequestData) → AvailableModelsResponse[source]

async request_model_load(data: ModelLoadRequestData) → ModelLoadResponse[source]

async request_move_model(data: MoveModelRequestData) → MoveModelResponse[source]

async request_hotkeys_in_current_model(data: HotkeysInCurrentModelRequestData) → HotkeysInCurrentModelResponse[source]

async request_hotkey_trigger(data: HotkeyTriggerRequestData) → HotkeyTriggerResponse[source]

async request_expression_state(data: ExpressionStateRequestData) → ExpressionStateResponse[source]

async request_expression_activation(data: ExpressionActivationRequestData) → ExpressionActivationResponse[source]

async request_art_mesh_list(data: ArtMeshListRequestData) → ArtMeshListResponse[source]

async request_color_tint(data: ColorTintRequestData) → ColorTintResponse[source]

async request_scene_color_overlay_info(data: SceneColorOverlayInfoRequestData) → SceneColorOverlayInfoResponse[source]

async request_face_found(data: FaceFoundRequestData) → FaceFoundResponse[source]

async request_input_parameter_list(data: InputParameterListRequestData) → InputParameterListResponse[source]

async request_parameter_value(data: ParameterValueRequestData) → ParameterValueResponse[source]

async request_live2d_parameter_list(data: Live2DParameterListRequestData) → Live2DParameterListResponse[source]

async request_parameter_creation(data: ParameterCreationRequestData) → ParameterCreationResponse[source]

async request_parameter_deletion(data: ParameterDeletionRequestData) → ParameterDeletionResponse[source]

async request_inject_parameter_data(data: InjectParameterDataRequestData) → InjectParameterDataResponse[source]

async request_get_current_model_physics(data: GetCurrentModelPhysicsRequestData) → GetCurrentModelPhysicsResponse[source]

async request_set_current_model_physics(data: SetCurrentModelPhysicsRequestData) → SetCurrentModelPhysicsResponse[source]

async request_ndi_config(data: NDIConfigRequestData) → NDIConfigResponse[source]

async request_item_list(data: ItemListRequestData) → ItemListResponse[source]

async request_item_load(data: ItemLoadRequestData) → ItemLoadResponse[source]

async request_item_unload(data: ItemUnloadRequestData) → ItemUnloadResponse[source]

async request_item_animation_control(data: ItemAnimationControlRequestData) → ItemAnimationControlResponse[source]

async request_item_move(data: ItemMoveRequestData) → ItemMoveResponse[source]

async request_item_sort(data: ItemSortRequestData) → ItemSortResponse[source]

async request_art_mesh_selection(data: ArtMeshSelectionRequestData) → ArtMeshSelectionResponse[source]

async request_item_pin(data: ItemPinRequestData) → ItemPinResponse[source]

async request_post_processing_list(data: PostProcessingListRequestData) → PostProcessingListResponse[source]

async request_post_processing_update(data: PostProcessingUpdateRequestData) → PostProcessingUpdateResponse[source]