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.

Parameters:
Name Type Description
bundle object

The bundle object to build an API instance from.

Source:

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`!
}

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.

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

getDialog(name, bundleopt) → {object}

Browser only
Returns the specified dialog element.

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.

Source:
Returns:
Type
object

getDialogDocument(name, bundleopt) → {object}

Browser only
Returns the specified dialog's iframe document.

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.

Source:
Returns:
Type
object

getSocketIOServer()

Extension only
Gets the server Socket.IO context.

Source:

listenFor(messageName, bundleNameopt, handler)

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.

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

handler function

The callback fired when this message is received.

Source:
Examples
nodecg.listenFor('printMessage', function (message) {
    console.log(message);
});

Listening to a message in another bundle's namespace:

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

log()

Provides access to 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.

Parameters:
Name Type Attributes Description
cueName String
opts Object <optional>
Properties
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.

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

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.

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.

Source:
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', function(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.

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.

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

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

myRep.on('change', function(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)

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.

If a message is sent from a client (graphic or dashboard panel), to the server (an extension), it may provide an optional callback called an acknowledgement. Acknowledgements will not work for client-to-client nor server-to-client messages. Only client-to-server messages support acknowledgements. This restriction is a limitation of Socket.IO.

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 callback to handle the server's acknowledgement message, if any.

Source:
Examples

Sending a normal message:

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

Sending a message and calling back with an acknowledgement:

// bundles/my-bundle/extension.js
module.exports = function(nodecg) {
    nodecg.listenFor('multiplyByTwo', function(value, callback) {
         callback(value * 2);
    });
}

// bundles/my-bundle/graphics/script.js
nodecg.sendMessage('multiplyByTwo', 2, function(result) {
    console.log(result); // Will eventually print '4'
});

sendMessageToBundle(messageName, bundleName, dataopt, cbopt)

Sends a message to a specific bundle. Also available as a static method. See NodeCG#sendMessage for usage details.

Parameters:
Name Type Attributes Description
messageName string

The name of the message.

bundleName string

The name of the target bundle.

data mixed <optional>

The data to send.

cb function <optional>

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

Source:

stopAllSounds()

Stops all currently playing sounds on the page.

Source:

stopSound(cueName)

Stops all currently playing instances of the provided cueName.

Parameters:
Name Type Description
cueName String
Source: