vtubestudio

library3.11.0jsnpmunverified

A TypeScript implementation of the VTube Studio WebSocket API for Node.js and browser environments. Current stable version is 3.11.0. This library provides a full-featured client for controlling VTube Studio (e.g., face tracking, model manipulation, hotkeys) via its official WebSocket API. It includes automatic reconnection, authentication token persistence, and typed interfaces for all API calls. Key differentiators: platform-agnostic (works in Node and browser), zero runtime dependencies, and comprehensive type definitions shipped with the package. Release cadence is irregular but maintained by a single developer.

communication

npm install vtubestudio

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · VTUBESTUDIO

vtubestudio

communicationjavascriptv3.11.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ApiClient

✓ import { ApiClient } from 'vtubestudio';

✗ const ApiClient = require('vtubestudio');

Package is ESM-first; named import is required. CommonJS require is still supported but uses the default export, e.g., const vts = require('vtubestudio'); const { ApiClient } = vts;

IApiClientOptions

✓ import type { IApiClientOptions } from 'vtubestudio';

✗ import { IApiClientOptions } from 'vtubestudio';

Use `import type` for type-only imports to avoid runtime errors in transpiled code.

ApiClient (from CDN)

✓ import { ApiClient } from 'https://unpkg.com/vtubestudio/lib/esm/vtubestudio.min.js?module';

✗ import ApiClient from 'https://unpkg.com/vtubestudio/lib/esm/vtubestudio.min.js';

Named import is required even from CDN. The ?module parameter enables ESM module support.

Initializes an ApiClient with authentication token persistence using browser localStorage, listens for the connect event, and makes a simple API call.

import { ApiClient } from 'vtubestudio'; function setAuthToken(token: string | null) { if (token) { localStorage.setItem('VTS_AUTH_TOKEN', token); } else { localStorage.removeItem('VTS_AUTH_TOKEN'); } } function getAuthToken(): string | null { return localStorage.getItem('VTS_AUTH_TOKEN'); } const options = { authTokenGetter: getAuthToken, authTokenSetter: setAuthToken, pluginName: 'My Plugin', pluginDeveloper: 'My Name', }; const apiClient = new ApiClient(options); apiClient.on('connect', async () => { // after authentication const response = await apiClient.getCurrentModel(); console.log(response); }); // Wait for connection to establish setTimeout(async () => { if (apiClient.isConnected) { const response = await apiClient.getStatistics(); console.log(response); } }, 1000);

Debug

Known issues

gotchaAPI calls may throw errors if the client is not connected, authentication is pending, or the Plugin API is disabled. Always wrap calls in try-catch.

fix

Use try-catch around every API call, and check apiClient.isConnected before making calls.

affects: >=3.0.0

deprecatedThe method `authenticationRequired` was removed in v3.0.0. Authentication is now handled internally.

fix

Remove any calls to `authenticationRequired`. Provide authTokenGetter and authTokenSetter in client options.

affects: >=3.0.0

breakingThe event 'authentication' was renamed to 'authenticate' in v3.0.0.

fix

Change `apiClient.on('authentication', ...)` to `apiClient.on('authenticate', ...)`.

affects: >=3.0.0

gotchaThe `authToken` option in client options is deprecated; use authTokenGetter and authTokenSetter for token persistence.

fix

Replace `authToken` with getter/setter functions.

affects: >=3.0.0 <4.0.0

breakingIn v2.x, the library used a different event system. All events are now camelCase strings.

fix

Update event listeners to use new event names (e.g., 'connect', 'disconnect', 'authenticate').

affects: >=3.0.0

Errors

Common errors & fixes

Error: WebSocket connection to 'ws://localhost:8001/' failed

VTube Studio is not running or the Plugin API is disabled.

fix

Ensure VTube Studio is open and the WebSocket Plugin is enabled in its settings (Plugins -> WebSocket API -> Enable).

TypeError: vtubestudio_1.ApiClient is not a constructor

Using a wrong import path (e.g., CDN without ?module) or not using named import.

fix

Use `import { ApiClient } from 'vtubestudio'` or the correct CDN URL with `?module`.

Error: Authentication required

The client tried to make an API call before authentication was completed.

fix

Wait for the 'authenticate' event to fire before making API calls, or check `apiClient.isAuthenticated`.

Upgrade

Version history

3.11.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

46 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/Hawkbat/VTubeStudioJS ↗

packagevtubestudio ↗

homepagehttps://github.com/Hawkbat/VTubeStudioJS#readme ↗