What loudness normalisation is
Two tracks peaking at the same level can sound very different in volume. Integrated loudness measures how loud a track sounds over its whole length, the way a listener hears it, in LUFS (Loudness Units relative to Full Scale, defined by the EBU R128 / ITU-R BS.1770 standards). Normalising a track adjusts it so its integrated loudness lands on a target you choose, so that everything you deliver plays back at a consistent level. You ask for it with aloudness block. Seven endpoints accept one:
create.new_sample, create.new_fx and adapt.separate_stems don’t take a loudness block. To normalise their outputs, pass them to adapt.normalise_loudness.
Asking for it
The block takes the target either as a number or as a named preset, never both:{} asks for the defaults: -14 LUFS, with compression allowed. A block with both preset and target_lufs is refused with a 422.
Opt-in or always on
- Opt-in on the five endpoints that produce or cut music. Leave
loudnessout and the outputs come back exactly as produced, with noloudnessfields in the response at all. Include the block, even{}, to normalise them. - Always on on
adapt.normalise_loudness, which exists to normalise, andadapt.auto_duck, which delivers a finished mix at a known loudness. There the block is optional: leaving it out means the defaults.
Presets
A preset names where the audio is going. Each stands for a fixed target, and a preset’s value never changes, so a request that names one means the same thing next year as it does today.
For a destination that isn’t a preset, send its number as
target_lufs. The loudness normalisation guide has a table of common destinations.
The peak ceiling
Normalised audio always keeps its true peak at or below -1 dBTP. That ceiling is fixed, and isn’t a field: it leaves the headroom that lossy encoding and playback need to stay free of clipping, and a higher ceiling would only trade that headroom away. Every preset fits under it.allow_compression
Changing the level of a track moves its loudness and its peaks by the same amount. Most audio can reach its target that way without its peaks going over the ceiling, and then the level is the only thing that changes, whatever allow_compression says.
Very dynamic audio, with loud peaks relative to its average level, can’t: turning it up far enough to reach the target would push its peaks over the ceiling. allow_compression decides what happens then:
Choose
false when preserving the dynamics matters more to you than hitting the number. The loudness normalisation guide shows a worked example of each outcome.
What’s measured
When normalisation was applied, the response tells you two things. The operation echoes what you asked for, with any omitted fields filled in:target_lufs is always present, whichever way you asked. preset is present only when you named one; it is absent (not null) when you sent a number or {}.
Each ready output carries a loudness block measured on the audio you download:
These are measured, not assumed: when a track can’t reach the target (see
allow_compression above), lufs reports where it actually landed, so you can decide for yourself whether the difference matters. On an endpoint with variations, each variation is normalised and measured separately.
Output loudness is only present once the operation is ready. On an opt-in endpoint where you didn’t ask for normalisation, there is no loudness field at all, neither the echo nor on the outputs: absent, not null.