GainStage Batch — Ableton Extensions SDK extension

GainStage Batch is an Ableton Extensions SDK tool, not a Max for Live device. It is an offline Arrangement View workflow action for Live 12 Suite 12.4.5 beta or later. A single selection may include both audio and MIDI tracks. Audio tracks are rendered pre-FX, measured for maximum sample value, and receive a trim inside a Gain Stage rack at the first device position. MIDI tracks receive a Gain Stage rack appended after their existing devices so it operates on the audio output of the track’s instrument.

MIDI-track measurement is experimental and unsupported: the SDK's public render API is typed to accept only AudioTrack, but the underlying native call it wraps accepts any track handle. The extension deliberately bypasses that type restriction to attempt rendering a MIDI track's post-instrument audio the same way it does for audio tracks. On a Live/SDK build where that render succeeds, the MIDI track gets a real, calculated trim like an audio track. Where it doesn't (the officially documented case), the extension falls back to the same rack at a neutral, 0.0 dB Utility, exactly as before. This bypass could stop working, or behave inconsistently, on a different SDK release — treat any measured MIDI result as unverified.

A Gain Stage rack is a built-in Live Audio Effect Rack containing exactly one Utility. The Extensions SDK has no device-rename API — only tracks, clips, take lanes, scenes, and cue points can be renamed — so the rack cannot be labeled "Gain Stage" in Live's own UI; it shows as the default "Audio Effect Rack". The extension recognizes its own rack by that shape (a lone Utility inside a single chain) rather than by name, which is what powers the re-run detection described below.

The Extensions SDK cannot act as a real-time audio effect, monitor playback, or process audio while Live is running. GainStage Batch therefore operates only when explicitly invoked and applies a static Utility trim. This is the SDK-appropriate implementation of channel gain staging. 1

Compatibility and installation

The extension requires Ableton Live 12 Suite 12.4.5 public beta or later and the Extensions feature enabled in Live. Extensions are not available in Live Standard, Intro, Lite, or earlier Live releases. Copy or download the packaged gainstage-audio-and-midi.ablx, then install it through Settings → Extensions in Live. The extension appears in the right-click context menu once installed. 1

Requirement	Detail
Live edition/version	Live 12 Suite 12.4.5b or newer with Extensions support.
Target view	Arrangement View.
Source selection	One or more audio and/or MIDI track lanes, a Group Track (collapsed or expanded), and a non-empty time range.
Built-in devices used	A new Live Audio Effect Rack containing a single Utility (the "Gain Stage rack"). Audio-track racks are inserted at device-chain index 0; MIDI-track racks are appended after existing devices.
Measurement	Audio tracks only: offline sample peak from Live’s pre-FX WAV render. This is not true peak or loudness (LUFS) measurement.
Adjustment range	Utility Output is constrained to ±35 dB, the documented internal range for the device.

Operation

Select a non-empty time range in Arrangement View and include the audio-track and MIDI-track lanes that need staging. Right-click the selection and choose GainStage Batch…. Enter the desired target sample peak and select Analyze & Apply. The extension renders the chosen range for each selected audio track, calculates target peak − measured sample peak, and inserts a Gain Stage rack (Audio Effect Rack + Utility) before existing track effects. It also appends a Gain Stage rack left at a neutral, 0.0 dB Utility after the existing devices on every selected MIDI track. A report separates measured audio-track trims from MIDI-track insertions.

For a single track without a manually selected range, right-click its track header and choose GainStage this track…. The extension derives that track’s range from the earliest start and latest end of its Arrangement clips.

A selected or right-clicked Group Track (collapsed or expanded) is resolved to its member audio and MIDI tracks, recursing through nested groups — this works for a mixed group containing both audio and MIDI tracks. When invoked via GainStage this track… on a group, the analyzed range is the earliest start to latest end across all of that group’s clips, combined.

If any selected channel already has a Gain Stage rack, a prompt appears before the target-peak dialog: Re-Gain-Stage All re-stages every already-staged channel, or Look Further… opens a checklist of just those channels (checkboxes, all checked by default) to pick which ones to include. Either path then asks whether to update the existing rack in place or add a new rack after the existing one; channels with no prior Gain Stage rack are unaffected by this prompt and always get a fresh rack.

The batch insertions are made in a single Live transaction. Use Edit → Undo once to revert everything created by that batch.

flowchart TD
    A[User selects tracks/lanes<br/>or right-clicks a track header] --> B{Is the target<br/>a Group Track?}
    B -- Yes --> C[Resolve to member tracks<br/>recursing through nested groups]
    B -- No --> D[Use the track as-is]
    C --> E{Already has a<br/>Gain Stage rack?}
    D --> E
    E -- No --> F[Plan: insert new rack]
    E -- Yes --> G[Prompt: Re-Gain-Stage All<br/>or Look Further]
    G --> H[Choose channels + mode:<br/>update existing / add new]
    H --> F
    F --> I{Track type}
    I -- Audio --> J[Render pre-FX WAV<br/>measure sample peak]
    J --> K[Insert or update rack<br/>Output = target − measured peak]
    I -- MIDI --> L[Insert or confirm rack<br/>Output stays 0.0 dB]
    K --> M[Single Live transaction]
    L --> M
    M --> N[Report: trims applied,<br/>insertions, skipped tracks]

Important behavior and limitations

The SDK's public offline render API is documented and typed for AudioTrack objects only; MIDI-track rendering is attempted through an unsupported bypass of that type restriction (see above) and may not work on every Live/SDK build. When it doesn't, the extension falls back to a neutral, unity-gain Utility placed after the track's existing devices — a consistent Utility control at the output of the MIDI instrument, without pretending an unmeasured MIDI track has been peak staged.

The offline render is pre-FX, so the calculated audio-track trim is deliberately inserted at the beginning of the device chain. This gives downstream track devices a consistently staged input. It does not account for processing that occurs later in the chain, track fader changes, return paths, or summing between channels. For sources that need staging after a specific device, move the inserted Utility to the desired point and then measure/stage again as needed.

Re-running the tool on a channel that already has a Gain Stage rack triggers the conflict prompt described above rather than silently stacking devices. Choosing to update in place edits only the Utility's Output inside the existing rack; choosing to add a new rack leaves the previous one untouched and inserts another immediately after it. A channel is recognized as already staged purely by device shape (an Audio Effect Rack containing a single Utility), since the SDK cannot rename devices to tag them.

Tracks that render silent or fail to render are skipped. Any rack that cannot be configured is removed automatically. The extension handles PCM and IEEE-float WAV files created by Live’s offline renderer. It intentionally does not report true peak, integrated loudness, crest factor, or perceptual loudness.

Development and local testing

The source project uses the official @ableton-extensions/sdk project layout and includes the SDK/CLI tarballs required to reproduce its build. Node.js 24.14.1+ is the SDK’s stated development prerequisite. The Live Extension Host supplies its own runtime when an extension is loaded. 1

npm install
npm test
npm run build
npm run package

npm test verifies the dB-trim clamping and WAV sample-peak parser with generated PCM fixture data. npm run build performs a strict TypeScript check and creates the CommonJS bundle expected by the Extension Host. npm run package produces dist/gainstage-audio-and-midi.ablx.

For live debugging, unpack the official Extensions SDK, set EXTENSION_HOST_PATH in a local .env file to your Live installation’s ExtensionHostNodeModule.node, enable Developer Mode in Preferences → Extensions, and run npm start. Do not include the machine-specific .env file when distributing the extension. 2

Project structure

Path	Purpose
src/extension.ts	SDK entry point, context-menu commands, rendering workflow, Group Track resolution, Gain Stage rack insertion, re-stage conflict resolution, and progress/report dialogs.
src/wav.ts	Dependency-free RIFF/WAVE PCM and IEEE-float sample-peak parser.
src/gain.ts	Target validation, dB trim math, Utility Output range conversion, and display formatting.
ui/interface.html	Ableton-themed target-peak configuration dialog, bundled into the CommonJS extension.
test/gainstage.test.ts	Regression tests for gain calculation and WAVE peak analysis.
dist/gainstage-audio-and-midi.ablx	Installable Ableton Extensions archive.

References