ControlSurface

A ControlSurface can be reached either directly by the root path control_surfaces N or by getting a list of active control surface IDs, via calling get control_surfaces on an Application object.
The latter list is in the same order in which control surfaces appear in Live's Link/MIDI Preferences. Note the same order is not guaranteed when getting a control surface via the control_surfaces N path.

A control surface can be thought of as a software layer between the Live API and, in this case, Max for Live. Individiual controls on the surface are represented by objects that can be grabbed and released via Max for Live, to obtain and give back exclusive control (see grab_control and release_control). In this way, parts of the hardware can be controlled via Max for Live while other parts can retain their default functionality.

Additionally, Live offers a special MaxForLive control surface that has a register_midi_control function. Using this, Max for Live developers can set up entirely custom control surfaces by adding and grabbing arbitrary controls.

Canonical Path

control_surfaces N

Functions

get_control

Parameter: name
Returns the control with the given name.

get_control_names

Returns the list of all control names.

grab_control

Parameter: control
Take ownership of the control. This releases all standard functionality of the control, so that it can be used exclusively via Max for Live.

grab_midi

Forward MIDI messages received from the control surface to Max for Live.

register_midi_control

Parameters:
name [symbol]
status [int]
number [int]

(MaxForLive control surface only) Register a MIDI control defined by status and number. Supported status codes are 144 (note on), 176 (continuous control) and 224 (pitchbend).
Returns the LOM ID associated with the control.
Once a control is registered and grabbed via grab_control, Live will forward associated MIDI messages that it receives to Max for Live. Max for Live can send values to the control (e.g. to light an LED) by calling send_value on the control object.

release_control

Parameter: control
Re-establishes the standard functionality for the control.

release_midi

Stop forwarding MIDI messages received from the control surface to Max for Live.

send_midi

Parameter: midi_message [list of int]
Send midi_message to the control surface.

send_receive_sysex

Parameters:
sysex_message [list of int]
timeout [symbol, int]
Send sysex_message to the control surface and await a response.
If the message is followed by the word timeout and a float, this sets the response timeout accordingly. The default timeout value is 0.2.
If the response times out and MIDI has not been grabbed via grab_midi, it's not forwarded to Max for Live. If MIDI has been grabbed via Max for Live, received messages are always forwarded, but the timeout is still reported.