sonicAPI.com

analyze/tempo

Show demo

Detect 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.



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.