OBS Websocket API in Javascript, consumes @Palakis/obs-websocket
npm install obs-websocket-js-forked
OBSWebSocket.JS allows Javascript-based connections to the Open Broadcaster plugin obs-websocket.
Download |
Samples |
Changelog
``sh
npm install obs-websocket-js --save
bower install obs-websocket-js --save
`
Typescript definitions are published in a separate repo to more easily allow the use of any plugin version desired. Please refer to the readme at [obs-websocket-js-types][link-types-repo] for more information.
`sh`
npm install obs-websocket-js-types@4.4
. `html
`In node...
`js
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. `js
const obs = new OBSWebSocket();
obs.connect({ address: 'localhost:4444', password: '$up3rSecretP@ssw0rd' });
`#### 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][link-obswebsocket] 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][link-obswebsocket] plugin.
- {args} are optional. Note that both request-type and message-id will be bound automatically.
- callback(err, data) is optional. `js
obs.send('RequestName', {args}, callback(err, data)) returns Promise// The following are additional supported requests.
obs.connect({ address: 'address', password: 'password' }, callback(err, data)) 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][link-obswebsocket] 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][link-obswebsocket] plugin.`js
obs.on('EventName', callback(data));// The following are additional supported events.
obs.on('ConnectionOpened', callback(data));
obs.on('ConnectionClosed', callback(data));
obs.on('AuthenticationSuccess', callback(data));
obs.on('AuthenticationFailure', 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.`js
// You must add this handler to avoid uncaught exceptions.
obs.on('error', err => {
console.error('socket error:', err);
});
`\samples.
`js
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.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:`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][link-debug] documentation.Upgrading from 1.x to 2.x
In order to better decouple the javascript library from the [obs-websocket][link-obswebsocket] 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.`js
// No longer supported.
obs.getVersion();
obs.onSwitchScenes();// Supported.
obs.send('GetVersion');
obs.on('SwitchScenes');
`` [badge-build-status]: https://img.shields.io/travis/haganbmj/obs-websocket-js/master.svg?style=flat "Travis Status"
[badge-tag]: https://img.shields.io/github/tag/haganbmj/obs-websocket-js.svg?style=flat "Latest Tag"
[badge-release]: https://img.shields.io/github/release/haganbmj/obs-websocket-js.svg?style=flat "Latest Release"
[badge-coveralls]: https://coveralls.io/repos/github/haganbmj/obs-websocket-js/badge.svg?branch=master "Coveralls Status"
[badge-npm-downloads]: https://img.shields.io/npm/dt/obs-websocket-js.svg "NPM Downloads"
[link-obswebsocket]: https://github.com/Palakis/obs-websocket "OBS WebSocket Plugin"
[link-types-repo]: https://github.com/haganbmj/obs-websocket-js-types "obs-websocket-js Typescript Definitions"
[link-Travis-CI]: https://travis-ci.org/haganbmj/obs-websocket-js "Travis CI"
[link-Coveralls]: https://coveralls.io/github/haganbmj/obs-websocket-js?branch=master "Coveralls"
[link-releases]: https://github.com/haganbmj/obs-websocket-js/releases "obs-websocket-js Releases"
[link-tags]: https://github.com/haganbmj/obs-websocket-js/tags "obs-websocket-js Tags"
[link-download]: https://raw.githubusercontent.com/haganbmj/obs-websocket-js/gh-pages/dist/obs-websocket.js "Download"
[link-documentation]: https://github.com/haganbmj/obs-websocket-js/blob/gh-pages/DOCUMENTATION.md "Documentation"
[link-samples]: https://github.com/haganbmj/obs-websocket-js/tree/master/samples "Samples"
[link-changelog]: https://github.com/haganbmj/obs-websocket-js/blob/gh-pages/CHANGELOG.md "Changelog"
[link-contributing]: .github/CONTRIBUTING.md "Contributing"
[link-debug]: https://github.com/visionmedia/debug "Debug Documentation"