ableton-js

Ableton.js communicates with the MIDI Script via UDP using JSON objects.

Command Structure

A command payload includes:

• uuid: A unique command ID for associating requests and responses.
• ns: The command namespace (e.g., song).
• nsid: The namespace ID (e.g., to address a specific track).
• name: The command name (e.g., get_prop).
• args: Arguments for the command.
• etag: An MD5 hash used for caching.
• cache: Boolean indicating if the plugin should use ETag caching.

Response Structure

The script responds with:

• data: The return value (JSON-compatible).
• event: Either result or error.
• uuid: The original command UUID.

Caching Mechanism

To reduce UDP bandwidth, the library uses an LRU cache and ETags. If the plugin determines the data hasn't changed, it returns a placeholder object: { "__cached": true }.

To use ableton-js, you must install a corresponding MIDI Remote Script into Ableton Live.

1. Copy the midi-script folder from the ableton-js repository to your Ableton Remote Scripts folder.
2. Rename the folder to AbletonJS.
3. The Remote Scripts folder is typically located at: ~/Music/Ableton/User Library/Remote Scripts.
4. Open Ableton Live and add AbletonJS to your list of available Control Surfaces in Preferences.

If you are on macOS and have forked the repository, you can automate this using yarn commands:

• yarn ableton10:start (for Ableton 10)
• yarn ableton11:start (for Ableton 11)

These commands will copy the folder, open Ableton, and stream logs to your terminal.

The TrackView namespace provides access to several properties that can be retrieved, observed, or set.

Gettable/Observable Properties:

• is_collapsed: A boolean indicating if the view is collapsed.
• selected_device: Returns the RawDevice currently selected in the track view. This is automatically transformed into a Device instance.

Settable Properties:

• device_insert_mode: Set the insertion mode using DeviceInsertMode (Default, Left, or Right).
• is_collapsed: Set whether the view is collapsed.

The Ableton instance provides several high-level namespaces to interact with different parts of Ableton Live. Instead of sending raw commands, use these specialized objects:

• ableton.song: For interacting with the current song/project.
• ableton.session: For session-related controls (e.g., session ring).
• ableton.application: For application-level settings and state.
• ableton.internal: For low-level or internal Ableton properties.
• ableton.midi: For MIDI-related operations.

To use ableton-js, instantiate the Ableton class and call the start() method. This establishes a UDP connection to the Ableton Remote Script. You can optionally provide AbletonOptions to configure port files, heartbeats, timeouts, and caching.

If start() is called while the client is already in a starting or started state, it will return the existing connection promise instead of attempting to restart.

import { Ableton } from 'ableton-js';

const ableton = new Ableton({
  heartbeatInterval: 2000,
  commandTimeoutMs: 2000,
  disableCache: false
});

try {
  await ableton.start();
  console.log('Connected to Ableton!');
} catch (err) {
  console.error('Failed to connect:', err);
}

The following JSON structures define the wire format for commands and responses used in the UDP protocol.

// Command payload
{
  "uuid": "a20f25a0-83e2-11e9-bbe1-bd3a580ef903",
  "ns": "song",
  "nsid": null,
  "name": "get_prop",
  "args": { "prop": "current_song_time" },
  "etag": "4e0794e44c7eb58bdbbbf7268e8237b4",
  "cache": true
}

// Standard response
{
  "data": 0.0,
  "event": "result",
  "uuid": "a20f25a0-83e2-11e9-bbe1-bd3a580ef903"
}

// Cached response (data matches ETag)
{
  "data": { "__cached": true },
  "event": "result",
  "uuid": "a20f25a0-83e2-11e9-bbe1-bd3a580ef903"
}

// Response with new data and ETag
{
  "data": { "data": 0.0, "etag": "4e0794e44c7eb58bdbbbf7268e8237b4" },
  "event": "result",
  "uuid": "a20f25a0-83e2-11e9-bbe1-bd3a580ef903"
}

The ApplicationView class allows you to manipulate and inspect the visible parts of the Ableton Live interface, such as the Session/Arranger views, the Browser, and Detail views. You can show, hide, focus, or scroll these views using specific commands.

import { Ableton } from "../index.js";
import { ApplicationView, NavDirection } from "./ns/application-view.js";

const ableton = new Ableton();
const appView = new ApplicationView(ableton);

// Example: Focus the Arranger view
await appView.focusView("Arranger");

// Example: Scroll the Session view up
await appView.scrollView("Session", NavDirection.Up);

// Example: Check if the Browser is visible
const isBrowserVisible = await appView.isViewVisible("Browser");

The MidiMessage class is used to wrap RawMidiMessage data and provide structured access to MIDI commands and parameters. You can convert a generic MidiMessage into specific types like MidiCC or MidiNote using helper methods.

• toCC(): Converts the message to a MidiCC object. Throws if the command is not MidiCommand.ControlChange.
• toNote(): Converts the message to a MidiNote object. Throws if the command is not MidiCommand.NoteOn or MidiCommand.NoteOff.

import { MidiMessage, MidiCommand } from 'ableton-js/ns/midi';

// Example: Parsing a raw message (e.g., from an observable property)
const raw = { bytes: [176, 7, 127] }; // CC, Controller 7, Value 127
const msg = new MidiMessage(raw);

if (msg.command === MidiCommand.ControlChange) {
  const cc = msg.toCC();
  console.log(cc.controller, cc.value);
}

Use the following methods to control how a clip plays or how you navigate through it:

• fire(): Starts playing the clip.
• stop(): Stops playing the clip.
• setFireButtonState(state: boolean): Directly sets the fire button state (supports all launch modes).
• movePlayingPos(amount: number): Jumps forward or backward by a relative number of beats (only works if the clip is playing).
• scrub(position: number): Starts scrubbing from a specific beat position. Continue scrubbing until stopScrub() is called.
• stopScrub(): Stops the current scrubbing operation.

await clip.fire();
await clip.movePlayingPos(2); // Jump forward 2 beats
await clip.scrub(0);           // Start scrubbing from beat 0
await clip.stopScrub();        // Stop scrubbing