Registry / communication / obs-websocket-js

obs-websocket-js

library5.0.8jsnpmunverified

A JavaScript/TypeScript library for connecting to OBS Studio's obs-websocket plugin (v5 protocol). Current stable version is 5.0.8, released in June 2023. Provides a Promise-based API for controlling OBS via WebSocket, supporting both JSON and MessagePack encodings. Includes full TypeScript definitions, works in Node.js (>=16) and browsers. Key differentiator: actively maintained community fork of the original Palakis library, with support for the latest obs-websocket 5.x protocol.

communication

npm install obs-websocket-js

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · OBS-WEBSOCKET-JS

obs-websocket-js

communicationjavascriptv5.0.8

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.

OBSWebSocket

✓ import { OBSWebSocket } from 'obs-websocket-js'

✗ import OBSWebSocket from 'obs-websocket-js'

Named export, not default. CommonJS: const { OBSWebSocket } = require('obs-websocket-js').

OBSWebSocket (CommonJS)

✓ const { OBSWebSocket } = require('obs-websocket-js')

✗ const OBSWebSocket = require('obs-websocket-js')

Do not use require without destructuring; the default export is not a constructor.

OBSWebSocket (msgpack)

✓ import { OBSWebSocket } from 'obs-websocket-js/msgpack'

✗ import { OBSWebSocket } from 'obs-websocket-js'

Use the /msgpack subpath import to enable MessagePack encoding instead of JSON.

Connects to OBS WebSocket, retrieves scene list, and starts recording using the v5 protocol's 'call' method.

import { OBSWebSocket } from 'obs-websocket-js'; const obs = new OBSWebSocket(); async function connectToOBS() { try { const { obsWebSocketVersion, negotiatedRpcVersion } = await obs.connect('ws://127.0.0.1:4455', 'mypassword'); console.log(`Connected to OBS v${obsWebSocketVersion}, RPC v${negotiatedRpcVersion}`); } catch (error) { console.error('Failed to connect:', error); } } connectToOBS(); // Example: get scene list and toggle recording async function exampleCommands() { const scenes = await obs.call('GetSceneList'); console.log('Scenes:', scenes.scenes); await obs.call('StartRecord'); console.log('Recording started'); } setTimeout(exampleCommands, 2000);

Debug

Known issues

breakingv5 removed the old event-based API (e.g., obs.on('SwitchScenes')). Use 'call' and 'on' with event names from the OBS WebSocket protocol.

fix

Replace obs.on('SwitchScenes', handler) with obs.on('SceneChanged', handler) and use obs.call('SetCurrentProgramScene', { sceneName }) instead of obs.send('SetCurrentScene').

affects: >=5.0.0

breakingv5 requires OBS WebSocket 5.0.0 or higher on the server side. It is incompatible with obs-websocket 4.x.

fix

Update OBS and obs-websocket plugin to version 5.0.0 or later.

affects: >=5.0.0

gotchaThe library uses different WebSocket implementations depending on environment: 'ws' package in Node.js, native WebSocket in browsers. Ensure your bundler handles this correctly.

fix

If bundling for browser, set target to 'web' or provide a polyfill for 'ws' if needed. In Node.js, the 'ws' package is automatically used.

affects: *

deprecatedv5 deprecated the 'send' method. Use 'call' for RPC requests.

fix

Replace obs.send('SetCurrentScene', ...) with obs.call('SetCurrentProgramScene', ...).

affects: >=5.0.0

Errors

Common errors & fixes

TypeError: obs_websocket_js_1.OBSWebSocket is not a constructor

Using default import instead of named import.

fix

Use import { OBSWebSocket } from 'obs-websocket-js' or const { OBSWebSocket } = require('obs-websocket-js').

Error: Unsupported RPC version

OBS WebSocket server version is 4.x, but library v5 requires version 5.

fix

Update OBS and obs-websocket plugin to version 5.0.0 or later.

Module not found: Can't resolve 'ws'

Bundler is trying to resolve the 'ws' WebSocket implementation for browser but it's not available.

fix

If targeting browser, set resolve.fallback: { ws: false } in webpack or use a polyfill. Alternatively, import from 'obs-websocket-js/browser' if available.

Upgrade

Version history

5.0.8latest on npm

Audit

Dependencies

wsoptionalWebSocket client used in Node.js environments

Agent activity

10 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/obs-websocket-community-projects/obs-websocket-js ↗

packageobs-websocket-js ↗

homepagehttps://github.com/obs-websocket-community-projects/obs-websocket-js#readme ↗