ableton-live

To use this library, you must first install the package and then configure Ableton Live to allow WebSocket communication.

1. Install the package

npm install --save ableton-live

2. Configure Ableton Live

Drag and drop the file external/LiveAPI.amxd (found in the package directory) onto any track in Ableton Live (for example, the Master Track). This enables the WebSocket server required for communication.

In a browser environment, you can import the AbletonLive class directly from the package.

import { AbletonLive } from 'ableton-live';

When using the library in Node.js, you must first polyfill the WebSocket API using a library like ws, as Node does not provide a native WebSocket implementation compatible with the library's requirements.

// polyfill for a browser API compatible WebSocket
if (process) {
    global.WebSocket = require('ws');
}

import { AbletonLive } from 'ableton-live';
// or
const { AbletonLive } = require('ableton-live');

The Song class is the top-level entry point for interacting with an Ableton Live project (Live Set). It provides access to the project's hierarchy, including the master track, audio/MIDI tracks, return tracks, scenes, and cue points.

Key capabilities include:

• Navigation: Accessing tracks, scenes, and cue points.
• Playback Control: Starting/stopping playback, triggering scenes, and controlling transport (undo/redo, tap tempo, etc.).
• Project Modification: Creating, duplicating, or deleting tracks and scenes.
• Properties: Reading and setting song-wide properties like tempo, quantization, and loop settings.

The Clip class provides an interface to interact with musical clips in Ableton Live, whether they are in Session View or Arrangement View. It supports both MIDI and Audio clips, offering methods for note manipulation, playback control, and audio-specific properties like warping and gain.

import { Clip } from './lib/Clip';

// Note: Clip instances are typically obtained through higher-level objects like Tracks or Scenes
// rather than being instantiated directly by the user.

If you are unable to receive data from Ableton Live, ensure that no other process is occupying the port used by Max/Live. You can check for active processes on a specific port using lsof:

sudo lsof -i :<port_number>

Ensure that only Max is using the designated port.

sudo lsof -i :send_port_number

The following example demonstrates how to connect to Ableton Live, navigate the song structure, and retrieve MIDI note information from clips on the first track.

1. Instantiate AbletonLive.
2. Call await live.connect() to establish the connection.
3. Use live.song.children('tracks') to access tracks.
4. Use track-specific methods like getClips() and clip-specific methods like getNotes() to traverse the Live Object Model.

import { AbletonLive } from 'ableton-live';

const live = new AbletonLive();

const main = async () => {
    try {
        await live.connect();

        const tracks = await live.song.children('tracks');
        const clips = await tracks[0].getClips();
        const notes = await clips[0].getNotes();

        notes.forEach(note => console.log(note.pitch));
    } catch (error) {
        console.error(error);
    }
};

main();

When instantiating the AbletonLive class, you can provide an AbletonLiveOptions object to specify the connection details for the Max4Live server.

Available options:

• host: The hostname of the server. Defaults to '127.0.0.1'.
• port: The port number the server is listening on. Defaults to 9001.
• logRequests: If set to true, every request sent to and received from Ableton Live will be logged to the console. Defaults to false.

const client = new AbletonLive({
  host: '127.0.0.1',
  port: 9001,
  logRequests: true
});

The ableton-live package provides a structured API to interact with Ableton Live. The main entry point exports several core classes and types that represent the hierarchy of an Ableton Live session.

Key modules include:

• AbletonLive: The primary interface for interacting with a running instance of Ableton Live.
• AbletonLiveOffline: An offline/mock implementation for testing or headless environments.
• Song: Represents the top-level container for a session.
• Track, Clip, ClipSlot, Scene: Represent the arrangement and session view components.
• Device, DeviceParameter, MixerDevice: Represent instruments, effects, and mixer controls.
• Note: Represents MIDI note data.

The ClipSlot class allows you to interact with individual clip slots within Ableton Live tracks. You can retrieve the current clip, create new clips, delete clips, duplicate clips to other slots, and control playback (fire/stop).

// Assuming 'clipSlot' is an instance of ClipSlot

// Get the current clip
const clip = await clipSlot.clip();

// Create a new clip with a specific length (e.g., 8 beats)
const newClip = await clipSlot.createClip(8);

// Delete the existing clip
await clipSlot.deleteClip();

// Duplicate the current clip to a specific target slot index
await clipSlot.duplicateClipTo(5);

// Trigger/Play the clip
await clipSlot.fire();

// Stop the clip
await clipSlot.stop();