obs-websocket-js
    TypeScript icon, indicating that this package has built-in type declarations

    4.0.3 • Public • Published

    obs-websocket-js

    OBSWebSocket.JS allows Javascript-based connections to the Open Broadcaster plugin obs-websocket.
    Created by Brendan Hagan
    Maintained by OBS Websocket Community

    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.

    <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 port of 4444.
    • Password is optional.
    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 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.

    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:

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

    Contributing Guidelines

    Install

    npm i obs-websocket-js

    DownloadsWeekly Downloads

    4,434

    Version

    4.0.3

    License

    MIT

    Unpacked Size

    498 kB

    Total Files

    15

    Last publish

    Collaborators

    • tt2468
    • haganbmj
    • t2t2