EMI Premium Content Sandbox Developer Guide
Introduction
The EMI and The Echo Nest have partnered to put premium content into the hands of the developer. This guide shows you how you can get access to the content in the sandboxes.
Getting access to a sandbox
Before you can get started with a sandbox, you will need to apply for access to the specific sandbox. To do so, start at The EMI Sandbox page . This page lists the available EMI sandboxes, from EMI Selection, Blue Note or one of a selection of EMI artists. Pick the sandbox that you are interested in, and read through the approval process. This is important stuff, since it outlines how you will be able to use the content. If you are not careful, you could end up spending time developing an application that you will not be able to release. Make sure to read the general EMI Sandbox FAQ.
Once you understand the application approval process, follow the directions for applying to get access to the sandbox. Once you've been granted access, your API key and credentials will be authorized to access content in the sandbox.
There are two types of EMI Sandboxes:
- General collection sandboxes that contain tracks, album art and previews for a wide range of artists.
- Artist specific sandboxes that contain audio, video, artwork, images, press releases and more for a specific artist.
On your Account Sandboxes page you'll see a list of all available sandboxes, along with your approval status for each sandbox.
Finding out what is in a sandbox
To get a general idea of what is in a sandbox, visit the specific sandbox by following the link from The EMI Sandbox Page. For example, the Blue Note page describes the available assets as '(1) audio for approximately 10,000 tracks and (2) Audio Metadata'
Artist-specific pages also include a developer pack which includes overview information for the artist and detailed inventory and description of all of the assets provided in the sandbox. An example is The Gorillaz developer pack.
To programmatically list the contents of a sandbox, use the sandbox/list method. This method gives a complete inventory of every asset in the sandbox. You do not need to be approved to access a sandbox to call this method, list the assets, and see what is in the sandbox. To list the contents of a particular sandbox you will need the Sandbox Key. You can find the Sandbox Key for each sandbox on your Account Sandboxes page.
For example, the EMI Blue Note sandbox has a Sandbox Key of 'emi_bluenote'. To list the contents of this sandbox, make the method call:
http://developer.echonest.com/api/v4/sandbox/list?api_key=FILDTEOIK2HBORODV&sandbox=emi_bluenote&results=2
This call returns a response of:
{
"response": {
"status": {
"code": 0,
"message": "Success",
"version": "4.2"
},
"start": 0,
"total": 23604
"assets": [
{
"echonest_ids": [
{
"foreign_id": "emi_bluenote:track:EUEDD0270749",
"id": "TRNVKOX13346FF118A"
}
],
"filename": "emi_bluenote/EUEDD0270749-preview.mp3",
"id": "af5860829140c3a3f6ca48c29b91c481",
"type": "preview_audio"
},
{
"echonest_ids": [
{
"foreign_id": "emi_bluenote:track:EMIDD1009985",
"id": "TRKOUMM13346FF0F16"
}
],
"filename": "emi_bluenote/EMIDD1009985.mp3",
"id": "8ef1b79639e4dca2c153dc3d7c98f5a5",
"type": "audio"
}
],
}
}
This response shows that there are 23,604 assets in the sandbox. Each asset is described with at least the following information:
- type
- The type of asset. Types include 'audio', 'preview_audio', 'release_image' and others.
- id
- The asset id. Use this with the access method to gain access to the actual asset. We describe how to do this in more detail below.
- echonest_ids
- If the asset is associated with a particular Echo Nest item such as an artist or a track, the ID will be included in this list of dictionaries.
Since the sandboxes are static, your application typically needs to get the asset inventory for a sandbox just once, and can safely cache the information locally.
Accessing the assets in a sandbox
To get access to the assets you use the sandbox/access method. To ensure that only authorized developers get access to the assets, the access method requires a cryptographic signature.
We use Oauth 1.0 for this authentication. The authentication process can be a bit complicated, so it is highly recommended that you use a library (such as pyechonest or jEN) to handle all of the authentication details. To sign a request, you add an oauth_nonce parameter (a random string of characters that differs from call to call), a timestamp (the number of seconds since the epoch) and a signature which is generated by a applying a cryptographic has such as SHA1 to your consumer key, shared secret and the base string portion of the request.
Yes, this is complicated. Such is Oauth. Use a library, and read its documentation!
A guide to signing requests can be found in the Oauth 1.0 Guide. Netflix also has an excellent description of how to sign requests in their Authentication Overview.
The authentication procedure requires a Consumer Key and a Shared Secret. These can be obtained on your Account Profile page. You should avoid exposing your shared secret to the public (such as an open source repository, or in the Javascript on a web page). If a shared secret is inadvertently exposed, let us know and we will expire the secret. Here's an example request that shows how to get access to the asset with the ID 'af5860829140c3a3f6ca48c29b91c481'. Note, of course, that the security credentials in this example are not valid credentials. This particular example with fail with an authentication error.
http://developer.echonest.com/api/v4/sandbox/access?api_key=FILDTEOIK2HBORODV&sandbox=emi_bluenote&id=af5860829140c3a3f6ca48c29b91c481&oauth_consumer_key=b30f027ead14e3056d8833b9e783a526&oauth_nonce=1234367&oauth_timestamp=1319830594&oauth_signature_method=HMAC-SHA1&oauth_signature=tR3+Ty81lMeYAr/Fid0kMTYa/WM=
{
"response": {
"status": {
"version": "4.2",
"code": 0,
"message": "Success"
},
"assets": [
{
"url": "http://assets-cdn.echonest.com/emi_bluenote/EUEDD03083622-preview.mp3?Expires=1320148855&Signature=HD",
"id": "c1b89c9b9e0ee9e53650f1d4e393d716"
},
]
}
}
For each requested ID, the access method returns a dictionary containing the URL to the asset. The URL expires in 10 minutes.
Using other Echo Nest APIs with sandbox content
Many of the assets are directly associated with Echo Nest data. For instance, an audio asset may be associated with an Echo Nest Track ID. The Echo Nest IDs for an asset are returned in the echonest_ids block of the asset description. You can use the Echo Nest API to get more detailed information about the asset. For example, one of the Blue Note tracks has an asset description like:
{
"echonest_ids": [
{
"foreign_id": "emi_bluenote:track:EMIDD1009985",
"id": "TRKOUMM13346FF0F16"
}
],
"filename": "emi_bluenote/EMIDD1009985.mp3",
"id": "8ef1b79639e4dca2c153dc3d7c98f5a5",
"type": "audio"
}
You can use the Echo Nest track ID TRKOUMM13346FF0F16 to get more information about the track with the track/profile call:
http://developer.echonest.com/api/v4/track/profile?api_key=FILDTEOIK2HBORODV&format=json&id=TRKOUMM13346FF0F16&bucket=audio_summaryThis call returns the response:
{
"response": {
"status": {
"code": 0,
"message": "Success",
"version": "4.2"
},
"track": {
"artist": "Stan Kenton",
"audio_md5": "1686b479eeb8310bd65c1a9cf2708273",
"audio_summary": {
"analysis_url": "https://echonest-analysis.s3.amazonaws.com/..."
"danceability": 0.17244651289412521,
"duration": 130.06666999999999,
"energy": 0.20982863398344401,
"key": 7,
"loudness": -9.4399999999999995,
"mode": 1,
"tempo": 78.022999999999996,
"time_signature": 4
},
"id": "TRKOUMM13346FF0F16",
"song_id": "SOUNBRE12AB0184AE3",
"status": "complete",
"title": "O Holy Night (2003 Digital Remaster)"
}
}
}
This includes detailed audio information about the song including energy, danceability, loudness, key, mode and time signature. In addition, you can also get a fully detailed analysis that includes detailed timbral, pitch and loudness info, along with a fine-grained representation of the beat structure of the song.
Also included in the information is the song_id, which can be used to retrieve more cultural information about the song (hotttnesss, artist information and so on).
Playlisting within a catalog
The general collections (EMI Selection and EMI Blue Note) are also associated with Rosetta Stone catalog allowing you to take advantage of all the APIs that support working with Rosetta catalogs. For instance, you can generate a playlist restricted to songs that are in the Blue Note catalog with a call like this:
http://developer.echonest.com/api/v4/playlist/basic?api_key=FILDTEOIK2HBORODV&artist=miles+davis&format=json&results=20&type=artist-radio&bucket=id:emi_bluenote&limit=true&bucket=tracks
Similarly, you can search for the hotttest artist in the open collection with a call:
http://developer.echonest.com/api/v4/artist/search?api_key=FILDTEOIK2HBORODV&format=json&results=20&bucket=id:emi_open_collection&limit=true&sort=hotttnesss-desc
Or you can search for the fastest songs in the Blue Note collection with a call:
http://developer.echonest.com/api/v4/song/search?api_key=FILDTEOIK2HBORODV&format=json&results=20&bucket=id:emi_bluenote&limit=true&sort=tempo-desc&bucket=audio_summary
The Echo Nest API provides a vast amount of data at the Artist, Song and Track level. You can associate this data with the assets in the EMI sandbox to provide context for the content. Similarly, you can use Echo Nest searching, similarity, and playlisting APIs to help people explore for and discovery music from the EMI catalog.
Conclusion
The EMI Premium Content Sandboxes present a great opportunity for music application developers to create new and innovative applications around music -- without needing a bevy of lawyers to negotiate label deals. We here at The Echo Nest hope you will go and build some really cool stuff with this content and our API.