Need help with obs-websocket-js?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

haganbmj
326 Stars 63 Forks MIT License 171 Commits 56 Opened issues

Description

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

Services available

!
?

Need anything else?

Contributors list

# 149,935
C++
obs-stu...
HTML
GitHub
99 commits
# 181
nextjs
postman...
graphql...
angular...
24 commits
# 62,999
algolia...
Algolia
lunr
Sass
1 commit
# 135,762
Nest
gRPC
C#
Twitch
1 commit
# 183,526
PHP
timber
Shell
HTML
1 commit
# 6,536
chalk
Svelte
example...
Ada
1 commit
# 48,025
phantom...
elixir-...
TypeScr...
Chrome
1 commit

obs-websocket-js

OBSWebSocket.JS allows Javascript-based connections to the Open Broadcaster plugin obs-websocket.

Download | Samples | Changelog

Installation

npm install obs-websocket-js --save

bower install obs-websocket-js --save

Typescript definitions are included in this package, and are automatically generated to match the latest

obs-websocket
release.

Usage

Instantiation

The web distributable exposes a global named

OBSWebSocket
.

In node...

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

Create a new WebSocket connection using the following. - Address is optional; defaults to

localhost
with a port of
4444
.
- Password is optional.
const obs = new OBSWebSocket();
obs.connect({ address: 'localhost:4444', password: '[email protected]' });

Sending Requests

All requests support the following two Syntax options where both

err
and
data
will contain the raw response from the WebSocket plugin.
Note that all response objects will supply both the original obs-websocket response items in their original format (ex:
'response-item'
), but also camelCased (ex:
'responseItem'
) for convenience.

- RequestName must exactly match what is defined by the
obs-websocket
plugin.
-
{args}
are optional. Note that both
request-type
and
message-id
will be bound automatically.
- To use callbacks instead of promises, use the
sendCallback
method instead of
send
.
// Promise API
obs.send('RequestName', {args}) // returns Promise

// Callback API obs.sendCallback('RequestName', {args}, callback(err, data)) // no return value

// The following are additional supported requests. obs.connect({ address: 'address', password: 'password' }) // returns Promise obs.disconnect();

Receiving Events

For all events,

data
will contain the raw response from the WebSocket plugin.
Note that all response objects will supply both the original obs-websocket response items in their original format (ex:
'response-item'
), but also camelCased (ex:
'responseItem'
) for convenience.

- EventName must exactly match what is defined by the
obs-websocket
plugin.
const callback = (data) => {
    console.log(data);
};

obs.on('EventName', (data) => callback(data));

// The following are additional supported events. obs.on('ConnectionOpened', (data) => callback(data)); obs.on('ConnectionClosed', (data) => callback(data)); obs.on('AuthenticationSuccess', (data) => callback(data)); obs.on('AuthenticationFailure', (data) => callback(data));

Handling Errors

By default, certain types of WebSocket errors will be thrown as uncaught exceptions. To ensure that you are handling every error, you must do the following: 1. Add a

.catch()
handler to every returned Promise. 2. Add a
error
event listener to the
OBSWebSocket
object. By default only errors on the initial socket connection will be caught. Any subsequent errors will be emit here and will be considered uncaught without this handler.
// You must add this handler to avoid uncaught exceptions.
obs.on('error', err => {
    console.error('socket error:', err);
});

Example

See more examples in

\samples
. ```js const OBSWebSocket = require('obs-websocket-js');

const obs = new OBSWebSocket(); obs.connect({ address: 'localhost:4444', password: '[email protected]' }) .then(() => { console.log(

Success! We're connected & authenticated.
);
    return obs.send('GetSceneList');
})
.then(data => {
    console.log(`${data.scenes.length} Available Scenes!`);

data.scenes.forEach(scene => {
    if (scene.name !== data.currentScene) {
        console.log(`Found a different scene! Switching to Scene: ${scene.name}`);

        obs.send('SetCurrentScene', {
            'scene-name': scene.name
        });
    }
});

}) .catch(err => { // Promise convention dicates you have a catch on every chain. console.log(err); });

obs.on('SwitchScenes', data => { console.log(

New Active Scene: ${data.sceneName}
); });

// You must add this handler to avoid uncaught exceptions. obs.on('error', err => { console.error('socket error:', err); }); ```

Debugging

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
documentation.

Upgrading from 1.x to 2.x

In order to better decouple the javascript library from the obs-websocket plugin the decision has been made to no longer provide method definitions for request/event methods. You are responsible for aligning your method calls with the plugin version that you would like to support.

// No longer supported.
obs.getVersion();
obs.onSwitchScenes();

// Supported. obs.send('GetVersion'); obs.on('SwitchScenes');

Upgrading from 2.x to 3.x

  • The
    es5
    build is no longer provided. If you're in an environment which must run ES5-compatible code, continue using the latest 2.x release.
  • The Callback API has been separated from the Promise API. If you use callbacks in your
    send
    invocations, you will need to update them to use the new
    sendCallback
    method:
  // No longer supported!
  obs.send('StartStreaming', (error) => {
    // Code here...
  });

// Use this instead: obs.sendCallback('StartStreaming', (error) => { // Code here... });

  • The
    connect
    method no longer accepts a callback. Use the promise it returns instead.
  // No longer supported!
  obs.connect({address: 'localhost: 4444'}, (error) => {
    // Code here...
  });

// Use this instead: obs.connect({address: 'localhost: 4444'}).then(() => { console.log('connected'); }).catch((error) => { console.error(error); });

Projects Using obs-websocket-js

To add your project to this list, submit a Pull Request. - GamesDoneQuick/agdq17-layouts - nodecg/nodecg-obs

Contributing Guidelines

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.