obs-websocket-js allows Javascript-based connections to the Open Broadcaster Software plugin obs-websocket.
Created by Brendan Hagan
Maintained by OBS Websocket Community
Download | Samples | Changelog
You are currently reading the documentation for upcoming v5. For v4 documentation look here
Using a package manager like npm / yarn is the recommended installation method when you're planning to use obs-websocket-js in node.js, building a web app that you'll bundle with webpack or rollup, or for using type definitions.
npm install obs-websocket-js@next
or
yarn add obs-websocket-js@next
Until obs-websocket 5.0 is released, the client supporting 5.x is released under next tag
dist folder of the npm package includes 2 different builds to support different message encodings supported by obs-websocket.
Connection Encoding | JSON | Msgpack |
---|---|---|
Used by default | By web bundles | By node.js |
Manually opting into | import OBSWebSocket from 'obs-web-socket/json' |
import OBSWebSocket from 'obs-web-socket/msgpack' |
Benefits | Easier debugging, smaller bundle | Connection uses less bandwidth |
Downsides | Connection uses more bandwidth | Harder to debug, bigger bundle size |
In addition each version has both modern and legacy builds. Modern bundlers will opt into modern build which uses most modern JS features while also being supported by most modern browsers. If you need support for older browsers, make sure to configure your bundler to also transpile dependencies with babel or other such .
OBSWebSocket
is available as the default export in ES Modules:
import OBSWebSocket from 'obs-websocket-js';
const obs = new OBSWebSocket();
When using commonjs require()
it is available under the default
object key:
const {default: OBSWebSocket} = require('obs-websocket-js');
const OBSWebSocket = require('obs-websocket-js').default;
const obs = new OBSWebSocket();
connect(url = 'ws://127.0.0.1:4444', password?: string, identificationParams = {}): Promise
To connect to obs-websocket server use the connect
method.
Parameter | Description |
---|---|
url string (optional) |
Websocket URL to connect to, including protocol. (For example when connecting via a proxy that supports https use wss://127.0.0.1:4444 ) |
password string (optional) |
Password required to authenticate with obs-websocket server |
identificationParams object (optional) |
Object with parameters to send with the Identify message Use this to include RPC version to guarantee compatibility with server |
Returns promise that resolves to data from Hello and Identified messages or rejects with connection error (either matching obs-websocket WebSocketCloseCode or with code -1 when non-compatible server is detected).
import OBSWebSocket, {EventSubscription} from 'obs-websocket-js';
const obs = new OBSWebSocket();
// connect to obs-websocket running on localhost with same port
await obs.connect();
// Connect to obs-ws running on 192.168.0.4
await obs.connect('ws://192.168.0.4:4444');
// Connect to localhost with password
await obs.connect('ws://127.0.0.1:4444', 'super-sekret');
// Connect expecting RPC version 1
await obs.connect('ws://127.0.0.1:4444', undefined, {rpcVersion: 1});
// Connect with request for high-volume event
await obs.connect('ws://127.0.0.1:4444', undefined, {
eventSubscriptions: EventSubscription.All | EventSubscription.InputVolumeMeters,
rpcVersion: 1
});
// A complete example
try {
const {
obsWebSocketVersion,
negotiatedRpcVersion
} = await obs.connect('ws://192.168.0.4:4444', 'password', {
rpcVersion: 1
});
console.log(`Connected to server ${obsWebSocketVersion} (using RPC ${negotiatedRpcVersion})`)
} catch (error) {
console.error('Failed to connect', error.code, error.message);
}
reidentify(data: {}): Promise
To update session parameters set by initial identification use reidentify
method.
Parameter | Description |
---|---|
data object |
Object with parameters to send with the Reidentify message |
Returns promise that resolves when the server has acknowledged the request
await obs.reidentify({
eventSubscriptions: EventSubscription.General | EventSubscription.InputShowStateChanged
});
disconnect(): Promise
Disconnects from obs-websocket server. This keeps any registered event listeners.
Returns promise that resolves when connection is closed
await obs.disconnect();
call(requestType: string, requestData?: object): Promise
Sending requests to obs-websocket is done via call
method.
Parameter | Description |
---|---|
requestType string |
Request type (see obs-websocket documentation) |
requestData object (optional) |
Request data (see obs-websocket documentation for the request) |
Returns promise that resolves with response data (if applicable) or rejects with error from obs-websocket.
// Request without data
const {currentProgramSceneName} = await obs.call('GetCurrentProgramScene');
// Request with data
await obs.call('SetCurrentProgramScene', {sceneName: 'Gameplay'});
// Both together now
const {inputMuted} = obs.call('ToggleInputMute', {inputName: 'Camera'});
on(event: string, handler: Function)
once(event: string, handler: Function)
off(event: string, handler: Function)
addListener(event: string, handler: Function)
removeListener(event: string, handler: Function)
To listen for events emitted by obs-websocket use the event emitter API methods.
Parameter | Description |
---|---|
event string |
Event type (see obs-websocket documentation) |
handler Function |
Function that is called when event is sent by the server. Recieves data as the first argument (see obs-websocket documentation for the event) |
function onCurrentSceneChanged(event) {
console.log('Current scene changed to', event.sceneName)
}
obs.on('CurrentSceneChanged', onCurrentSceneChanged);
obs.once('ExitStarted', () => {
console.log('OBS started shutdown');
// Just for example, not necessary should you want to reuse this instance by re-connect()
obs.off('CurrentSceneChanged', onCurrentSceneChanged);
});
Internally eventemitter3 is used and it's documentation can be referenced for advanced usage
In addition to obs-websocket events, following events are emitted by obs-websocket-js client itself:
ConnectionOpened
- When connection has opened (no data)ConnectionClosed
- When connection closed (called withOBSWebSocketError
object)ConnectionError
- When connection closed due to an error (generally above is more useful)Hello
- When server has sent Hello message (called with Hello data)Identified
- When client has connected and identified (called with Identified data)
This library is written in typescript and typescript definitions are published with the package. Each package is released with typescript defintions matching the currently released version of obs-websocket. This data can be reused from OBSEventTypes
, OBSRequestTypes
and OBSResponseTypes
named exports, though in most cases function parameters will enforce the typings correctly.
import OBSWebSocket, {OBSEventTypes, OBSRequestTypes, OBSResponseTypes} from 'obs-websocket-js';
function onProfileChanged(event: OBSEventTypes['CurrentProfileChanged']) {
event.profileName
}
obs.on('CurrentProfileChanged', onProfileChanged);
obs.on('VendorEvent', ({vendorName, eventType, eventData}) => {
if (vendorName !== 'fancy-plugin') {
return;
}
});
const req: OBSRequestTypes['SetSceneName'] = {
sceneName: 'old-and-busted',
newSceneName: 'new-hotness'
};
obs.call('SetSceneName', req);
obs.call('SetInputMute', {
inputName: 'loud noises',
inputMuted: true
});
To enable debug logging, set the DEBUG
environment variable:
# Enables debug logging for all modules of osb-websocket-js
DEBUG=obs-websocket-js:*
# on Windows
set DEBUG=obs-websocket-js:*
If you have multiple libraries or application which use the DEBUG
environment variable, they can be joined with commas:
DEBUG=foo,bar:*,obs-websocket-js:*
# on Windows
set DEBUG=foo,bar:*,obs-websocket-js:*
Browser debugging uses localStorage
localStorage.debug = 'obs-websocket-js:*';
localStorage.debug = 'foo,bar:*,obs-websocket-js:*';
For more information, see the debug
package documentation.
- Upgrading from 4.x to 5.x (available soon)
- Upgrading from 2.x to 3.x
- Upgrading from 1.x to 2.x
To add your project to this list, submit a Pull Request.