analyze_audio
Read-onlyIdempotent
Measure audio loudness, true peak, stereo phase, and band balance to verify and guide mixing in Ableton Live.
Instructions
Measure the audio itself: loudness, true peak, stereo phase and band balance.
Reads the LiveMaestro Analyzer Max for Live device over loopback OSC; without it this
reports device_not_found with the steps to load it.
- Loudness to EBU R128: momentary 400 ms, short term 3 s, gated integrated since
reset, range.
- True peak, oversampled, with sample peak, RMS and the crest factor between them.
- Stereo correlation full band and below 120 Hz, and low-end survival of a mono sum.
- Seven band energies on the mono sum, and their weighted centre, not an FFT centroid.
The device reads at its position in the chain, so it belongs last: an effect
after it is not in the reading. A master chain sits before the master fader, so a
master reading matches the output only at 0.0 dB. The two peak figures are maxima
since the last reset and only rise: to measure one, call with
reset=true and no accumulate, let a pass of the material through, then call again.
The averaged figures need no reset. What it proves is what the signal measured
passing the device, not the room.
Every measurement carries the transport state from immediately after it, so a reading
taken mid scene change can be recognised. ``in_transition`` is true while any track
reports fired_slot_index 0 or more, a launch waiting for the next quantization boundary,
and ``tracks_sounding`` counts tracks whose playing_slot_index is 0 or more while the
transport runs, 0 when stopped: clips Live plays, not what is audible. Unreadable state
gives ``transport`` null with a code and one sentence in ``transport_unavailable``, or
not_queried when the analyzer did not answer.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| reset | No | Restart the integrated loudness and loudness range before measuring, to integrate one section rather than everything since the audio engine started. The reply that performs the reset reports no integrated figure, because it had just begun. It applies to a call with no 'accumulate' at all: an accumulation samples the device on its own schedule, and accumulate='read' reports the windows already counted rather than taking a fresh measurement, so a call that passes both performs no reset. | |
| track | No | Which analyzer to read: a track name, a zero-based track index, 'master' for the main track, or '*' for whichever instance answers first. Every instance in the set answers every request, and the result lists them all under 'answered'. An index or 'master' costs one extra round trip, because the device reports the name of its track and the index is resolved against the set here. | master |
| window_ms | No | How far back the averaged measurements reach, in milliseconds. This governs the averaged figures alone: RMS, both correlations and the seven bands. Loudness keeps its own EBU windows and the peaks are maxima since the last reset. This looks backwards at audio that already played and returns immediately. It does not record for this long. The device buffers a fixed number of samples, so the window this reaches depends on the sample rate: about 2180 ms at 44.1 kHz and 1000 ms at 96 kHz. A longer request is clamped without complaint, so read window_ms back off the result rather than assuming the request was honoured. | |
| accumulate | No | Accumulate band occupancy and levels over multiple analysis windows. 'start' begins periodic background sampling; 'read' returns the accumulated occupancy percentages and averaged levels across all sampled windows, together with the span they were taken over; 'reset' stops and clears accumulation. Occupancy is a share of time, so it is reported on 'read' alone: a single call measures one window and reports none. | |
| occupancy_threshold_db | No | Threshold in dB relative to the loudest band in each analysis window. A band is counted as occupied if its level is within this threshold of the loudest band. It takes effect on accumulate='start' alone, because that is where the counting happens: an accumulate='read' reports the threshold its own accumulation was started with, and a single call counts no occupancy at all. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||