ricardomatias / ableton-live

A library for communicating with Live via WebSockets, works both in NodeJS and in the Browser.

Ableton Live

A library for communicating with Ableton Live via WebSockets, works both in Node and in the Browser.

Requirements

• Ableton Live 11
• Max 4 Live

Installation

1. Install package

npm install --save ableton-live

2. Drag and drop external/LiveAPI.amxd to any track in Ableton Live (f.ex, Master Track)

3. Done!

Usage

Browser

import { AbletonLive } from 'ableton-live';

NodeJS

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

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

Example

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();

Documentation

Found at https://ricardomatias.net/ableton-live/

Credits

A loose fork of ableton-js, which was a great source of inspiration on how to approach handling Live's Object Model.

Development

When not receiving try running sudo lsof -i :send_port_number and make sure only Max is using it.

ableton-live's Issues

Missing function (delete_clip): How to call?

I think there's a function definition missing in the Tracks class: delete_clip.
So I was wondering if I could call it myself. The .call function on the Tracks-object is protected, and if I want to use the .call function on the AbletonLive-object, I need the track's path, which is also protected.
Is there another way to do this? There are other functions that aren't defined in this package either, so a way to call them "by hand" would be great.

Send close frame to clients when server is closed

I want my client to be notified when the server is closed (port changed). I was able to get the expected message by calling ws.end() on each client after this line:

maxApi.addHandler('port', async (port) => {
	try {
		if (uws) {
			console.log('Attempting to close server..');

			if (listenSocket) uWS.us_listen_socket_close(listenSocket);
			
			SOCKETS.forEach((ws, i) => ws.end());
		}

		console.log('Creating server..');
		
		....

As uWebSockets explains, ws.end() does:

Send websocket close frame, emit close event, send FIN if successful. Will not append a close reason if code is 0 or 1005.

Migrate WebSockets server

to https://github.com/uNetworking/uWebSockets.js

is it possible to create a clip envelope?

Thanks for this library, I've had some fun using it! What I'm wondering is can I use it to assign an envelope to a clip - for example, I would like to create a panning envelope programmatically.

Issues observing more than one property

Hi there, great work on this library! I'm just having trouble observing more than one properties. E.g. given an Ableton song with 3 tracks.

const live = new AbletonLive();

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

    const tracks = await live.song.children("tracks");

    await tracks[0].observe("name", (v) => {
      console.log(v);
    });

    await tracks[1].observe("name", (v) => {
      console.log(v);
    });

    await tracks[2].observe("name", (v) => {
      console.log(v);
    });

  } catch (error) {
    console.error(error);
  }
};

main();

The websockets entry looks like this:

{
  "event": "callback",
  "result": {
    "data": "\"track name\"",
    "listeners": [
      "BOapnHqy09vhRLS-fLAbN",
      "Vx-E_k3Z7nVJ00_oCCcc0",
      "bYGH2h2OFGq7SFMw0OUuu"
    ]
  }
}

which suggests it's targeting all the callback for a single track name update.

I would expect each different track to log when their name updates but it only seems to factor in the last item that's observed and this overrides all the other callbacks and so the same name is printed three times in this case.

It could be a case of not using the api correctly though.

Re-factor Clip -> removeSelectedNotes

• Add call to getSelectedNotes
• Switch to removeNotesById

Issues with Ableton 11.3.20

Hi - I was happily using this on Ableton 11.3.13, but it seems to have stopped working now that I am on version 11.3.20 (I double checked this on a different machine that was running .13, and later upgraded that one to .20 as well, and I replicated the failure)

The error I'm getting is that track.volume() crashes with TypeError: Cannot read properties of undefined (reading 'id'), but that seems a symptom of overall funkiness: all track.id and track.name are 0, and live.song.children("track") only returns midi tracks.

So something is quite off somewhere - I went looking for the changelog, and the most relevant change seems to be the "Updated the bundled Max build to version 8.5.6", so maybe something in Max changed?

I know nothing about Max so I am not sure where to look for more info on how to debug this, but I'm happy to assist.

Possible documentation and/or LiveAPI.amxd issue

Hi there,

Great library! I think I'm missing something trivial here, but I found a few issues with the Read ME page and possibly the LiveAPI.amxd file as well.

I tried the 3 simple steps mentioned with Ableton running, but the very first connection is refused followed by the timeout after the default 20 attempts. No other apps are using the port from what I can tell.

Clicking the arrow button on the plugin in Ableton seems to turn green, but that's it. The colour toggles back immediately after switching back to the console.

Clicking Restart on the plugin crashes Ableton.

Any ideas on what I'm missing to create a successful connection? I used the example code as written in the READ ME.

Expose Track.getClipSlots()

I find myself doing track.children("clip_slots") to obtain the full list of clip slots, including the empty ones.
What about exposing a Track.getClipSlots() method? Maybe in the wip branch, where I see you're adding new useful things.

would you be able a way to observe the start of a clip playing?

I want to do something immediately when some clip started to play.
would you be able a way to observe the start of a clip playing?

i tried to use 'play_position' but it starts little bit after 0ms

Get the playing position efficiently

AFAIK the only way to get the playing position with Live API is through the Song.current_song_time property. It's an observable property (and it's listed inside SongObservableProperties) but I fear that it will overload the websocket sending continous updates.

For this (and other use cases) it would be useful to have the ability to observe "custom signals" that could be sent by the Live API device itself.

I was considering to implement an approach similar to "observe" that ableton-live already provides:

• the client asks to observe a custom property ("observecustom" message?). A callback is stored as usual client side
• the device sends messages for the custom properties (signlas) which the socket might broadcast to any client, or only to clients that requested to observe the custom property

Basically reuse the same mechanism, but without actually using the LiveAPI.

Example for my use case:

• the device has a plugsync~. The outlets are either sent individually or comined in a single message which is sent to the node.script
• the websocket (for simplicity) boradcasts the message for the custom property (let's call it playhead)
• a client code which asked to observe the playhead by registering it's own callback, receive the playhead message

This way:

• we can extend the Live API device (and maybe use it as a bpatcher in the future?) beyond the Live API itself.
• we can leverage other Max 4 Live devices that might be optimized or already designed for specific purposes (like plugsync~)

@ricardomatias makes sense? Do you suggest alternative solutions?

Add .clone to Note

Copy every property besides the ID to a new Note object

LiveAPI.amxd crashes ableton 11.3.20

As soon as I drop the LiveAPI.amxd into ableton or, use the file browser to bring it in, ableton crashes immediately.