JavaScript in Ableton Live Overview
Table of Contents
- JavaScript in Ableton Live Overview (this page)
- Getting Started
- Real Time MIDI Processing
- The Max Console
- The Live API
- Generating MIDI Clips
NOTE: new versions of all tutorials are available for Max 9's new V8 object. As of December 2024, you
need a license for the standalone version of Max 9 to use it. I will start promoting these new tutorials heavily once
the bundled Max for Live version is updated to Max 9 and everyone has access to the new
v8
object.
Overview
These pages are a series of Max for Live tutorials on using JavaScript to extend Live's functionality with Max's built-in JavaScript engine and its Live API.
The target audience is people who want to "hack" on Ableton Live and who already know how to program in JavaScript (like web developers). If you need help learning Max for Live or want to see what is possible with JavaScript in Live, you'll find useful info here.
Topics covered include:
- Creating a new Max for Live device that uses JavaScript in "Getting Started"
- Altering MIDI notes as they are played in "Real Time MIDI Processing"
- Techniques for understanding and debugging your code in "The Max Console"
- The basics of using "The Live API" in JavaScript
- "Generating MIDI Clips" with the Live API, opening the door to algorithmic composition
The tutorials are designed to be followed in order, where later tutorials assume you know how to do the things from earlier tutorials.
Feel free to jump into "Getting Started" if you are eager to start building. More context and general info is below.
Prerequisites
To follow along, you need Ableton Live Suite (which comes with Max for Live) or Live Standard edition with the Max for Live addon. Most tutorials should work with Ableton Live version 11 or higher. Some tutorials cover the latest features and require the newer versions of Live (or Max). I will point this out when it's a requirement.
Familiarity with JavaScript programming is assumed. You don't need to be an expert, but I assume you can write basic JavaScript with conditionals and loops and functions. You should know basic usage of Live, such as how to control Live's instruments with MIDI clips.
Learning resources
In case you get lost, here are places you can learn more:
Limitations
Let's set some expectations about JavaScript running in Live. Real time music applications like Live need to crunch numbers very quickly, and JavaScript isn't fast enough, at least not the way it runs inside Max and Live. The Max docs talk about how JavaScript can't run in Max's high priority thread:
it is [not] possible to configure JavaScript functions to run in the high-priority thread of Max's scheduler
The main implication is we cannot expect to process an audio stream in real time in JavaScript. You can't build synthesizers or audio FX in JavaScript, at least not in Live.
What can we do? We can respond to any events that occur at a reasonable rate, like 100 times a second (every 10ms) instead of audio rates like 44,100 times a second. We can build tools that respond to human interaction. We can trigger code on a timer. We can process MIDI.
MIDI data occurs at a much slower rate compared to audio samples and it's workable with JavaScript in Live. Since MIDI can control an instrument (and FX), and an instrument generates audio, we can still exert a lot of influence over the sounds that are being generating. There's a lot to explore there. We can make something that responds to what we are playing and alters the notes or generates harmonies. We can get into algorithmic composition and generate entire songs. These tutorials explore some of this territory.
I really do need to emphasize this though:
Even when we're working with something that happens at a suitable rate, like MIDI data, JavaScript cannot be relied on for consistent, accurate timing at all times.
It might be ok most of the time though! This gets back to the quote above from the docs: JavaScript runs in Max's low(er) priority thread. Anything we want to do in Live in the real time signal chain of MIDI data to instruments to audio to effects should ideally be happening entirely in the high priority thread to ensure stable timing with low latency. We prevent this when we introduce JavaScript into this signal path. On a modern, fast computer, most of the time it's going to be ok. But there are so many things that could load up the low priority thread, including potentially anything else on your operating system (read: things outside your control), and problems can happen unexpectedly. For these reasons:
Real time processing in JavaScript in Max for Live should not be relied on for live
performance scenarios (unless timing sloppiness and unpredictable latency is acceptable for the style of music). Extensive testing before live performance usage is highly recommended.
I strongly recommend against trying to make commercial products with JavaScript that do real time processing
in Max for Live. You can't expect it to work perfectly all the time on random people's
computers.
Personally I like to use JavaScript in Live in a composition and production context in a place like my home studio where I am trying out ideas. And almost all of the time, timing with real time processing of MIDI is fine for my needs. Since I'm doing studio work, if there is the occasional glitch or spike in latency, I can edit it manually to fix it or quantize the timing.
One last point. You aren't making some big compromise by choosing to use JavaScript in Live. It's not all bad: JavaScript in Live seems particularly well-suited to build Live MIDI Tools (Generators and Transformers). These are "offline" tools that aren't in the audio signal path in Live, so none of these limitations are a concern in this context. I will try to write more about this later.
JavaScript Engines
Towards the end of 2024, Max started a transition from a very old and slow JavaScript engine to a fast and modern one. This is great news, but it will take time to transition (I'm thinking at least a year).
As of November 2024, Live comes bundled with Max 8 and the old original js
object. Max 9
launched recently and comes with the new JavaScript engine in a new v8
object. People
who own Max 9 as a standalone application can configure Live to use it for Max for Live. I assume most people who use
Max for Live don't own standalone Max 9 and can't use v8
. At some point, Live will be
bundled with Max 9 but that probably won't happen until well into 2025.
For now, these tutorials remain focused on the old js
object. This means most "modern"
JavaScript features cannot be used. More detail below.
If you are using v8
, all of the code here should work, so give it a try.
v8
is intended to be backward compatible. The v8 tutorials will show better/simpler ways
to do things with modern JavaScript syntax and features. Other than differences in the code, the overall structure and
content of the v8 tutorials is planned to be the same.
Max 8 and the Original js
Object
Here's an important note in case you try to run some valid JavaScript code and it gives strange errors. The JavaScript engine in Max is from 2011 and compatible with the ES5 specification of the language. Specifically, it's the JavaScript 1.8.5 version of Mozilla's engine. Since then, many enhancements have been made to the JavaScript language, but unfortunately we can't (directly) use them.
It's hard to make a comprehensive list of modern JavaScript features you can't use in Max for Live. This article talks
about some of
the differences between ES5 and ES6.
Features added in ES6 will not work in Max for Live. Notably, you cannot use let
or const
and must declare
everything with the var
keyword.
If you check a JavaScript feature's compatibility at caniuse.com and it says it works in Firefox version 4, then I believe it will work in Max for Live (and otherwise it probably won't work).
It's possible to work with modern JavaScript syntax and compile it to a version that works in the
js
object via Babel.js or TypeScript. If you pursue that approach, bundle all your
JavaScript into an ES5-compatible single .js
file for use in the Max for Live device. Now, the best path to modern
JavaScript in Live is the v8
object.
Max 9 and the New v8
Object
In October 2024, Max 9 launched with a new JavaScript object called
v8
(and a related object for inline coding called
v8.codebox
). This is based on V8, one of the world's most advanced
JavaScript engines, which powers Node.js and Google's Chrome web browser.
Max's v8
object brings support for all the latest JavaScript syntax and major
performance improvements for JavaScript code execution.
As explained above, as of 2024: Most users of Max for Live can't use v8
yet (unless
they own standalone Max 9), but that will change. These pages are currently being updated to provide v8-specific
versions of all tutorials. In many cases the code is simpler and cleaner, and everything runs faster. It's good stuff,
so check back later, especially once Max 9 is bundled in Ableton Live by default. This may happen in Live 12.2.
I have made updated versions of all these tutorials for v8. Check them out!
Next Steps
Read "Getting Started" to learn how to setup a Max for Live device with JavaScript.