{"id":49657,"library":"vtubestudio","title":"VTubeStudioJS","description":"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.","status":"active","version":"3.11.0","language":"javascript","source_language":"en","source_url":"https://github.com/Hawkbat/VTubeStudioJS","tags":["javascript","vtstudio","vtuber","vtubestudio","typescript"],"install":[{"cmd":"npm install vtubestudio","lang":"bash","label":"npm"},{"cmd":"yarn add vtubestudio","lang":"bash","label":"yarn"},{"cmd":"pnpm add vtubestudio","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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;","wrong":"const ApiClient = require('vtubestudio');","symbol":"ApiClient","correct":"import { ApiClient } from 'vtubestudio';"},{"note":"Use `import type` for type-only imports to avoid runtime errors in transpiled code.","wrong":"import { IApiClientOptions } from 'vtubestudio';","symbol":"IApiClientOptions","correct":"import type { IApiClientOptions } from 'vtubestudio';"},{"note":"Named import is required even from CDN. The ?module parameter enables ESM module support.","wrong":"import ApiClient from 'https://unpkg.com/vtubestudio/lib/esm/vtubestudio.min.js';","symbol":"ApiClient (from CDN)","correct":"import { ApiClient } from 'https://unpkg.com/vtubestudio/lib/esm/vtubestudio.min.js?module';"}],"quickstart":{"code":"import { ApiClient } from 'vtubestudio';\n\nfunction setAuthToken(token: string | null) {\n  if (token) {\n    localStorage.setItem('VTS_AUTH_TOKEN', token);\n  } else {\n    localStorage.removeItem('VTS_AUTH_TOKEN');\n  }\n}\n\nfunction getAuthToken(): string | null {\n  return localStorage.getItem('VTS_AUTH_TOKEN');\n}\n\nconst options = {\n  authTokenGetter: getAuthToken,\n  authTokenSetter: setAuthToken,\n  pluginName: 'My Plugin',\n  pluginDeveloper: 'My Name',\n};\n\nconst apiClient = new ApiClient(options);\n\napiClient.on('connect', async () => {\n  // after authentication\n  const response = await apiClient.getCurrentModel();\n  console.log(response);\n});\n\n// Wait for connection to establish\nsetTimeout(async () => {\n  if (apiClient.isConnected) {\n    const response = await apiClient.getStatistics();\n    console.log(response);\n  }\n}, 1000);","lang":"typescript","description":"Initializes an ApiClient with authentication token persistence using browser localStorage, listens for the connect event, and makes a simple API call."},"warnings":[{"fix":"Use try-catch around every API call, and check apiClient.isConnected before making calls.","message":"API 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.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Remove any calls to `authenticationRequired`. Provide authTokenGetter and authTokenSetter in client options.","message":"The method `authenticationRequired` was removed in v3.0.0. Authentication is now handled internally.","severity":"deprecated","affected_versions":">=3.0.0"},{"fix":"Change `apiClient.on('authentication', ...)` to `apiClient.on('authenticate', ...)`.","message":"The event 'authentication' was renamed to 'authenticate' in v3.0.0.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Replace `authToken` with getter/setter functions.","message":"The `authToken` option in client options is deprecated; use authTokenGetter and authTokenSetter for token persistence.","severity":"gotcha","affected_versions":">=3.0.0 <4.0.0"},{"fix":"Update event listeners to use new event names (e.g., 'connect', 'disconnect', 'authenticate').","message":"In v2.x, the library used a different event system. All events are now camelCase strings.","severity":"breaking","affected_versions":">=3.0.0"}],"env_vars":null,"search_vec":"'3.11.0':20 'agnost':62 'api':10,43,56 'authent':48 'automat':46 'browser':14,67 'cadenc':80 'call':57 'client':28 'comprehens':72 'control':30 'current':16 'definit':74 'depend':70 'develop':88 'differenti':59 'e.g':33 'environ':15 'face':34 'featur':27 'full':26 'full-featur':25 'hotkey':38 'implement':4 'includ':45 'interfac':53 'irregular':82 'javascript':89 'key':58 'librari':22 'maintain':84 'manipul':37 'model':36 'node':65 'node.js':12 'offici':41 'packag':78 'persist':50 'platform':61 'platform-agnost':60 'provid':23 'reconnect':47 'releas':79 'runtim':69 'ship':75 'singl':87 'stabl':17 'studio':8,32 'token':49 'track':35 'type':52,73 'typescript':3,93 'version':18 'via':39 'vtstudio':90 'vtube':7,31 'vtuber':91 'vtubestudio':92 'vtubestudioj':1 'websocket':9,42 'work':63 'zero':68","created_at":"2026-06-07T17:02:55.653633+00:00","updated_at":"2026-06-07T17:02:55.653633+00:00","problems":[{"fix":"Ensure VTube Studio is open and the WebSocket Plugin is enabled in its settings (Plugins -> WebSocket API -> Enable).","cause":"VTube Studio is not running or the Plugin API is disabled.","error":"Error: WebSocket connection to 'ws://localhost:8001/' failed"},{"fix":"Use `import { ApiClient } from 'vtubestudio'` or the correct CDN URL with `?module`.","cause":"Using a wrong import path (e.g., CDN without ?module) or not using named import.","error":"TypeError: vtubestudio_1.ApiClient is not a constructor"},{"fix":"Wait for the 'authenticate' event to fire before making API calls, or check `apiClient.isAuthenticated`.","cause":"The client tried to make an API call before authentication was completed.","error":"Error: Authentication required"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/Hawkbat/VTubeStudioJS#readme","github":"https://github.com/Hawkbat/VTubeStudioJS","docs":null,"changelog":null,"pypi":null,"npm":"vtubestudio","openapi_spec":null,"status_page":null,"smithery":null,"categories":["communication"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}