Connection Guide

This guide covers how to establish and manage connections to VTube Studio.

Establishing a Connection

The VTS class manages the WebSocket connection to VTube Studio. To connect:

from vtpy import VTS

vts = VTS(plugin_name="MyPlugin", plugin_developer="MyName")
await vts.start(host="localhost", port=8001)

Connection Parameters

The start() method accepts several parameters:

host (str): VTube Studio host address (default: “localhost”)
port (int): VTube Studio WebSocket port (default: 8001)
auth_token (Optional[str]): Authentication token for reconnection (default: None)
auth_file (Union[str, Path]): Path to the file to save/load the auth token (default: “vts_token.txt”)
save_auth_token (bool): Whether to save the auth token to disk (default: True)

Checking Connection Status

You can check if the client is connected and authenticated:

if vts.connected:
    print("Connected to VTube Studio")

if vts.authenticated:
    print("Authenticated with VTube Studio")

Closing the Connection

Always close the connection when done:

if vts.connected:
    await vts.close()

It’s recommended to use a try/finally block:

try:
    await vts.start(host="localhost", port=8001)
    # Your code here
finally:
    if vts.connected:
        await vts.close()

Reconnection

If the connection is lost, you can reconnect:

if not vts.connected:
    await vts.start(
        host="localhost",
        port=8001,
        auth_token=previous_token  # Use saved token
    )

Connection Errors

Common connection errors:

ConnectionError: VTube Studio is not running or WebSocket API is disabled
ValueError: Authentication failed or was rejected
TimeoutError: Connection timeout

Handle these appropriately:

try:
    await vts.start(host="localhost", port=8001)
except ConnectionError as e:
    print("Could not connect to VTube Studio")
    print("Make sure VTube Studio is running and API is enabled")
except ValueError as e:
    print("Authentication failed")
    print("Approve the request in VTube Studio")