Getting Started

This guide will help you get started with vtube-python (vtpy). You’ll learn how to install the library, establish a connection to VTube Studio, and perform basic operations.

Installation

Install from PyPI

pip install vtube-python

Install from Repository

To install directly from the repository:

# Clone the repository
git clone https://github.com/limitcantcode/vtube-python.git
cd vtube-python

# Install in development mode
pip install -e .

# Or install normally
pip install .

For development with all optional dependencies:

pip install -e ".[dev]"

Prerequisites

Before using vtpy, make sure you have:

  1. VTube Studio installed and running

  2. WebSocket API enabled in VTube Studio settings

  3. Python 3.8+ installed

To enable the WebSocket API in VTube Studio:

  1. Open VTube Studio

  2. Go to Settings → API

  3. Enable “Enable API Server”

  4. Note the port (default is 8001)

Basic Connection

The first step is to create a VTS client and connect to VTube Studio:

import asyncio
from vtpy import VTS

async def main():
    # Initialize VTS client
    vts = VTS(plugin_name="MyPlugin", plugin_developer="MyName")

    try:
        # Connect to VTube Studio
        auth_token = await vts.start(
            host="localhost",
            port=8001,
            save_auth_token=False
        )
        print(f"Connected! Auth token: {auth_token[:20]}...")

    except ConnectionError as e:
        print(f"Connection error: {e}")
    finally:
        if vts.connected:
            await vts.close()

asyncio.run(main())

Authentication

VTube Studio requires authentication for API access. The start() method handles this automatically:

  • If you don’t have an auth token, it will request one from VTube Studio

  • You’ll need to approve the authentication request in VTube Studio

  • The token can be saved for future use (set save_auth_token=True)

# First time - request authentication
auth_token = await vts.start(
    host="localhost",
    port=8001,
    save_auth_token=True  # Save token for next time
    auth_file="vts_token.txt"  # Save location of existing or new token
)

# Subsequent connections - use in-memory token
auth_token = await vts.start(
    host="localhost",
    port=8001,
    auth_token=auth_token
)

# Subsequent connections - use saved token
auth_token = await vts.start(
    host="localhost",
    port=8001,
    auth_file="vts_token.txt"
)

Making Requests

Once connected, you can make API requests. Here’s an example of getting VTube Studio statistics:

from vtpy.data.requests import StatisticsRequestData

# Request statistics
stats_response = await vts.request_statistics(StatisticsRequestData())
stats = stats_response.data

print(f"Version: {stats.vTubeStudioVersion}")
print(f"Framerate: {stats.framerate} FPS")
print(f"Uptime: {stats.uptime} seconds")

Handling Events

vtpy supports event-driven programming. You can subscribe to VTube Studio events:

from vtpy.data.events import (
    EventType,
    ModelMovedEvent,
    ModelMovedEventSubscriptionRequestData,
    ModelMovedEventSubscriptionRequestConfig,
)

# Define event handler
async def on_model_moved(event: ModelMovedEvent) -> None:
    print(f"Model moved: {event.data.modelName}")

# Register handler
vts.on_event(EventType.ModelMovedEvent, on_model_moved)

# Subscribe to events
await vts.event_sub_model_moved(
    ModelMovedEventSubscriptionRequestData(
        subscribe=True,
        config=ModelMovedEventSubscriptionRequestConfig()
    )
)

Error Handling

vtpy provides specific exception types for better error handling:

from vtpy.error import VTSRequestError

try:
    await vts.request_statistics(StatisticsRequestData())
except VTSRequestError as e:
    print(f"VTube Studio error: {e.message}")
    print(f"Error ID: {e.error_id}")
except ConnectionError as e:
    print(f"Connection error: {e}")

Next Steps