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 and loudness, 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
Analyze a previously uploaded track with the latest version of the analyzer. The md5 parameter is the file md5.
Parameter Required? Multiple? Values Description api_key yes no N6E4NIOVYMTHNDM8J the developer API key id one of id or md5 yes TRTLKZV12E5AC92E11 the ID of the previously uploaded track md5 one of id or md5 yes 881f4e47e88e8b570e34a3b49c8262ac the md5 of the previously uploaded 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 wait no no true or false if true wait for the analysis to be completed bucket no yes audio_summary Indicates which track data should be returned (only valid if wait is true) Warning
This method requires an HTTP Post request with Content-Type "multipart/form-data"
Example post:
curl -F "api_key=N6E4NIOVYMTHNDM8J" -F "format=json" -F "id=TRTLKZV12E5AC92E11" -F "bucket=audio_summary" "http://developer.echonest.com/api/v4/track/analyze"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, "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. Submit the track for analysis.
- pending - The track has been submitted 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.
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 N6E4NIOVYMTHNDM8J the developer API key id one of id or md5 yes TRTLKZV12E5AC92E11 the ID of the track md5 one of id or md5 yes 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=N6E4NIOVYMTHNDM8J&format=json&id=TRTLKZV12E5AC92E11&bucket=audio_summaryHere 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, "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. Submit the track for analysis.
- pending - The track has been submitted 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.
- unavailable - The track's analysis is out of date. Call analyze on this trackID.
The audio_summary can only be returned once the audio analysis has been completed.
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 N6E4NIOVYMTHNDM8J 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 wait no no true or false if true wait for the upload and analysis to finish filetype required if uploading a local file no wav, mp3, au, ogg, m4a, mp4 the type of audio file to be analyzed bucket no yes audio_summary type of data to be returned (only valid if wait is true) 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=N6E4NIOVYMTHNDM8J&url=http://example.com/audio.mp3"
curl -F "api_key=N6E4NIOVYMTHNDM8J" -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=N6E4NIOVYMTHNDM8J&filetype=mp3" --data-binary "@audio.mp3"
Here is an example response:
{ "response": { "status": { "version": "4.2", "code": 0, "message": "Success" }, "track": { "status": "complete", "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.
- 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.