obs-websocket-bun

obs-websocket-bun allows Javascript-based connections to the Open Broadcaster Software plugin obs-websocket.



Created by Brendan Hagan


Maintained by OBS Websocket Community

Download |
Samples |
Changelog

Version Warning

> You are currently reading the documentation for v5. For v4 documentation look here

---

Installation

$3

Using a package manager like npm / yarn is the recommended installation method when you're planning to use obs-websocket-bun in node.js, building a web app that you'll bundle with webpack or rollup, or for using type definitions.

``sh
npm install obs-websocket-bun
yarn add obs-websocket-bun
`

$3

Standalone js file is available from jsdeliver & unpkg CDN's:

`
https://cdn.jsdelivr.net/npm/obs-websocket-bun
https://unpkg.com/obs-websocket-bun
`

Usage

$3

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 .

$3

OBSWebSocket is available as a named export in ES Modules:

`ts
import { OBSWebSocket } from 'obs-websocket-bun';

const obs = new OBSWebSocket();
`

When using commonjs require() it is available under the OBSWebSocket object key:

`ts
const { OBSWebSocket } = require('obs-websocket-bun');
const OBSWebSocket = require('obs-websocket-bun').OBSWebSocket;

const obs = new OBSWebSocket();
`

$3

`ts
connect(url = 'ws://127.0.0.1:4455', 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:4455)
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).

`ts
import OBSWebSocket, {EventSubscription} from 'obs-websocket-bun';
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:4455');

// Connect to localhost with password
await obs.connect('ws://127.0.0.1:4455', 'super-sekret');

// Connect expecting RPC version 1
await obs.connect('ws://127.0.0.1:4455', undefined, {rpcVersion: 1});

// Connect with request for high-volume event
await obs.connect('ws://127.0.0.1:4455', undefined, {
eventSubscriptions: EventSubscription.All | EventSubscription.InputVolumeMeters,
rpcVersion: 1
});

// A complete example
try {
const {
obsWebSocketVersion,
negotiatedRpcVersion
} = await obs.connect('ws://192.168.0.4:4455', 'password', {
rpcVersion: 1
});
console.log(Connected to server ${obsWebSocketVersion} (using RPC ${negotiatedRpcVersion}))
} catch (error) {
console.error('Failed to connect', error.code, error.message);
}
`

$3

`ts
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

`ts
await obs.reidentify({
eventSubscriptions: EventSubscription.General | EventSubscription.InputShowStateChanged
});
`

$3

`ts
disconnect(): Promise
`

Disconnects from obs-websocket server. This keeps any registered event listeners.

Returns promise that resolves when connection is closed

`ts
await obs.disconnect();
`

$3

`ts
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.

`ts
// 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'});
`

$3

`ts
callBatch(requests: RequestBatchRequest[], options?: RequestBatchOptions): Promise
`

Multiple requests can be batched together into a single message sent to obs-websocket using the callBatch method. The full request list is sent over the socket at once, obs-websocket executes the requests based on the options provided, then returns the full list of results once all have finished.

Parameter | Description
---|---
requests
RequestBatchRequest[] | The list of requests to be sent (see obs-websocket documentation). Each request follows the same structure as individual requests sent to call.
options
RequestBatchOptions (optional) | Options controlling how obs-websocket will execute the request list.
options.executionType
RequestBatchExecutionType (optional) | The mode of execution obs-websocket will run the batch in
options.haltOnFailure
boolean (optional) | Whether obs-websocket should stop executing the batch if one request fails

Returns promise that resolve with a list of results, one for each request that was executed.

`ts
// Execute a transition sequence to a different scene with a specific transition.
const results = await obs.callBatch([
{
requestType: 'GetVersion',
},
{
requestType: 'SetCurrentPreviewScene',
requestData: {sceneName: 'Scene 5'},
},
{
requestType: 'SetCurrentSceneTransition',
requestData: {transitionName: 'Fade'},
},
{
requestType: 'Sleep',
requestData: {sleepMillis: 100},
},
{
requestType: 'TriggerStudioModeTransition',
}
])
`

Currently, obs-websocket-bun is not able to infer the types of ResponseData to any specific request's response. To use the data safely, cast it to the appropriate type for the request that was sent.

`ts
(results[0].responseData as OBSResponseTypes['GetVersion']).obsVersion //=> 28.0.0
`

$3

`ts
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)

`ts
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

#### Internal events

In addition to obs-websocket events, following events are emitted by obs-websocket-bun client itself:

* ConnectionOpened - When connection has opened (no data)
* ConnectionClosed - When connection closed (called with OBSWebSocketError 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)

Typescript Support

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.

`ts
import OBSWebSocket, {OBSEventTypes, OBSRequestTypes, OBSResponseTypes} from 'obs-websocket-bun';

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
});
`

Debugging

To enable debug logging, set the DEBUG environment variable:

`sh


Enables debug logging for all modules of osb-websocket-js

DEBUG=obs-websocket-bun:*

on Windows

set DEBUG=obs-websocket-bun:*
`

If you have multiple libraries or application which use the DEBUG environment variable, they can be joined with commas:

`sh
DEBUG=foo,bar:,obs-websocket-bun:

on Windows


set DEBUG=foo,bar:,obs-websocket-bun:
`

Browser debugging uses localStorage

`js
localStorage.debug = 'obs-websocket-bun:*';

localStorage.debug = 'foo,bar:,obs-websocket-bun:';
`

For more information, see the debug` package documentation.

Upgrading

* Upgrading from 4.x to 5.x
* Upgrading from 2.x to 3.x
* Upgrading from 1.x to 2.x

Projects Using obs-websocket-bun

Share your project in github discussions!

Contributing Guidelines