Web Playback API

The Rdio player API allows web developers to incorporate the playback of licensed Rdio music into their web applications. Rdio subscribers and trial users will be able to hear full-length songs and non-users will be able to hear music previews.

It consists of an Adobe Flash file (SWF) with simple JavaScript and ActionScript 3 APIs. It can only be used in compliance with the Rdio API terms and conditions.

There is a Playback API Console available that allows interactive experimentation with the API.

Playback Model

Rdio uses the concept of a source for playback. A source is a sequence of one or more tracks that can be played. Albums, playlists, stations and individual tracks are all different types of sources. In addition to the currently playing source, Rdio can maintain a queue of sources to be played after the current source completes playing. You can see this in action on the rdio.com site. Each Rdio player SWF will have its own current source and queue.

JavaScript Interface

The API SWF must be embedded from http://www.rdio.com/api/swf/ with the following flashvars arguments:

playbackToken

a valid playback token, retrieved from the getPlaybackToken Web Service API method

domain

the domain that the SWF will be embedded in

listener

the name of a JS object to receive callbacks

The easiest way to embed the SWF is probably to use the SWFObject library.

Status callbacks will be called on whatever object was passed in as the callback parameter. For example if foo was supplied then the ready callback will be called as window.foo.ready().

Methods can be called directly on the embed object — the <embed> or <object> tag's DOM node. Since Flash itself defines some methods all methods are prefixed with rdio_.

To call the play method on an API SWF with ID bar you could call:
document.getElementById('bar').rdio_play()
No methods may be called until the ready callback has been received. All calls are asynchronous, state changes will be reflected through callbacks, not through method return codes.

A complete example is available in Github: https://github.com/rdio/hello-web-playback

jQuery Interface

Rdio provides a jQuery library to simplify embedding and interacting with the Web Playback SWF. It is available on GitHub: https://github.com/rdio/jquery.rdio.js. jquery.rdio.min.js should be included after jQuery itself.

The library will embed the SWF inside a placeholder HTML element. Callbacks are exposed as jQuery events on that placeholder element.

If the placeholder is a <div id="api">, the SWF can be embedded with:
$('#api').rdio(playbackToken)
where playbackToken is a valid playback token from the getPlaybackToken Web Service API method.

Callbacks are exposed as jQuery events in the rdio namespace, so the ready event could be captured as:
('#api').bind('ready.rdio', function(event, userInfo) { ... });
Callback arguments become event handler arguments, after the event argument.

Call methods like: $('#api').rdio().play('a997982');

A complete example is available in Github: https://github.com/rdio/jquery.rdio.js/blob/master/example/example.html

ActionScript 3 Interface

The API SWF must be loaded from http://www.rdio.com/api/swf/ and with two query string arguments:

playbackToken

a valid playback token, retrieved from the getPlaybackToken Web Service API method

domain

the domain that the SWF will be embedded in

For example, with a domain of www.example.com and a playbackToken of WXYZ you would load:
http://www.rdio.com/api/swf/?domain=www.example.com&playbackToken=WXYZ

Callbacks are implemented as AS3 events. Once the movie has loaded (Event.INIT) event handlers can be attached to the Rdio object. No calls should be made until the rdioReady event is received. Callback arguments are available as properties on the event object.

This is a brief example:

Security.allowDomain("www.rdio.com");
var rdio : Object = null;
loader = new Loader();
loader.contentLoaderInfo.addEventListener(Event.INIT, function() {
  rdio = loader.content;
  rdio.addEventListener("rdioReady", 
    function(event : Event) : void { rdio.play("a997982"); });
  rdio.addEventListener("playingTrackChanged", playingTrackChanged);
});
loader.load(new URLRequest("http://www.rdio.com/api/swf/?"+
  'domain='+encodeURIComponent(domain)+'&'+
  'playbackToken='+encodeURIComponent(playbackToken)));

A complete example is also available in Github: https://github.com/rdio/hello-flash-playback

Methods

The Rdio object exposes a set of methods to fully control playback. From JavaScript the methods are called on the embed object. From ActionScript 3 they are called on the loaded movie object.

play

Begins playback. It can take two optional arguments, a key string that indicates a new source to play and an options object. When they're not passed in it either resumes play or plays the next item in the queue. If they are passed in, the current playing source is replaced with the specified one. Currently the only supported option is initialPosition, a number that indicating the number of seconds into the track to begin playing from.

pause

Pauses playback. It can be resumed by calling play with no source specified.

stop

Stops playback.

next

Skips to the next track. It takes an optional superSkip boolean parameter. If you pass true then it will skip to the start of the next source in the queue.

previous

Skips to the beginning of the current track, or if already at the beginning, to the beginning of the previous track.

seek

Seeks within the currently playing track. It takes a position number argument for the number of seconds into the track to seek.

setShuffle

Enables or disables shuffle, based on the boolean shuffle argument.

setRepeat

Sets the repeat mode based on an integer argument mode that can either be: 0 → no-repeat, 1 → track-repeat or 2 → whole-source-repeat.

queue

Adds a source to the end of the queue.

setVolume

Sets the playback volume, expressed as a number in the range 0 to 1.

setMute

Mutes or unmutes playback base on a boolean argument.

playQueuedTrack

Moves the source at position into playback and plays track offset within that source.

moveQueuedSource

Reorders the queue so that the source at position from is now at to.

clearQueue

Clears the queue.

setCurrentPosition

Sets the position within the currently playing source to sourcePosition. For example, if there's an album playing currently then setCurrentPosition(5) will move playback to the 6th track on the album.

removeFromQueue

Remove the source at sourceIndex from the queue.

sendState

Pass all of the player state out to the page via the callback interface.

startFrequencyAnalyzer

Begin frequency analysis. Options is an object that can include:

period: how often to report data, integer milliseconds (default is 50)
frequencies: the frequency bands to return, 4-band, 4-band-visual, 8-band, 10-band, 26-band, 31-band, or raw.

stopFrequencyAnalyzer

Stop frequency analysis.

Callbacks

ready(userInfo)

Called once the API SWF has loaded and is ready to accept method calls. The userInfo is an object with four boolean members indicating the current Rdio user's subscription state: isSubscriber (an Rdio subscriber), isTrial (an Rdio trial account), isFree (an Rdio free account), isUnlimited (an unlimited account). There's also a freeRemaining number member that indicates the percentage of a free user's quota is remaining.

playStateChanged(playState)

The playback state has changed. The state can be: 0 → paused, 1 → playing, 2 → stopped, 3 → buffering or 4 → paused.

playingTrackChanged(playingTrack, sourcePosition)

The currently playing track has changed. Track metadata is provided as playingTrack and the position within the playing source as sourcePosition.

playingSourceChanged(playingSource)

The currently playing source changed. The source metadata, including a track listing is inside playingSource.

volumeChanged(volume)

The volume changed to volume, a number between 0 and 1.

muteChanged(mute)

Mute was changed. mute will either be true (for muting enabled) or false (for muting disabled).

positionChanged(position)

The position within the track changed to position seconds. This happens both in response to a seek and during playback.

queueChanged(newQueue)

The queue has changed to newQueue.

shuffleChanged(shuffle)

The shuffle mode has changed. shuffle is a boolean, true for shuffle, false for normal playback order.

repeatChanged(repeat)

The repeat mode change. repeat will be one of: 0 → no-repeat, 1 → track-repeat or 2 → whole-source-repeat.

updateFrequencyData(frequencyData)

Receive a frequency update. The data comes as a string that is a comma separated array of floats in the range 0-1.

playingSomewhereElse()

An Rdio user can only play from one location at a time. If playback begins somewhere else then playback will stop and this callback will be called.

freeRemainingChanged(freeRemaining)

The percentage of free tracks remaining changed. This number will descend towards zero as the user plays more. When freeRemaining reaches 1 then there is just one last song to play.