analyze/key
Show demoExtract the musical key.
The key task recognizes the musical key and the tuning frequency of a song. The key describes its tonal center - the root note - and the scale such as major or minor. Typical key descriptions would be, for example, "a minor" or "E Major". The task is able to distinguish between major and minor keys and to identify the root/pitch class and thus has 24 possible results.
The musical key allows you to estimate the tonal compatibility between two or more songs, as it is done in, e.g., DJ software for the so-called harmonic mixing. The closer two keys are in the Circle of Fifths, the more likely they are compatible with each other. Pitch shifting (see task process/elastique) can be applied to the audio to increase compatibility.
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 response gives you the main results (musical key, tuning frequency); these are complemented by a list of pitch energies indicating which pitches are more and less common in the analyzed song.
| Name | Type | Description |
|---|---|---|
| key | string | The name of the extracted key.
The algorithm is able to detect both major (Maj) and minor (min) scales from 12 different root notes (C, C#, D, D#, E, F, F#, G, G#, A, A#, B). There are no flat root notes as we assume enharmonic equivalency (c sharp equals d flat). |
| key_index | integer | A representation of the key as an index.
The key_index can take the values 0...23. The first 12 indices indicate the major keys, and remaining indices the minor keys, both starting from C (example: d# min is 15). |
| tuning_frequency | float | The song's tuning frequency in Hz.
The tuning frequency is the frequency of the concert pitch A4 and frequently equals 440Hz. It may deviate a few Hertz for some songs. |
| pitch_energies | List of average pitch energies extracted from the music.
Some pitch classes are more frequently used in a song than others. The pitch_energies attribute show the (octave-independent) energy distribution (also referred to as pitch chroma). |
The pitch_energies contains the following attributes:
| Name | Type | Description |
|---|---|---|
| name | string | The name of the pitch class. |
| energy | float | A value between 0 and 1 containing the energy of the pitch class compared to all other pitch classes. |
One-click example
You can analyze the musical key 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/key
?access_id=584ee88b-4525-4f14-b2ea-94dedda17a30
&input_file=http://www.sonicapi.com/music/brown_eyes_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 key analysis task uses the [tONaRT] engine by zplane.development as integrated in numerous DJ software applications.