The LiveAPI Object

The LiveAPI object provides a means of communicating with the Live API functions 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.

LiveAPI Constructor

     api = new LiveAPI([callback], [path]/[id]);

callback is an optional JavaScript function. This function will be called when the LiveAPI object refers to a new object in Live (if the LiveAPI object's path change, for instance), or when an observed property changes. path refers to the object in Live "pointed to" by the LiveAPI object (e.g. "live_set tracks 0 devices 0"). Alternately, a valid id can be used to refer a LiveAPI object to an object in Live.

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.

LiveAPI Properties

id (Number, get/set)

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.

path (String, get/set)

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.

children (Array, get)

An array of children of the object at the current path.

mode (Number, get/set)

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.

type (String, get)

The type of the object at the current path. Please see the Live API Overview and Live Object Model documents for more information.

info (String, get)

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

property (String, get/set)

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, get)

The type of the currently observed property or child. The types of the properties and children are given in the Live Object Model.

patcher (Patcher object, get)

The patcher of the LiveAPI object, as passed into the Constructor.

LiveAPI Methods

getcount (child)

The count of children of the object at the current path, as specified by the child argument.

goto (path)

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.

get (property)

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

getstring (property)

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

set (propertyvalue)

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

call (function(arguments...))

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

Sample Code

  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");
  }

The LiveAPI Object and the Scheduler

Although it is possible to configure JavaScript functions to run in the high-priority thread of Max's scheduler (using the immediate property, as documented here), the LiveAPI object cannot be created or used in this thread. Users should therefore ensure that the immediate property is disabled in JavaScript functions which communicate with the Live API (or use the defer or deferlow objects to re-queue messages to the js object to the low-priority thread). The js object will generate an error in the Max window if attempts are made to create, or use previously created, LiveAPI objects outside of Max's low-priority (GUI) thread.