Skip to content

Custom module#

Writing a custom module#

Using the -c / --custom-module command-line switch, users can load a javascript file to tune the way Open Stage Control behaves regarding osc.

// Do whatever you want, initialize some variables, declare some functions, ...

module.exports = {

    init: function(){
        // this will be executed once when the osc server starts

        // Filter incoming osc messages

        var {address, args, host, port} = data

        // do what you want

        // address = string
        // args = array of {value, type} objects
        // host = string
        // port = integer

        // return data if you want the message to be processed
        return {address, args, host, port}


        // Filter outgoing osc messages

        var {address, args, host, port, clientId} = data

        // same as oscInFilter

        // return data if you want the message to be and sent
        return {address, args, host, port}


Available globals#

The module is executed in a restricted context, only a few globals are available :


Event Emitter, useful for monitoring the events sent by the different clients. Event names can be found in callbacks.js, callbacks are called with 2 arguments: data (object) and client (object: {address, id})

receive(host, port, address, ...args, options)#

Send osc/midi message to connected clients. host and port can be specified to simulate a specific origin for the message.

  • host (optional): string ip address, valid hostname or "midi"
  • port (optional): integer port number or string midi device name
  • address: osc address
  • args: value or {type: "OSC_TYPE_LETTER", value: VALUE} object
  • options (optional): set to {clientId: id} to define which client receives the message (where id is the client's id as retreived from app events or oscOutFilter)

send(host, port, address, ...args)#

Send osc/midi to a target.

Returns specified server option. name must be the option's long name without the leading dashes (ie: "send", not "s")


Returns the server's http addresses.


Array containing the extra options passed to --custom-module after the filename


Loads a json file (path is relative to the custom module location)

saveJSON(path, object)#

Saves an object/array to a json file (path is relative to the custom module location)


Load another javascript module. Returns the value of module.exports defined in this module. If path is a relative path, it will be resolved against its parent module's path. See Managing Big Modules

Other javascript globals#

  • console
  • setTimeout
  • clearTimeout
  • setInterval
  • clearInterval


Custom modules (including submodules loaded with require()) are reloaded automatically when they are modified. Upon reload, timers (setTimeout and setInterval) and event listeners (added to the  app object) are reset.