OBSWebSocket.JS allows Javascript-based connections to the Open Broadcaster plugin obs-websocket.
Download | Samples | Changelog
npm install obs-websocket-js --save
bower install obs-websocket-js --save
The web distributable exposes a global named OBSWebSocket
.
<script type='text/javascript' src='./dist/obs-websocket.js'></script>
In node...
const OBSWebSocket = require('obs-websocket-js');
Create a new WebSocket connection using the following.
- Address is optional; defaults to
localhost
with a default port of4444
. - Password is optional.
const obs = new OBSWebSocket();
obs.connect({ address: 'localhost:4444', password: '$up3rSecretP@ssw0rd' });
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.- When calling a method directly (instead of via
.send
), you may also use thelowerCamelCase
version of the request, i.e.requestName
instead ofRequestName
. This may be preferred if you use a linter such as ESlint.
- When calling a method directly (instead of via
- {args} are optional. Note that both
request-type
andmessage-id
will be bound automatically. - callback(err, data) is optional.
// These three options are equivalent for every available request.
obs.send('RequestName', {args}, callback(err, data)) returns Promise
obs.RequestName({args}, callback(err, data)) returns Promise
obs.requestName({args}, callback(err, data)) returns Promise
// The following are additional supported requests.
obs.connect({ address: 'address', password: 'password' }, callback(err, data)) returns Promise
All events support the following two Syntax options where 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.
obs.on('EventName', callback(data));
obs.onEventName(callback(data));
// The following are additional supported requests.
obs.on('ConnectionOpened', callback(data));
obs.on('ConnectionClosed', callback(data));
obs.on('AuthenticationSuccess', callback(data));
obs.on('AuthenticationFailure', callback(data));
If this does not yet support a new method, or if you have custom hooks in your build of obs-websocket
and prefer to use the obs.requestName
and obs.onEventName
syntaxes, you can register your own methods at runtime. As always, these must match exactly what is to be expected from the plugin.
obs.registerRequest('RequestName')
obs.registerRequest(['RequestName1', 'RequestName2'])
obs.registerEvent('EventName')
obs.registerEvent(['EventName1', 'EventName2'])
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:
- Add a
.catch()
handler to every returned Promise. - Add a
error
event listener to theOBSWebSocket
object.
const OBSWebSocket = require('obs-websocket-js');
const obs = new OBSWebSocket();
obs.connect({ address: 'localhost:4444', password: '$up3rSecretP@ssw0rd' })
.then(() => {
console.log('Success! We\'re connected & authenticated.');
return obs.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.setCurrentScene({'scene-name': scene.name});
}
});
})
.catch(err => { // Ensure that you add a catch handler to every Promise chain.
console.log(err);
});
obs.onSwitchScenes(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);
});
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.
- Unit testing / Socket mocking.
- More examples.
To add your project to this list, submit a Pull Request.