This tutorial provides a step-by-step guide to creating a simple music player using the imeem Media Platform and the Adobe ActionScript 3 client library. While this tutorial does not showcase all of the imeem Media Platform’s capabilities, it provides an introduction on how to take advantage of the platform.
Let’s get started!
- Ensure you have an imeem user account. If you don’t already have one, you can create one here.
- Create a new imeem Media Platform application. Go to the imeem Media Platform developers home page to create your application. Select the Create tab and specify your application details.
- Take note of the api key and secret that are generated for your application.
- Download the ActionScript 3 Client Library from the downloads section of the developers site.
- Ensure you have Adobe Flex Builder 3 installed. If not, you can download a trial here.
- Run Adobe Flex Builder 3
- Select File: New: Flex Project. Call the project “MyMusicPlayer”. Select “Web application”.
- Copy the imeem.api.swc client library that you downloaded to the libs folder of your newly created project.
- Right-click on your project in the Flex Navigator and select properties. Go to the Flex Build Path node. Select the Library Path tab. Choose Add swc and browse to the location of the imeem.api.swc.
- Open MyMusicPlayer.mxml
- Setup the UI for the music player. This will include a play/pause button, a title and artist label, a slider representing the current position of the song, and an image for the album art. We’ll also setup canvases to display the imeem toolbar as well as the imeem overlay display. To do this, replace the existing code in MyMusicPlayer.mxml with the following:
<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute" creationComplete="onInit()">
<mx:Canvas x="0" y="0" width="280" height="175" backgroundColor="#FFFFFF">
<mx:Canvas id="playerCanvas" x="0" y="0" width="280" height="150">
<mx:Button id="playButton" x="23" y="77" label="Play" click="onTogglePlayButtonClick()" width="60" height="60" fontSize="10" fontWeight="bold"/>
<mx:HSlider id="songPositionSlider" x="109" y="100" change="onSongPositionChange(event)" width="161"/>
<mx:Label id="songTitleLabel" x="109" y="25" text="title" width="161" fontSize="14" color="#000000" fontWeight="bold"/>
<mx:Label id="songArtistLabel" x="109" y="47" text="artist" width="161" fontSize="12" color="#000000"/>
<mx:Image id="songIconLabel" x="30" y="25" scaleContent="true" width="45" height="45"/>
</mx:Canvas>
<mx:Canvas id="toolbarCanvas" x="0" y="150" width="280" height="25">
</mx:Canvas>
</mx:Canvas>
</mx:Application>
- Now let’s create the script section of the application, declare some key member variables, and initialize the client library classes. Copy the following code into your MXML file:
<mx:Script>
<![CDATA[
import imeem.api.Imeem;
import imeem.api.player.MediaPlayer;
import imeem.api.data.MusicData;
import imeem.api.events.MediaEvent;
import imeem.api.results.ResultData;
import mx.events.SliderEvent;
// application API key and secret
static private const API_KEY:String = "your API key";
static private const API_SECRET:String = "your API secret";
// id of the song to play
private var mediaID:String = "V08rFe1zBa";
private var imeemService:Imeem = null;
private var player:MediaPlayer = null;
private var updateTimer:Timer = null;
private function onInit():void
{
// instantiate the Imeem class and get song info
imeemService = new Imeem(API_KEY, API_SECRET);
imeemService.media.getInfo([mediaID], onMediaGetInfo);
// instantiate the MediaPlayer class and load player
player = new MediaPlayer(API_KEY, API_SECRET);
player.addEventListener(MediaEvent.MEDIA_PLAYER_LOADED, onMediaPlayerLoadedEvent);
player.addEventListener(MediaEvent.MEDIA_END, onMediaEndEvent);
player.load();
}
]]>
</mx:Script>
The code declares variables for the API_KEY, API_SECRET, and mediaID that the player will play. It then declares variables for the imeem class that we will use to make web services call to the imeem Media Platform as well as the MediaPlayer class which will be used for media playback.
In the onInit method, we pass in the API_KEY and API_SECRET to the constructor of the imeemService and player objects. We also make a call to the media.getInfo method of the imeemService object to retrieve metadata for the song we wish to play. All imeemService object calls are asynchronous and require callback functions to be specified to process the results. In this case we have specified the onMediaGetInfo function. For the media player class, we add several event listeners for the MEDIA_PLAYER_LOADED and MEDIA_END events. Then we load the player to prepare it for playback.
- Change the API_KEY and API_SECRET constants to reflect those given to you at application creation.
- Change the mediaID to be whatever song you wish to have the player play. The best way to get the media ID of your desired song is to use the API Test Console to perform a search for your song and pull out the id. You can find the API Test Console here: http://www.imeem.com/developers/devresources/console/
- Now let’s create the callback function to handle the getInfo request as well as the event handlers that we setup in the onInit method. Copy in the following code:
private function onMediaGetInfo(result:ResultData):void
{
if (result.success)
{
// display song title, artist, and icon from results
var songs:Array = result.data as Array;
var song:MusicData = songs[0] as MusicData;
songTitleLabel.text = song.title;
songArtistLabel.text = song.artist;
songIconLabel.source = song.iconUrl;
}
}
private function onMediaPlayerLoadedEvent(event:MediaEvent):void
{
// setup timer to periodically update current song position
updateTimer = new Timer(100);
updateTimer.addEventListener(TimerEvent.TIMER, onTimerEvent);
updateTimer.start();
// set the location of the imeem toolbar and overlay display
player.setToolbarDisplay(toolbarCanvas);
player.setOverlayDisplay(playerCanvas);
}
private function onMediaEndEvent(event:MediaEvent):void
{
// reset player to position 0 once reached end of song
player.stop();
playButton.label = "Play";
}
The callback function takes in a ResultData parameter that includes a data property that is an array of MusicData objects. From this, we get the song title, artist, and icon to populate the UI. Once the media player is loaded, we setup a timer in the onMediaPlayerLoadedEvent to fire every 100 ms. We also set the area in which we want the imeem toolbar, a required UI component, to be displayed. We do the same for the imeem overlay. The overlay area is designed to display on top of the player. (Consult the application guidelines for more details). The onMediaEndEvent dispatches when the song playing reaches the end, so at that point we’ll want to stop the player and set the play button to read Play again.
- Finally, we setup the timer event, the slider change event, and the play button event handler to complete the UI handling of our music player. Copy the following code into the script section:
private function onTimerEvent(event:TimerEvent):void
{
// set slider to reflect current song position
songPositionSlider.minimum = 0;
songPositionSlider.maximum = player.trackLength;
songPositionSlider.value = player.trackPosition;
}
private function onSongPositionChange(event:SliderEvent):void
{
// set song position to reflect current slider position
player.seek(event.value);
}
private function onTogglePlayButtonClick():void
{
// toggle play/pause
if (player.status == MediaPlayer.STOPPED)
{
player.play(mediaID);
playButton.label = "Pause";
}
else if (player.status == MediaPlayer.PAUSED)
{
player.resume();
playButton.label = "Pause";
}
else
{
player.pause();
playButton.label = "Play";
}
}
The onTimerEvent event handler updates the slider to reflect the current position of the currently playing song. At the same time the onSongPostionChanged event handler seeks to the location in the song designated by the user’s selection on the slider. Finally, the onTogglePlayButtonClick event handler toggle’s between play and paused depending on the current state of the MediaPlayer.
- Select Run: Debug MyMusicPlayer to see your new music player in action! That’s it!
Below you will find the full MyMusicPlayer.mxml file for your reference:
<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute" creationComplete="onInit()">
<mx:Canvas x="0" y="0" width="280" height="175" backgroundColor="#FFFFFF">
<mx:Canvas id="playerCanvas" x="0" y="0" width="280" height="150">
<mx:Button id="playButton" x="23" y="77" label="Play" click="onTogglePlayButtonClick()" width="60" height="60" fontSize="10" fontWeight="bold"/>
<mx:HSlider id="songPositionSlider" x="109" y="100" change="onSongPositionChange(event)" width="161"/>
<mx:Label id="songTitleLabel" x="109" y="25" text="title" width="161" fontSize="14" color="#000000" fontWeight="bold"/>
<mx:Label id="songArtistLabel" x="109" y="47" text="artist" width="161" fontSize="12" color="#000000"/>
<mx:Image id="songIconLabel" x="30" y="25" scaleContent="true" width="45" height="45"/>
</mx:Canvas>
<mx:Canvas id="toolbarCanvas" x="0" y="150" width="280" height="25">
</mx:Canvas>
</mx:Canvas>
<mx:Script>
<![CDATA[
import imeem.api.Imeem;
import imeem.api.player.MediaPlayer;
import imeem.api.data.MusicData;
import imeem.api.events.MediaEvent;
import imeem.api.results.ResultData;
import mx.events.SliderEvent;
// application API key and secret
static private const API_KEY:String = "your API key";
static private const API_SECRET:String = "your API secret";
// id of the song to play
private var mediaID:String = "V08rFe1zBa";
private var imeemService:Imeem = null;
private var player:MediaPlayer = null;
private var updateTimer:Timer = null;
private function onInit():void
{
// instantiate the Imeem class and get song info
imeemService = new Imeem(API_KEY, API_SECRET);
imeemService.media.getInfo([mediaID], onMediaGetInfo);
// instantiate the MediaPlayer class and load player
player = new MediaPlayer(API_KEY, API_SECRET);
player.addEventListener(MediaEvent.MEDIA_PLAYER_LOADED, onMediaPlayerLoadedEvent);
player.addEventListener(MediaEvent.MEDIA_END, onMediaEndEvent);
player.load();
}
private function onMediaGetInfo(result:ResultData):void
{
if (result.success)
{
// display song title, artist, and icon from results
var songs:Array = result.data as Array;
var song:MusicData = songs[0] as MusicData;
songTitleLabel.text = song.title;
songArtistLabel.text = song.artist;
songIconLabel.source = song.iconUrl;
}
}
private function onMediaPlayerLoadedEvent(event:MediaEvent):void
{
// setup timer to periodically update current song position
updateTimer = new Timer(100);
updateTimer.addEventListener(TimerEvent.TIMER, onTimerEvent);
updateTimer.start();
// set the location of the imeem toolbar and overlay display
player.setToolbarDisplay(toolbarCanvas);
player.setOverlayDisplay(playerCanvas);
}
private function onMediaEndEvent(event:MediaEvent):void
{
// reset player to position 0 once reached end of song
player.stop();
playButton.label = "Play";
}
private function onTimerEvent(event:TimerEvent):void
{
// set slider to reflect current song position
songPositionSlider.minimum = 0;
songPositionSlider.maximum = player.trackLength;
songPositionSlider.value = player.trackPosition;
}
private function onSongPositionChange(event:SliderEvent):void
{
// set song position to reflect current slider position
player.seek(event.value);
}
private function onTogglePlayButtonClick():void
{
// toggle play/pause
if (player.status == MediaPlayer.STOPPED)
{
player.play(mediaID);
playButton.label = "Pause";
}
else if (player.status == MediaPlayer.PAUSED)
{
player.resume();
playButton.label = "Pause";
}
else
{
player.pause();
playButton.label = "Play";
}
}
]]>
</mx:Script>
</mx:Application>
