Cantabile JavaScript API Cantabile JavaScript API

  • API Docs for Version: 4.0.0

    • Show:

    Bindings4

    Extends EndPoint

    Provides access to Cantabile's binding points.

    Access this object via the bindings4 property.

    Table of Contents

    Methods

    availableBindingPoints () Promise | BindingPointEntry4[][]

    Defined in Bindings4.js:170

    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 | BindingPointEntry4[][]:

    A promise to return an array of BindingPointInfo

    Example:

    let C = new CantabileApi();
C.connect();
console.log(await C.bindings4.availableBindingPoints());
    bindingPointInfo () Promise | BindingPointInfo4[][]

    Defined in Bindings4.js:191

    Retrieves additional information about a specific binding point

    Returns:

    Promise | BindingPointInfo4[][]:

    A promise to return an array of BindingPointInfo

    Example:

    let C = new CantabileApi();
C.connect();
console.log(await C.bindings4.bindingPointInfo("setList", "loadSongByProgram", false, {}, {}));
    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
    (
    • bindableId
    • bindingPointId
    • value
    • bindableParams
    • bindingPointParams
    )
    Promise

    Defined in Bindings4.js:215

    Invokes a target binding point

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

    Parameters:

    • bindableId String

      The id of the bindable object

    • bindingPointId String

      The id of the binding point to invoke

    • [value] Object optional

      The value to pass to the binding point

    • [bindableParams] Object optional

      Parameters for the bindable object

    • [bindingPointParams] Object optional

      Parameters for the binding point object

    Returns:

    Promise:

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

    Example:

    Set the master output level gain

    C.bindings4.invoke("masterLevels", "outputGain", 0.5);

    Suspend the 2nd plugin in the song

    C.bindings4.invoke("indexedPlugin", "suspend", true, { 
    rackIndex: 0,
 pluginIndex: 1,
    }

    );

    Sending a MIDI Controller Event

    C.bindings4.invoke("midiPorts", "out.Main Keyboard", 65, {
    kind: "Controller",
    controller: 10,
       channel: 0
   });

    Sending MIDI Data directly

    C.bindings4.invoke("midiPorts", "out.Main Keyboard", [ 0xb0, 23, 99 ]);

    Sending MIDI Sysex Data directly

    C.bindings4.invoke("midiPorts", "out.Main Keyboard", [ 0xF7, 0x00, 0x00, 0x00, 0xF0 ]);

    Some binding points expect parameters. 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 parameters are stored with the binding itself.

    eg: Load the song with program number 12

    C.bindings4.invoke("setList", "loadSongWithProgram", null, null, {
        program: 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
    (
    • bindableId
    • bindingPointId
    • bindableParams
    • bindingPointParams
    )
    Object

    Defined in Bindings4.js:288

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

    Parameters:

    • bindableId String

      The id of the bindable object

    • bindingPointId String

      The id of the binding point to query

    • [bindableParams] Object optional

      Parameters for the bindable object

    • [bindingPointParams] Object optional

      Parameters for the binding point object

    Returns:

    Object:

    The current value of the binding source

    Example:

    console.log("Current Output Gain:", await C.bindings4.query("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
    (
    • bindableId
    • bindingPointId
    • bindableParams
    • bindingPointParams
    • callback
    )
    Binding4Watcher

    Defined in Bindings4.js:309

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

    Parameters:

    • bindableId String

      The id of the bindable object

    • bindingPointId String

      The id of the binding point to query

    • [bindableParams] Object optional

      Parameters for the bindable object

    • [bindingPointParams] Object optional

      Parameters for the binding point object

    • [callback] Function optional

      Optional callback function to be called when the source binding triggers

      The callback function has the form function(value, source) where value is the new binding point value and source is the Binding4Watcher instance.

    Returns:

    Binding4Watcher

    Example:

    Using a callback function:

    let C = new CantabileApi();

// Watch a source binding point using a callback function
C.bindings4.watch("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.bindings4.open();

    Using the Binding4Watcher class and events:

    let C = new CantabileApi();
let watcher = C.bindings4.watch("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.bindings4.open();

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

    Watching for a MIDI event:

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

    Watching for a keystroke:

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