Cantabile JavaScript API Cantabile JavaScript API

  • API Docs for Version: 4.0.0

    • Show:

    Bindings

    Extends EndPoint

    Provides access to Cantabile's binding points.

    Access this object via the bindings property.

    Table of Contents

    Methods

    availableBindingPoints () Promise | BindingPointInfo[][]

    Defined in Bindings.js:160

    Retrieves a list of available binding points

    If Cantabile is running on your local machine you can view this list directly at http://localhost:35007/api/bindings/availableBindingPoints

    Returns:

    Promise | BindingPointInfo[][]:

    A promise to return an array of BindingPointInfo

    Example:

    let C = new CantabileApi();
C.connect();
console.log(await C.bindings.availableBindingPoints());
    close ()

    Inherited from EndPoint: EndPoint.js:55

    Closes the end point and stops listening for events. This method no longer needs to be explicitly called as end points are now automatically closed when the last event listener is removed.
    invoke
    (
    • name
    • value
    • indicies
    • parameter
    )
    Promise

    Defined in Bindings.js:181

    Invokes a target binding point

    If Cantabile is running on your local machine a full list of available binding points is available here

    Parameters:

    • name String

      The name of the binding point to invoke

    • [value] Object optional

      The value to pass to the binding point

    • [indicies] Number[] optional

      The integer indicies of the target binding point

    • [parameter] Object optional

      The parameter value to invoke the target with

    Returns:

    Promise:

    A promise that resolves once the target binding point has been invoked

    Example:

    Set the master output level gain

    C.bindings.invoke("global.masterLevels.outputGain", 0.5);

    Suspend the 2nd plugin in the song

    C.bindings.invoke("global.indexedPlugin.suspend", true, [
        0,     // Rack index (zero = song)
     1      // Plugin index (zero based, 1 = the second plugin)
    ]);

    Sending a MIDI Controller Event

    C.bindings.invoke("midiInputPort.Main Keyboard", new {
    kind: "FineController",
    controller: 10,
    value: 1000,
   });

    Sending MIDI Data directly

    C.bindings.invoke("midiInputPort.Main Keyboard", [ 0xb0, 23, 99 ]);

    Sending MIDI Sysex Data directly

    C.bindings.invoke("midiInputPort.Main Keyboard", [ 0xF7, 0x00, 0x00, 0x00, 0xF0 ]);

    Some binding points expect a "parameter" value. Parameter values are similar to the value parameter in that they specify a value to invoke on the target of the binding. The difference is related to the way they're managed internally for user created bindings. The value comes from the source of the binding whereas a parameter value is stored with the binding itself.

    eg: Load the song with program number 12

    C.bindings.invoke("global.setList.loadSpecificSongByProgramInstant", null, null, 12);
    open ()

    Inherited from EndPoint: EndPoint.js:35

    Opens this end point and starts listening for events. This method no longer needs to be explicitly called as end points are now automatically opened when the first event listener is attached. Use this method to keep the end point open even when no event listeners are attached.
    query
    (
    • name
    • indicies
    )
    Object

    Defined in Bindings.js:253

    Queries a source binding point for it's current value.

    If Cantabile is running on your local machine a full list of available binding points is available here

    Parameters:

    • name String

      The name of the binding point to query

    • [indicies] Number[] optional

      The integer indicies of the binding point

    Returns:

    Object:

    The current value of the binding source

    Example:

    console.log("Current Output Gain:", await C.bindings.query("global.masterLevels.outputGain"));
    untilOpen () Promise

    Inherited from EndPoint: EndPoint.js:137

    Returns a promise that will be resolved when this end point is opened

    Returns:

    Promise

    Example:

    let C = new CantabileApi();
   C.application.open();
await C.application.untilOpen();
    watch
    (
    • name
    • indicies
    • condition
    • callback
    )
    BindingWatcher

    Defined in Bindings.js:276

    Starts watching a source binding point for changes (or invocations)

    If Cantabile is running on your local machine a full list of available binding points is available here

    Parameters:

    • name String

      The name of the binding point to query

    • [indicies] Number[] optional

      The integer indicies of the binding point

    • [condition] Object optional

      The condition for triggering the binding

    • [callback] Function optional

      Optional callback function to be called when the source binding triggers

      The callback function has the form function(resolved, source) where resolved is the resolved display string and source is the BindingWatcher instance.

    Returns:

    BindingWatcher

    Example:

    Using a callback function:

    let C = new CantabileApi();

// Watch a source binding point using a callback function
C.bindings.watch("global.masterLevels.outputGain", null, null, function(value) {
    console.log("Master output gain changed to:", value);
})

   // The "bindings" end point must be opened before callbacks will happen
C.bindings.open();

    Using the BindingWatcher class and events:

    let C = new CantabileApi();
let watcher = C.bindings.watch("global.masterLevels.outputGain");
watcher.on('invoked', function(value) {
    console.log("Master output gain changed to:", value);
});

   // The "bindings" end point must be opened before callbacks will happen
C.bindings.open();

/// later, stop listening
watcher.unwatch();

    Watching for a MIDI event:

    C.bindings.watch("midiInputPort.Onscreen Keyboard", null, {
    channel: 0,
    kind: "ProgramChange",
    controller: -1,
}, function(value) {
    console.log("Program Change: ", value);
})

    Watching for a keystroke:

    C.bindings.watch("global.pckeyboard.keyPress", null, "Ctrl+Alt+M", function() {
    console.log("Key press!");
})