Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/obs-websocket-community-projects/obs-websocket-js

Consumes https://github.com/obsproject/obs-websocket
https://github.com/obs-websocket-community-projects/obs-websocket-js

javascript nodejs obs obs-studio obs-websocket websocket-client

Last synced: about 2 months ago
JSON representation

Consumes https://github.com/obsproject/obs-websocket

Awesome Lists containing this project

README 

        
# obs-websocket-js





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




# Version Warning!



> You are currently reading the documentation for v5. [For v4 documentation look here](https://github.com/obs-websocket-community-projects/obs-websocket-js/tree/v4)



---



## Installation



### Via package manager



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.



```sh

npm install obs-websocket-js

yarn add obs-websocket-js

```



### Standalone file / CDN build



Standalone js file is available from [the latest github release](https://github.com/obs-websocket-community-projects/obs-websocket-js/releases) or from jsdeliver & unpkg CDN's:



```

https://cdn.jsdelivr.net/npm/obs-websocket-js

https://unpkg.com/obs-websocket-js

```



## Usage



### Builds



dist folder of the npm package includes 2 different builds to support [different message encodings supported by obs-websocket](https://github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md#connection-steps).



| 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](https://github.com/developit/microbundle#-modern-mode-). If you need support for older browsers, make sure to configure your bundler to also transpile dependencies with babel or other such .



### Creating an OBS Websocket client



`OBSWebSocket` is available as the default export in ES Modules:



```ts

import OBSWebSocket from 'obs-websocket-js';



const obs = new OBSWebSocket();

```



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



```ts

const {default: OBSWebSocket} = require('obs-websocket-js');

const OBSWebSocket = require('obs-websocket-js').default;



const obs = new OBSWebSocket();

```



### Connecting



```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](https://github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md#identify-opcode-1)
Use this to include RPC version to guarantee compatibility with server



Returns promise that resolves to data from [Hello](https://github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md#hello-opcode-0) and [Identified](https://github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md#identified-opcode-2) messages or rejects with connection error (either matching obs-websocket [WebSocketCloseCode](https://github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md#websocketclosecode) or with code -1 when non-compatible server is detected).



```ts

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: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);

}

```



### Reidentify



```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](https://github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md#reidentify-opcode-3)



Returns promise that resolves when the server has acknowledged the request



```ts

await obs.reidentify({

  eventSubscriptions: EventSubscription.General | EventSubscription.InputShowStateChanged

});

```



### Disconnecting



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

```



### Sending Requests



```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](https://github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md#requests))

`requestData`
`object (optional)` | Request data ([see obs-websocket documentation for the request](https://github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md#requests))



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

```



### Sending Batch Requests



```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](https://github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md#requests)). Each request follows the same structure as individual requests sent to [`call`](#sending-requests).

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

```



### Receiving Events



```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](https://github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md#events))

`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](https://github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md#events))



```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](https://github.com/primus/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-js 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](https://github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md#hello-opcode-0))

* `Identified` - When client has connected and identified (called with [Identified](https://github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md#identified-opcode-2) 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-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

});

```



## Debugging



To enable debug logging, set the `DEBUG` environment variable:



```sh

# 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:



```sh

DEBUG=foo,bar:*,obs-websocket-js:*



# on Windows

set DEBUG=foo,bar:*,obs-websocket-js:*

```



Browser debugging uses `localStorage`



```js

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



localStorage.debug = 'foo,bar:*,obs-websocket-js:*';

```



For more information, see the [`debug`](https://github.com/visionmedia/debug) package documentation.



## Upgrading



* [Upgrading from 4.x to 5.x](https://github.com/obs-websocket-community-projects/obs-websocket-js/releases/tag/v5.0.0)

* [Upgrading from 2.x to 3.x](https://github.com/obs-websocket-community-projects/obs-websocket-js/tree/v4#upgrading-from-2x-to-3x)

* [Upgrading from 1.x to 2.x](https://github.com/obs-websocket-community-projects/obs-websocket-js/tree/v4#upgrading-from-1x-to-2x)



## Projects Using **obs-websocket-js**



[Share your project in github discussions!](https://github.com/obs-websocket-community-projects/obs-websocket-js/discussions/categories/show-and-tell)



## [Contributing Guidelines](.github/CONTRIBUTING.md)