Integration

VTube Studio

Control your VTuber avatar in VTube Studio with expressions, hotkeys, model loading, and parameter manipulation.

Overview

FaustBot connects to VTube Studio via its API to provide full avatar control:

Expressions

Trigger facial expressions and emotions.

Hotkeys

Activate VTS hotkeys remotely.

Model Control

Load and switch between models.

Parameters

Modify Live2D parameters directly.

Items

Load and position prop items.

Movement

Control model position and rotation.

Setup

Connect to VTube Studio

Enable the VTube Studio API and connect FaustBot to control your avatar.

1

Enable VTube Studio API

In VTube Studio, go to Settings → Start API. Note the Port (default: 8001) and optionally set an IP if connecting remotely.

2

Configure FaustBot

In FaustBot, go to Integrations → VTube Studio. Enter the host (usually localhost) and port (8001).

Screenshot: VTube Studio settings
3

Authorize Connection

Click Connect. VTube Studio will show a popup asking to authorize FaustBot. Click Allow to grant access.

4

Test the Connection

The status should show Connected. Try triggering a hotkey or expression to verify everything works.

Auto-Reconnect

Enable Auto-Reconnect to automatically reconnect if VTube Studio restarts. FaustBot will retry the connection periodically.

Triggers

Respond to VTube Studio events:

Model Loaded A new model was loaded
Hotkey Triggered A hotkey was activated in VTS
Tracking Started Face tracking began
Tracking Lost Face tracking was lost

Trigger Variables

These variables are available in your actions:

%vtsModelId% Current model's unique ID
%vtsModelName% Current model's display name
%vtsHotkeyId% Triggered hotkey ID
%vtsHotkeyName% Triggered hotkey name

Effects

Hotkeys & Expressions

Trigger Hotkey

Activate a VTS hotkey by name or ID.

Set Expression

Activate or deactivate an expression.

Play Animation

Trigger an animation sequence.

Model Control

Load Model

Switch to a different model.

Move Model

Change model position on screen.

Rotate Model

Adjust model rotation.

Scale Model

Change model size.

Parameters

Set Parameter

Set a Live2D parameter value.

Get Parameter

Read current parameter value.

Create Parameter

Add a custom parameter.

Delete Parameter

Remove a custom parameter.

Items

Load Item

Load a prop or accessory.

Unload Item

Remove an item from scene.

Move Item

Position an item.

Pin Item

Attach item to model point.

Scripting API

Control VTube Studio from your scripts:

Hotkeys & Expressions

Trigger hotkeys and expressions 
# Trigger a hotkey by name
CPH.VTSTriggerHotkey("Happy")

# Trigger by ID
CPH.VTSTriggerHotkeyById("HotkeyID123")

# Get available hotkeys
hotkeys = CPH.VTSGetHotkeys()
for hk in hotkeys:
    CPH.LogInfo(f"Hotkey: {hk['name']} ({hk['id']})")

# Set expression state
CPH.VTSSetExpression("Angry", True)  # Activate
CPH.VTSSetExpression("Angry", False)  # Deactivate

Model Control

Control model loading and positioning 
# Get current model info
model = CPH.VTSGetCurrentModel()
CPH.LogInfo(f"Current model: {model['name']}")

# Load a different model
CPH.VTSLoadModel("ModelID123")
# or by name
CPH.VTSLoadModelByName("My Cute Avatar")

# Move model (x, y in screen coordinates, -1 to 1)
CPH.VTSMoveModel(0.5, 0.0)  # Move to right side

# Rotate model (degrees)
CPH.VTSRotateModel(15)

# Scale model (0.1 to 2.0)
CPH.VTSScaleModel(1.2)

Parameter Control

Manage Live2D parameters 
# Get parameter value
value = CPH.VTSGetParameter("MouthOpen")
CPH.LogInfo(f"Mouth open: {value}")

# Set parameter value
CPH.VTSSetParameter("EyeOpenLeft", 0.5)
CPH.VTSSetParameter("EyeOpenRight", 0.5)

# Create custom parameter
CPH.VTSCreateParameter("MyCustomParam", min=0, max=100, default=50)

# Set custom parameter
CPH.VTSSetParameter("MyCustomParam", 75)

# Delete custom parameter
CPH.VTSDeleteParameter("MyCustomParam")

Items

Load and manage items 
# Load an item
item_id = CPH.VTSLoadItem("crown.png", x=0, y=0.5, size=0.3)

# Pin item to model (attach to head)
CPH.VTSPinItem(item_id, "HeadTop")

# Move item
CPH.VTSMoveItem(item_id, x=0.1, y=0.6)

# Unload item
CPH.VTSUnloadItem(item_id)

# Unload all items
CPH.VTSUnloadAllItems()

Chat-Triggered Expressions

React to chat with expressions 
# React to chat commands with expressions
message = CPH.GetArg("message").lower()

expressions = {
    "happy": "HappyExpression",
    "sad": "SadExpression",
    "angry": "AngryExpression",
    "surprised": "SurprisedExpression"
}

for keyword, expression in expressions.items():
    if keyword in message:
        CPH.VTSSetExpression(expression, True)
        CPH.Wait(3000)
        CPH.VTSSetExpression(expression, False)
        break

See the full API reference for all available VTube Studio methods.