Skip to content

Controls & Elements

This is the layer closest to the hardware. Before a button can launch a clip, the framework has to know that "note 36 on channel 1" is a button, how to read it, and how to light it. That is what Elements and logical Controls are for. They sit one level below Components, Layers & Modes: components think in named controls; elements think in MIDI.

Element -- a physical control wrapped as an object

An Element represents one physical control plus its MIDI identity. The common types:

  • ButtonElement -- a pad or button. Sends note/CC on press (and usually release); receives a value to drive its LED.
  • EncoderElement -- a knob. Often relative (endless) or absolute; carries a map mode describing how its value is interpreted.
  • SliderElement -- a fader. Absolute value; on motorised hardware it also receives position feedback.
  • ButtonMatrixElement -- a 2-D grid of buttons addressed by (row, column), the backbone of pad-grid controllers.

Every element knows three things about its MIDI identity:

  • message type -- MIDI_NOTE_TYPE vs MIDI_CC_TYPE (and SysEx for special cases);
  • channel and number -- which note/CC on which MIDI channel;
  • direction -- it both receives (input) and sends (send_value, for LED/motor feedback). An element is bidirectional by nature.

Elements carry no musical meaning. A ButtonElement doesn't know it launches clips; it only knows it is note 36 and how to turn its light on. Meaning is added by the component it is bound to.

Logical Control -- the component side of the wire

Where an Element is the hardware end, a Control is the component end. In the v2/v3 framework a component declares controls declaratively -- ButtonControl, EncoderControl, and the generic control descriptor -- as named slots with behaviour (pressed/released callbacks, value handling) but no fixed hardware. A Layer is what marries a logical Control to a physical Element.

This split is why the same SessionComponent runs on a 4x4 and an 8x8 grid: the component's controls are constant; only the elements bound to them differ.

Value handling and feedback

A few practical concepts you will meet constantly:

  • value range -- buttons are effectively on/off (0 / 127); encoders and sliders span 0..127 (7-bit) or higher with 14-bit/NRPN schemes on some hardware.
  • takeover / pickup -- when a physical knob's position doesn't match the parameter it controls (after a mode change), takeover modes prevent value jumps until you "catch" the current value.
  • feedback / Skin -- the colour or brightness an element shows is usually looked up in a Skin: a named palette mapping logical states ("Session.ClipStopped", "Session.ClipPlaying") to concrete colour values. In v3 the skin is created from the Specification via create_skin. Decoupling state names from raw colour numbers is what lets one component drive RGB pads and single-colour LEDs alike.

Where to look in the reference

Element classes live in the framework packages: _Framework for the original lineage, ableton.v2.control_surface.elements / ableton.v3.control_surface.elements for the modern ones. The per-device elements module in a controller's package shows how that specific hardware instantiates them (which notes, which channels, which colour map). Open a device's elements and colors/skin modules in the API Reference to see the concrete wiring.

See also: Components, Layers & Modes for how elements get bound, and MIDI message flow for what travels through them.