analyze/tempo
Show demoDetect the tempo and the click marks.
The tempo detection task allows you to determine the tempo (in beats per minute) of the audio file as well as the individual beat positions.
The result allows you to sort your audio files with respect to the tempo (e.g. for categorization or playlists); the click positions can be used for, e.g., beat matching. In order to change the tempo of a file see process/elastique.
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 results include the overall tempo, the clicks per bar as measure of the time signature as well as a list of individual click marks. Note that each beat contains two clicks.
| Name | Type | Description |
|---|---|---|
| clicks_per_bar | integer | The number of click marks constituting one bar.
The length of a bar in clicks is constant even if the tempo slowly changes over time. |
| overall_tempo | float | The song's average tempo.
A measure of the perceived tempo in beats per minute (BPM). |
| overall_tempo_straight | float | The song's average tempo (alternative computation).
If a song is known to have an absolutely constant tempo (see, e.g., many electronically produced songs), this measure might give more accurate results. |
| click_marks | List of clicks extracted from the music.
Each click has several attributes with information on the position, the local (instantaneous) tempo, the estimation reliability and on the click being a downbeat or not (see below). |
Each click has the following attributes:
| Name | Type | Description |
|---|---|---|
| index | integer | The index of the click mark. |
| bpm | float | The local tempo estimate in BPM.
Tempo can change throughout a song. The local tempo estimate tracks these changes. |
| probability | float | An estimate of the reliability of this click mark estimate. |
| time | float | The time position of the click mark (in seconds). |
| downbeat | string | "true" for the first beat of a bar, "false" otherwise.
The downbeat marks the beginning of a bar. The distance between two downbeats will thus be clicks_per_bar. |
Audio file requirements
The specified audio file must have a duration of at least 20 seconds to ensure you get reliable results. For shorter files you will get an "Insufficient audio file" error (code 23).
One-click example
You can analyze the tempo 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/tempo
?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 tempo analysis task uses the [aufTAKT] engine by zplane.development as integrated in numerous DJ software applications.