Skip to content

v2 vs v3 framework

Modern Live ships two generations of the control-surface framework side by side: ableton.v2.control_surface and ableton.v3.control_surface (with the older _Framework beneath them for legacy scripts). They share the vocabulary from Components, Layers & Modes; the difference is how much you write by hand versus declare.

v2 · _Framework imperative, you wire it by hand v3 · ableton.v3 declarative, you declare it __init__ builds everything create each Element by hand create each Component build Layer(...) wirings wire Modes explicitly enable / disable in code → a lot of code in the device script write a ControlSurfaceSpecification num_tracks / num_scenes / element class component_map = { ... } a thin setup() for extras the base ControlSurface builds it behaviour inherited, not written → the device script looks almost empty

The short version

  • v2 is the imperative rewrite: you create components, build layers, and wire modes explicitly in code, mostly inside __init__.
  • v3 is the declarative layer on top: you describe the surface in a ControlSurfaceSpecification -- counts, element type, skin, component map -- and the base ControlSurface assembles most of it for you. You only write the device-specific parts in setup().

If a device page in the reference is mostly a Specification class with little code, it is a v3 script. If it builds components by hand in __init__, it is v2 (or _Framework).

What v3 adds

  • ControlSurfaceSpecification -- one declarative object holding num_tracks, num_scenes, the element class, the skin factory, the component map, identity/SysEx bytes, and feature flags. Reading it tells you almost everything a controller does.
  • create_skin -- the skin (state-name -> colour palette) is produced from the specification, so colour handling is configuration rather than code.
  • a richer component library under ableton.v3.control_surface.components, designed to be enabled and wired from the specification with minimal glue.
  • ElementsBase -- a declarative way to define the hardware's elements as a group.

The net effect: a v3 device script is short because the base class does the assembly. The behaviour you're looking for is therefore in the v3 base classes, not the device -- the recurring theme of this whole documentation.

What stays the same

The core ideas are unchanged across generations: Elements wrap hardware, Components hold behaviour, Layers wire them, Modes swap them, listeners drive feedback, and a MIDI map routes messages. Learning one generation transfers almost entirely to the other; only the assembly style and some class names differ.

Migration notes for script authors

  • A v2 script ported to v3 typically shrinks: hand-built component/layer code collapses into a Specification plus a small setup().
  • Watch for renamed classes: several v2 names have v3 equivalents under ableton.v3.control_surface. Use the What changed page and the per-version API Reference to map them.
  • Skins move from imperative colour assignment to the create_skin factory.