Glossary

The framework reuses a small vocabulary everywhere, often under slightly different names between _Framework, ableton.v2 and ableton.v3. Learn these once and the reference stops looking foreign. Terms are grouped by what they are, not alphabetically.

The script and its host

ControlSurface, the root object of a Remote Script. Live instantiates exactly one per enabled controller. It owns the MIDI ports, builds the components, and runs the lifecycle. Your device class subclasses it. In v3 most of its work is inherited rather than written.

ControlSurfaceSpecification (v3), a declarative class that describes a controller: number of tracks/scenes, which element class to use, the skin, and the component_map. The base ControlSurface reads it and builds the script for you. This is why modern device scripts look almost empty.

c_instance, the opaque bridge object Live hands to create_instance. Every MIDI send and every Live Object Model call ultimately travels through it. You pass it to the base class and otherwise never touch it.

create_instance, the single entry point Live looks for in a script's __init__.py. It returns your ControlSurface instance.

The two stacks

Live Object Model (LOM), the object tree representing the Live set: Application, Song, Track, ClipSlot, Clip, Device, DeviceParameter, MixerDevice. Implemented in C++ and exposed as the built-in Live module. You read properties, call functions, and observe changes.

listener / observer, a callback you register on a LOM property (song.add_tempo_listener(cb)). It fires whenever the value changes. Observation is what makes hardware feedback possible; the framework is event-driven, never polled.

The framework building blocks

Element (a.k.a. control), wraps one physical control and its MIDI identity: ButtonElement, EncoderElement, SliderElement. Knows its message type (MIDI_NOTE_TYPE / MIDI_CC_TYPE), channel and number, and how to send a value back for LED or motor feedback. Elements are pure I/O; they carry no musical meaning.

ButtonMatrixElement, a 2-D grid wrapper around many button elements, addressed by (row, column). The backbone of pad grids and Session views.

Component, a unit of behaviour: SessionComponent (the clip grid), MixerComponent, TransportComponent, DeviceComponent, a step sequencer. A component talks to the LOM and exposes named controls (play_button, stop_button) that get wired to physical elements. Components can be enabled/disabled and nested.

Layer, the wiring between a component's named controls and physical elements: Layer(play_button=button_1, stop_button=button_2). Separating behaviour (component) from wiring (layer) is what lets the same component be driven by different hardware and re-bound when modes change.

Mode / ModesComponent, swaps which layers/components are active at runtime. "Hold Shift and the grid launches scenes instead of clips" is a mode change: same buttons, a different layer applied. Modes are how one controller does ten jobs.

Appearance and mapping

Skin / SkinColor, the named colour palette a script uses for feedback. Components ask for a colour by name (e.g. Session.ClipStopped) and the skin maps it to the actual MIDI value the hardware expects. Swapping skins re-themes a controller without touching component code.

MIDI map, the table the framework builds that says which incoming MIDI message reaches which element. Built once after construction and rebuilt when mappings change. Messages not in the map are ignored (or forwarded, see below).

forwarding, telling the framework to pass a raw MIDI message straight to your script's handler instead of routing it to an element. Used for controls that need custom handling.

Generations

_Framework, the original imperative framework (Live 9/10/11). You build and wire everything by hand. Still present in Live 12 and still loads.

ableton.v2.control_surface, the Live 10+ rewrite that formalised the control / element / component / layer model.

ableton.v3.control_surface, the current declarative framework (Live 11/12 devices). You declare a Specification; the base class assembles the script. See v2 vs v3.

Beyond scripts: Max for Live

Not every controller or generative idea needs a Remote Script. Max for Live reaches much of the same Live Object Model from live.object / live.path, in a visual environment, without Python or decompilation. Cycling '74 documents that side officially. For a guided, hands-on path there are two books I wrote on it: The Art of Max for Live (English) and L'art de Max for Live (French).