Getting started
The Beats Music Audio Manager (BAM) allows developers to incorporate the playback of Beats Music into their web applications using Javascript. Beats Music subscribers will be able to listen to full-length songs directly from your site.
Any use, modification or distribution of this SDK is subject to the Beats Music API Terms of Use provided at https://developer.beatsmusic.com/tos, and for purposes of these Beats Music API Terms of Use this SDK is a Beats Music API.
What you will need
- A Beats Music user account.
- A Beats Music developer account
Setting up your environment
If you are developing locally without a webserver you will need to tell the Adobe Flash Player to trust your project location to allow connections from a non-server location. If you are testing on a local or remote server then you can skip step 2.
- Create a new HTML project in the environment of your choice.
- Open the FlashPlayer Security Settings Panel. You will see a dropdown menu populated with 'Edit Locations...'. Open it and select 'Add Location'. Add the directory of your HTML project to the list of trusted locations by typing or pasting it into the input field (The 'Browse for folder' button is buggy in browsers).
You should now be able to make connections to the Beats Music Service from your local project. The next section will test that these settings are functioning properly.
Testing Playback
Go to your project directory and open your index.html file for editing. Remove any existing HTML and paste the following into the file:
<html>
<head>
<title>My Beats Music Player</title>
</head>
<body>
<script src="http://bam.cdn.beatsmusic.com/bam-1.0.2.min.js"></script>
<script>
// Your player Javascript goes here.
</script>
</body>
</html>This will include the playback library for use in your page and give you a place to add your implementation code. Load your page in a browser and look in your console to ensure that the bam JS file is properly linked.
The remaining code will go in the empty script tag in the body of the page. You will need the following information in order to complete your playback test:
- clientId: the client id you registered in the developer portal.
- authentication: an access token for your user.
- identifier: track id for a Beats Music track you would like to play.
You can get these using the Beats Music API playground area.
Paste the following into your page, substituting the properties above:
var bam = new BeatsAudioManager("myBeatsPlayer");
bam.on("ready", handleReady);
bam.on("error", handleError);
function handleReady(value) {
bam.clientId = [YOUR_DEVELOPER_CLIENT_ID];
bam.authentication = {
access_token:[YOUR_USER_ACCESS_TOKEN],
user_id:[YOUR_USER_ID]
};
bam.identifier = [BEATS_MUSIC_TRACK_ID];
bam.load();
};
function handleError(value) {
console.log("Error: " + value);
switch(value){
case "auth":
// Beats Music API auth error (401)
break;
case "connectionfailure":
// audio stream connection failure
break;
case "apisecurity":
// Beats Music API crossdomain error
break;
case "streamsecurity":
// audio stream crossdomain error
break;
case "streamio":
// audio stream io error
break;
case "apiio":
// Beats Music API io error getting track data
break;
case "flashversion":
// flash version too low or not installed
break;
}
};
Here is a breakdown of what is going on in this snippet:
The first line creates an instance of the BAM named "myBeatsPlayer". If you do not specify a name then it will default to "bam". By using a name you can create multiple instances of the player on the same page. Then we subscribe to the ready and the error events and define our handler functions. When the BAM instance is created it will begin initializing immediately. When the ready event is dispatched the player is available to play tracks. Our ready handler sets the needed information on the BAM instance, then calls the load method to begin playback.
Save the file and open it in your browser. Since autoplay is true by default, you should hear your track auomatically playing within seconds. If you do not hear the specified track, make sure of the following:
- Open the console for your browser and make sure that your bam.js is linked properly (no 404).
- Open your console and ensure that you are not getting a 401 response. If so, you need to go to the playground and get a new acess token.
- If the above issues do not exist, make sure that you have specified the right directory in the Flash Player Security Settings Panel.
Live Examples
Here are some working examples on JS Fiddle. Keep in mind you will need to enter your own client ID, access token and user ID. You can get these at the playground.
