JS Live API » #1 Setup

This is the 1st of a series of articles about hacking on Ableton Live with JavaScript. These articles assume you own Ableton Live 9 Suite and are comfortable coding JavaScript.

This article explains the setup to run JavaScript code inside Live.

If you are already familiar with this setup, you can skip ahead to the next article.

Summary of Steps

  1. Add a Max Midi Effect device and edit it
  2. Add a "js your-filename.js" object to the Max device
  3. Lock the Max device and double-click the js object to open the JavaScript editor
  4. Save the JavaScript file
  5. Save the Max device in the same folder as the JavaScript file
  6. Open the Max Window for logging debug info
  7. Start coding
  8. Save the JavaScript file to run your code

Detailed Steps

We're going to interact with Live directly through the LiveAPI, so our Max device will not alter the incoming signal. I usually use a MIDI effect in this situation, but you could use an audio effect. The important thing is the MIDI/audio input is passed directly to the MIDI/audio output. These instructions assume we're using a MIDI effect.

Find "Max Midi Effect" under the Max for Live section of the Live browser inside the "Max MIDI Effect" folder. Drag it to a MIDI track (I recommend using a dedicated track to stay organized), then click its edit button. Max will launch, and after a few moments the Max Editor window will appear. First we'll add a Max JavaScript object to the device.

Double click in some empty space in the Max Editor window, and the Max Object Explorer will appear (if it doesn't, make sure the device is unlocked by using the lock button in the lower left). Type "javascript" into the search box of the Object Explorer. Under the languages category we see "js" (if not, select "Show All"). Drag "js" into your device and type in a filename, so we have an object that looks like "js your-filename.js".

Pro tip: Learn Max keyboard shortcuts. If you type "n" in an unlocked device, it will add an object. Then you can type "js your-filename.js" and hit enter to create a js object.

Lock the device with the lock button in the lower left. Double-click the js object to open the JavaScript editor.

At this point we could start coding, but let's take the time to choose a name for our files and save them. This way we can easily come back later for another coding session. Use the usual File → Save menu, or hit command+S (ctrl+S on Windows).

The JavaScript save dialog prefills the your-filename.js that you typed into the Max object. The filenames need to match, so go ahead and save it with that name. The save location will probably be the "Max MIDI effect" folder of your Live library. This is fine, but you may want to create a subfolder for your JavaScript projects.

Once you've saved the JavaScript, close the JavaScript editor and save the Max device. The Max device (.amxd) file needs to be saved to the same folder as the JavaScript. I suggest you use the same filename for both files, so you know which devices and scripts go together.

Now we need to close the Max device editor and reopen it to workaround a bug in Max (otherwise Max can't locate the JavaScript file we just created). Once the Max Editor is open again, lock the device and double click the js object to open the JavaScript editor again too.

Finally, open the Max window via the Window → Max Window menu. When we print out debugging info, it will appear here.

Testing it Out

Every time you save the code in Max's JavaScript editor, it will run. As a quick test, try this simple program

  post("Hello World!");

You should see Hello World! in the Max window, like in this screenshot:

Next Steps

Alright! Now you're ready to write JavaScript programs inside Ableton Live. In the next article, we'll learn how to set some useful utility code to help us debug our scripts.

Adam Murray, April 2014
contact the author...