analyze/loudness
Show demoExtract loudness and peak maximum.
The loudness analysis task estimates the perceived loudness of an audio file according to the EBU recommendation R128.
Knowing the loudness of an audio file allows you to adjust one file's overall volume to either a reference level or to the loudness of another file, thus avoiding jumps in the perceived playback level in music players. In most cases, adjusting the LU is trivial: add a gain to your audio file that corresponds to the difference between the extracted and the target LU value. You can also verify the EBU standard compliance of your mixes and productions for your customer or broadcasting station.
Parameters
Parameter | Type | Description |
---|---|---|
access_id required |
string |
One of your personal access_ids. |
input_file required |
file |
A file id or file url or a direct file upload (requires POST).
Upload a local file by performing a POST request with encoding-type "multipart/form-data" (corresponding to an html form with an <input type="file" />) |
begin_seconds optional |
float |
Skip audio data before this position. |
end_seconds optional |
float |
Ignore audio data after this position. |
blocking optional |
bool [true, false] default: true |
Whether to call the task in a blocking or non-blocking way.
Blocking calls return the results directly. For more info see the response documentation for this task. |
format optional |
string [xml, json, jsonp, xmlp] default: xml |
The format to use in the response.
Note that for the formats "jsonp" or "xmlp", the HTTP status code will always be 200. |
callback optional |
string |
Callback function name required when using the format "jsonp" or "xmlp." |
foo_string optional |
string |
Arbitrary string to add to the logs.
Allows you to add any strings you might find helpful for later analysis of the request logs. |
Response
blocking=false
The response gives you a status code, the file_id and the corresponding download URL of the resulting file (audio for process tasks and xml for analyze tasks). For processing reports, use the /file/status request with the parameter format=xml/json/jsonp/xmlp.
Name | Description |
---|---|
status | The status code of the task. |
file_id | The unique identifier of the file. |
href | The direct download link to the file including the file_id |
blocking=true
The result provides various measures of loudness and level in the audio file.
Name | Type | Description |
---|---|---|
programme_loudness | float | The loudness of the audio in LU.
The pseudo-unit LU stands for loudness unit. In order to increase or decrease the loudness by one LU, apply a gain of +1 (or -1, respectively) dB to the audio. For your mix to be EBU R128 compliant adjust the loudness to 0 LU (0 LU = -23 LUFS). LU values above 0 LU are possible. |
loudness_range | float | The loudness range (in LU) measures the variation of loudness.
The loudness range is computed from the instantaneous shortterm loudness (see below). High loudness ranges indicate frequent and/or large changes in the programme. |
momentary_loudness_max | float | The overall maximum of the momentary loudness (in LU).
The momentary loudness is a measure with the comparably short integration time of 0.4s. |
shortterm_loudness_max | float | The overall maximum of the shortterm loudness (in LU).
The shortterm loudness is a measure with an integration time of 3s. |
truepeak_max | float | The maximum of the true peak level as an intra-sample peak measure in dBFS.
The true peak maximum should never be larger than 0 dBFS. To decrease the true peak maximum by 1 dB, apply a gain of -1 dB to the audio signal. |
One-click example
You can analyze the loudness of this
song snippet
with a simple click on this button:
Analyze
Learn more
The button is just a link with a specially constructed URL:
https://api.sonicapi.com/analyze/loudness
?access_id=584ee88b-4525-4f14-b2ea-94dedda17a30
&input_file=http://www.sonicapi.com/music/burning_bridges_by_ueberschall.mp3
By requesting this URL, the input file will be imported into the system, processed by sonicAPI and the analysis result is displayed in your browser. The
Live-Demo generates additional example code.
About the technology
The loudness analysis task uses the Metering technology by zplane.development, included in multiple audio software products such as zplane PPMulatorXL.