NodeCG

NodeCG

new NodeCG(bundle)

Creates a new NodeCG API instance. It should never be necessary to use this constructor in a bundle, as NodeCG automatically injects a pre-made API instance.

Source:
Parameters:
Name Type Description
bundle object

The bundle object to build an API instance from.

Members

(static) declaredReplicants

An object containing references to all Replicants that have been declared in this window, sorted by bundle. E.g., NodeCG.declaredReplicants.myBundle.myRep

Source:

bundleConfig

An object containing the parsed content of cfg/<bundle-name>.json, the contents of which are read once when NodeCG starts up. Used to quickly access per-bundle configuration properties.

Properties:
Type Description
Object
Source:

extensions

Extension only
Object containing references to all other loaded extensions. To access another bundle's extension, it must be declared as a bundleDependency in your bundle's package.json.

Properties:
Type Description
Object
Source:
Example
// bundles/my-bundle/package.json
{
    "name": "my-bundle"
    ...
    "bundleDependencies": {
        "other-bundle": "^1.0.0"
    }
}

// bundles/my-bundle/extension.js
module.exports = function (nodecg) {
    var otherBundle = nodecg.extensions['other-bundle'];
    // Now I can use `otherBundle`!
}

Logger :Object

Provides easy access to the Logger class. Useful in cases where you want to create your own custom logger.

Source:
Type:
  • Object

Methods

findCue(cueName) → {Object|undefined}

Returns the sound cue of the provided cueName in the current bundle. Returns undefined if a cue by that name cannot be found in this bundle.

Source:
Parameters:
Name Type Description
cueName String
Returns:
Type:
Object | undefined
  • A NodeCG cue object.

getDialog(name, bundleopt) → {object}

Browser only
Returns the specified dialog element.

Source:
Parameters:
Name Type Attributes Default Description
name string

The desired dialog's name.

bundle string <optional>
CURR_BNDL

The bundle from which to select the dialog.

Returns:
Type:
object

getDialogDocument(name, bundleopt) → {object}

Browser only
Returns the specified dialog's iframe document.

Source:
Parameters:
Name Type Attributes Default Description
name string

The desired dialog's name.

bundle string <optional>
CURR_BNDL

The bundle from which to select the dialog.

Returns:
Type:
object

getSocketIOServer()

Extension only
Gets the server Socket.IO context.

Source:

listenFor(messageName, bundleNameopt, handlerFunc)

Listens for a message, and invokes the provided callback each time the message is received. If any data was sent with the message, it will be passed to the callback.

Messages are namespaced by bundle. To listen to a message in another bundle's namespace, provide it as the second argument.

Source:
Parameters:
Name Type Attributes Default Description
messageName string

The name of the message.

bundleName string <optional>
CURR_BNDL

The bundle namespace to in which to listen for this message

handlerFunc function

The callback fired when this message is received.

Examples
nodecg.listenFor('printMessage', message => {
    console.log(message);
});

Listening to a message in another bundle's namespace:

nodecg.listenFor('printMessage', 'another-bundle', message => {
    console.log(message);
});

log()

An instance of NodeCG's Logger, with the following methods. The logging level is set in cfg/nodecg.json, NodeCG's global config file.

nodecg.log.trace('trace level logging');
nodecg.log.debug('debug level logging');
nodecg.log.info('info level logging');
nodecg.log.warn('warn level logging');
nodecg.log.error('error level logging');
Source:

mount()

Extension only
Mounts express middleware to the main server express app. See the express docs for usage.

Source:

playSound(cueName, optsopt) → {Object|undefined}

Plays the sound cue of the provided cueName in the current bundle. Does nothing if the cue doesn't exist or if the cue has no assigned file to play.

Source:
Parameters:
Name Type Attributes Description
cueName String
opts Object <optional>
Name Type Attributes Default Description
updateVolume <optional>
true

Whether or not to let NodeCG automatically update this instance's volume when the user changes it on the dashboard.

Returns:
Type:
Object | undefined
  • A SoundJS AbstractAudioInstance.

readReplicant(name, bundleopt, cb)

Reads the value of a replicant once, and doesn't create a subscription to it. Also available as a static method.

Source:
Parameters:
Name Type Attributes Default Description
name string

The name of the replicant.

bundle string <optional>
CURR_BNDL

The bundle namespace to in which to look for this replicant.

cb function

Browser only The callback that handles the server's response which contains the value.

Examples

From an extension:

// Extensions have immediate access to the database of Replicants.
// For this reason, they can use readReplicant synchronously, without a callback.
module.exports = function (nodecg) {
    var myVal = nodecg.readReplicant('myVar', 'some-bundle');
}

From a graphic or dashboard panel:

// Graphics and dashboard panels must query the server to retrieve the value,
// and therefore must provide a callback.
nodecg.readReplicant('myRep', 'some-bundle', value => {
    // I can use 'value' now!
    console.log('myRep has the value '+ value +'!');
});

Replicant(name, namespaceopt, optsopt)

Replicants are objcts which monitor changes to a variable's value. The changes are replicated across all extensions, graphics, and dashboard panels. When a Replicant changes in one of those places it is quickly updated in the rest, and a change event is emitted allowing bundles to react to the changes in the data.

If a Replicant with a given name in a given bundle namespace has already been declared, the Replicant will automatically be assigned the existing value.

Replicants must be declared in each context that wishes to use them. For instance, declaring a replicant in an extension does not automatically make it available in a graphic. The graphic must also declare it.

By default Replicants will be saved to disk, meaning they will automatically be restored when NodeCG is restarted, such as after an unexpected crash. If you need to opt-out of this behaviour simply set persistent: false in the opts argument.

As of NodeCG 0.8.4, Replicants can also be automatically validated against a JSON Schema that you provide. See Replicant Validation for more information.

Source:
Parameters:
Name Type Attributes Description
name string

The name of the replicant.

namespace string <optional>

The namespace to in which to look for this replicant. Defaults to the name of the current bundle.

opts object <optional>

The options for this replicant.

Name Type Attributes Default Description
defaultValue * <optional>

The default value to instantiate this Replicant with. The default value is only applied if this Replicant has not previously been declared and if it has no persisted value.

persistent boolean <optional>
true

Whether to persist the Replicant's value to disk on every change. Persisted values are re-loaded on startup.

schemaPath string <optional>

The filepath at which to look for a JSON Schema for this Replicant. Defaults to nodecg/bundles/${bundleName}/schemas/${replicantName}.json. Please note that this default path will be URIEncoded to ensure that it results in a valid filename.

Example
const myRep = nodecg.Replicant('myRep', {defaultValue: 123});

myRep.on('change', (newValue, oldValue) => {
    console.log(`myRep changed from ${oldValue} to ${newValue}`);
});

myRep.value = 'Hello!';
myRep.value = {objects: 'work too!'};
myRep.value = {objects: {can: {be: 'nested!'}}};
myRep.value = ['Even', 'arrays', 'work!'];

sendMessage(messageName, dataopt, cbopt) → {Promise}

Sends a message with optional data within the current bundle. Messages can be sent from client to server, server to client, or client to client.

Messages are namespaced by bundle. To send a message in another bundle's namespace, use NodeCG#sendMessageToBundle.

When a sendMessage is used from a client context (i.e., graphic or dashboard panel), it returns a Promise called an "acknowledgement". Your server-side code (i.e., extension) can invoke this acknowledgement with whatever data (or error) it wants. Errors sent to acknowledgements from the server will be properly serialized and intact when received on the client.

Alternatively, if you do not wish to use a Promise, you can provide a standard error-first callback as the last argument to sendMessage.

See Socket.IO's docs for more information on how acknowledgements work under the hood.

Source:
Parameters:
Name Type Attributes Description
messageName string

The name of the message.

data mixed <optional>

The data to send.

cb function <optional>

Browser only The error-first callback to handle the server's acknowledgement message, if any.

Returns:
Type:
Promise
  • Browser only A Promise that is rejected if the first argument provided to the acknowledgement is an Error, otherwise it is resolved with the remaining arguments provided to the acknowledgement.
Examples

Sending a normal message:

nodecg.sendMessage('printMessage', 'dope.');

Sending a message and replying with an acknowledgement:

// bundles/my-bundle/extension.js
module.exports = function (nodecg) {
    nodecg.listenFor('multiplyByTwo', (value, ack) => {
        if (value === 4) {
            ack(new Error('I don\'t like multiplying the number 4!');
            return;
        }

        // acknowledgements should always be error-first callbacks.
        // If you do not wish to send an error, use a falsey value
        // like "null" instead.
        ack(null, value * 2);
    });
}

// bundles/my-bundle/graphics/script.js
// Both of these examples are functionally identical.

// Promise acknowledgement
nodecg.sendMessage('multiplyByTwo', 2)
    .then(result => {
        console.log(result); // Will eventually print '4'
    .catch(error => {
        console.error(error);
    });

// Error-first callback acknowledgement
nodecg.sendMessage('multiplyByTwo', 2, (error, result) => {
    if (error) {
        console.error(error);
        return;
    }

    console.log(result); // Will eventually print '4'
});

stopAllSounds()

Stops all currently playing sounds on the page.

Source:

stopSound(cueName)

Stops all currently playing instances of the provided cueName.

Source:
Parameters:
Name Type Description
cueName String

unlisten(messageName, bundleNameopt, handlerFunc) → {boolean}

Removes a listener for a message.

Messages are namespaced by bundle. To remove a listener to a message in another bundle's namespace, provide it as the second argument.

Source:
Parameters:
Name Type Attributes Default Description
messageName string

The name of the message.

bundleName string <optional>
CURR_BNDL

The bundle namespace to in which to listen for this message

handlerFunc function

A reference to a handler function added as a listener to this message via NodeCG#listenFor.

Returns:
Type:
boolean
Examples
nodecg.unlisten('printMessage', someFunctionName);

Removing a listener from a message in another bundle's namespace:

nodecg.unlisten('printMessage', 'another-bundle', someFunctionName);