class LiveAPI

A means of communicating with the Live API from JavaScript.

For background information on this functionality, please see the Live API Overview and Live Object Model documents, as well as the Reference pages for live.path, live.object and live.observer objects, which provide the same basic functionality as the LiveAPI object, but from the Max patcher.

Technical note: you cannot use the LiveAPI object in JavaScript global code. Use the live.thisdevice object to determine when your Max Device has completely loaded (the object sends a bang from its left outlet when the Device is fully initialized, including the Live API).

Legacy note: previous versions of the LiveAPI object required the jsthis object's this.patcher property as the first argument. For backward-compatibility, this first argument is still supported, but is no longer necessary.

Beginning with release 6.0 of Max, it is no longer possible to configure JavaScript functions to run in the high-priority thread of Max's scheduler. The LiveAPI object cannot be created or used in the high-priority thread, so users should be sure to use the defer or deferlow objects to re-queue messages to the js object.

Example

var api = new LiveAPI(sample_callback, "live_set tracks 0");
if (!api) {
    post("no api object\n");
    return;
}
post("api.mode", api.mode ? "follows path" : "follows object", "\n");
post("api.id is", api.id, "\n");
post("api.path is", api.path, "\n");
post("api.children are", api.children, "\n");
post('api.getcount("devices")', api.getcount("devices"), "\n");

api.property = "mute";
post("api.property is", api.property, "\n");
post("type of", api.property, "is", api.proptype, "\n");

function sample_callback(args) {
    post("callback called with arguments:", args, "\n");
}

Constructors

new LiveAPI(callback?: Function, path?: string);

Constructs a new instance of the LiveAPI class

Properties

children string[]

An array of children of the object at the current path

id string

The id of the Live object referred to by the LiveAPI object. These ids are dynamic and awarded in realtime from the Live application, so should not be stored and used over multiple runs of Max for Live.

info string read-only

A description of the object at the current path, including id, type, children, properties and functions

mode number

The follow mode of the LiveAPI object. 0 (default) means that LiveAPI follows the object referred to by the path, even if it is moved in the Live user interface.

For instance, consider a Live Set with two tracks, "Track 1" and "Track 2", left and right respectively. If your LiveAPI object's path is live_set tracks 0, the left-most track, it will refer to "Track 1". Should the position of "Track 1" change, such that it is now to the right of "Track 2", the LiveAPI object continues to refer to "Track 1". A mode of 1 means that LiveAPI updates the followed object based on its location in the Live user interface. In the above example, the LiveAPI object would always refer to the left-most track, updating its id when the object at that position in the user interface changes.

patcher Patcher read-only

The patcher of the LiveAPI object, as passed into the constructor

path string

The path to the Live object referred to by the LiveAPI object.

These paths are dependent on the currently open Set in Live, but are otherwise stable: live_set tracks 0 devices 0 will always refer to the first device of the first track of the open Live Set.

property string

The observed property, child or child-list of the object at the current path, if desired

For instance, if the LiveAPI object refers to "live_set tracks 1", setting the property to "mute" would cause changes to the "mute" property of the 2nd track to be reported to the callback function defined in the LiveAPI Constructor.

proptype string read-only

The type of the currently observed property or child

The types of the properties and children are given in the Live Object Model.

type string read-only

The type of the object at the current path

Please see the Live API Overview and Live Object Model documents for more information.

unquotedpath string

The path to the Live object referred to by the LiveAPI object, without any quoting (the path property contains a quoted path)

These paths are dependent on the currently open Set in Live, but are otherwise stable: live_set tracks 0 devices 0 will always refer to the first device of the first track of the open Live Set.

Methods

call

Calls the given function of the current object, optionally with a list of arguments.

call(fn: Function, ...arguments: any[]): void;

get

Returns the value or list of values of the specified property of the current object.

get(property: string): number | number[];

getcount

The count of children of the object at the current path

getcount(child: string): number;

getstring

Returns the value or list of values of the specified property of the current object as a String object.

getstring(property: string): string | string[];

goto

Navigates to the path and causes the id of the object at that path out be sent to the callback function defined in the Constructor. If there is no object at the path, id 0 is sent.

goto(path: string): void;

set

Sets the value or list of values of the specified property of the current object.

set(property: string, value: any): void;