Track API Methods

Methods for analyzing or getting info about tracks.

Analysis - The track analysis includes summary information about a track including tempo, key signature, time signature mode, danceability, loudness, liveness, speechinesss, acousticness and energy along with detailed information about the song structure (sections) beat structure (bars, beats tatums) and detailed info about timbre, pitch and loudness envelope (segment). For a detailed description of how to interpret the analyzer output see the Analyze Documentation

profile

Get info about tracks given an id or md5. The md5 parameter is the file md5.

Parameter Required? Multiple? Values Descriptions
api_key yes no YOUR_API_KEY the developer API key
id one of id or md5 no TRTLKZV12E5AC92E11 the ID of the track
md5 one of id or md5 no 881f4e47e88e8b570e34a3b49c8262ac the MD5 of the track
format no no json, xml, jsonp the desired format of the response
callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests
bucket no yes audio_summary the type of track data that should be returned

Example query:

http://developer.echonest.com/api/v4/track/profile?api_key=YOUR_API_KEY&format=json&id=TRTLKZV12E5AC92E11&bucket=audio_summary

Here is an example response:

{
     "response": {
         "status": {
             "code": 0,
             "message": "Success",
             "version": "4.2"
         },
         "track": {
             "artist": "Weezer",
             "audio_md5": "e16bde82eaecd13bde9261b2710aa991",
             "audio_summary": {
                 "analysis_url": "https://echonest-analysis.s3.amazonaws.com/TR/A1B2C3D4E5F6G7/3/full.json",
                 "danceability": 0.5164314670162907,
                 "duration": 243.64363,
                 "energy": 0.6617689403520844,
                 "key": 1,
                 "loudness": -4.613,
                 "mode": 1,
                 "speechiness": 0.16405298937493515,
                 "acousticness": 0.1331355,
                 "liveness": 0.05298937493515,
                 "tempo": 74.694,
                 "time_signature": 4
             },
             "catalog": "7digital-US",
             "foreign_id": "7digital-US:track:11123262",
             "foreign_release_id": "7digital-US:release:1011998",
             "id": "TRTLKZV12E5AC92E11",
             "preview_url": "http://previews.7digital.com/clips/34/11123262.clip.mp3",
             "release_image": "http://cdn.7static.com/static/img/sleeveart/00/010/119/0001011998_200.jpg",
             "song_id": "SOCRHFJ12A67021D74",
             "status": "complete",
             "title": "El Scorcho"
         }
     }
 }

Analysis Status

  • unknown - The track has never been submitted for analysis. Upload the track for analysis.
  • pending - The track has been uploaded for analysis, but the analysis is not yet ready. Wait for status to change.
  • complete - The track has been analyzed.
  • error - The track could not be analyzed.

The audio_summary can only be returned once the audio analysis has been completed.

Note that the returned 'acousticness' value is a beta feature.

Note that song level information is not available for tracks that have been analyzed with track/upload.

upload

Upload a track to The Echo Nest's analyzer for analysis. The track will be analyzed. This method takes either a url parameter, or a local audio file, which should be the contents of the request body.

Parameter Required? Multiple? Values Description
api_key yes no YOUR_API_KEY the developer API key
format no no json, xml, jsonp the format of the response
callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests
url one of url or a local audio file no http://example.com/audio.mp3 a url to an audio file
filetype required if uploading a local file no wav, mp3, au, ogg, m4a, mp4 the type of audio file to be analyzed
track no no track is required in a POST if using the 'multipart/form-data' Content-Type the track data

Warning

This method requires an HTTP Post request

Posting Tracks

Posting tracks with /track/upload can be done in two manners

  • An HTTP POST request with Content-Type "multipart/form-data" where all parameters are in the post body and the track is in the "track" section of the post "files"
  • An HTTP POST request with Content-Type "application/octet-stream", with the local file as the body of the request, and the parameters in the URL

Example POSTs:

curl -X POST "http://developer.echonest.com/api/v4/track/upload" -d "api_key=YOUR_API_KEY&url=http://example.com/audio.mp3"

curl -F "api_key=YOUR_API_KEY" -F "filetype=mp3" -F "track=@audio.mp3" "http://developer.echonest.com/api/v4/track/upload"

curl -X POST -H "Content-Type:application/octet-stream" "http://developer.echonest.com/api/v4/track/upload?api_key=YOUR_API_KEY&filetype=mp3" --data-binary "@audio.mp3"

Here is an example response:

{
    "response": {
        "status": {
            "version": "4.2",
            "code": 0,
            "message": "Success"
        },
        "track": {
            "status": "pending",
            "artist": "How to Destroy Angels",
            "title": "Fur Lined",
            "analyzer_version": "3.01a",
            "release": "How to Destroy Angels",
            "audio_md5": "97507e1eeda3e62abeabcc8dd51e6bd6",
            "bitrate": 320,
            "id": "TRGOVKX128F7FA5920",
            "samplerate": 44100,
            "md5": "cd9276287838f11f2d7f39cd10391195"
        }
    }
}

Analysis Status

  • pending - The track has been submitted for analysis, but the analysis is not yet ready. Wait for status to change.
  • error - The track could not be analyzed.

The audio_summary can only be returned once the audio analysis has been completed.