Web Integration with the Webpage API

Introduction

Today, most media players lack a way to interact with your website. Whether your site is a music store, an music blog, a social media site, or anywhere you want to add rich media functionality, the Songbird Webpage API enables you to embed player functionality into your web site so it can interact with the Songbird media player.

Using Songbird out of the box, you can take advantage of useful integration features such as the ability to drag and drop songs from a website into your music library. But to provide more control over what gets displayed to web site users in Songbird, you'll want to use the Webpage API.

The Songbird Webpage API provides programmatic access to aspects of the media player relating to both presentation and media playback. Websites can add individual tracks or entire playlists and manipulate shuttle controls.

As an example, we'll show you how you can take your MP3 blog to the next level by integrating it with a state-of-the-art media player. Visitors to your website will be able to do everything with the media on your site that they now do with standalone media players. We'll assume you are already familiar with JavaScript and the basics of object-oriented design.

What is the Songbird object?

The Songbird object is a global object that contains within it all of the functionality necessary for playback, download, adding and removing event listeners, and creating and retrieving libraries. This object provides you with functions that enable you to initiate playback of URLs, MediaLists and WebPlaylists. You can also use it to download MediaItems, MediaLists and user selected items present in the WebPlaylist.

Because the Songbird object is built in JavaScript, websites benefit from a much greater level of integration than can be achieved with in-page Flash-based players. In addition, you can draw upon the experience of JavaScript developers in integrating a rich media experience with your website.

The Songbird object is accessible (from JavaScript) using the songbird global variable attached to the currently loaded document.

How to find out if your page is being displayed in Songbird

Not all visitors to your MP3 blog will have Songbird installed. Here's how to check to see if your page is being displayed in Songbird.

var hasSongbird = false;
if ( typeof (songbird) != "undefined" ) {
        hasSongbird = true;
        // or just do your songbird stuff here.
}

if (hasSongbird) {
}

Or:

var hasSongbird = (typeof(songbird) != "undefined");

if(hasSongbird) {
    // Here goes your code
}

Display what's playing

Songbird can tell you an awful lot about what's currently playing. You can get the current artist, title, and album statically just by asking for it.

var artist = songbird.currentArtist;
var album = songbird.currentAlbum;
var track = songbird.currentTrack;

In addition to information about what's currently playing, you can find out about player state by accessing the following properties on the songbird object:

songbird.playing; // true or false
songbird.paused; // true or false
songbird.repeat; // 0 (no repeat), 1 (repeat track), or 2 (repeat playlist)
songbird.shuffle; // true or false
songbird.position; // milliseconds
songbird.volume; // 0 to 255
songbird.mute; // true or false

Attaching as a listener

Having access to static data is nice, but because so many pages on the web today are dynamic, we allow sites to attach themselves as event listeners. This provides a notification when a value changes.

var observer = {
        observe: function ( aSubject, aTopic, aData) {
                // aTopic is 'metadata.title' and aData is it's value
                doSomething(aTopic, aData);
        }
};
window.onload = function() {
        songbird.addListener("metadata.title", observer);
};
window.onunload = function() {
        songbird.removeListener('metadata.title', observer);
};

Please see the Listener Topics list for all the metadata and state items that a page can attach to as a listener.

Create a Library

Media managed by Songbird contains a vast amount of metadata that can be used to help users with organization. Music can be organized by artist, album, genre, and so on. The most common way is to use a custom playlist. Songbird abstracts media into two entities: MediaItems & MediaLists.

MediaItems represent an individual item such as a song while MediaLists are lists of MediaItems representing playlists constructed from either the user's own media library, or from a website's content (which is abstractly represented by the SiteLibrary class)

The user's main library is represented by songbird.mainLibrary and contains all the media (represented as MediaItems) the user has in their Songbird media collection. The SiteLibrary contains the media the website wishes to present to the user. For example, if the website is a music store - the SiteLibrary would contain pointers to all the media the store is selling. If the website is an MP3 blog, it would contain all the media the blog has made available for playing or download.

The WebPlaylist that the user sees at the bottom of the Songbird browser is determined by the Webpage API which allows the website to assign an existing MediaList to the WebPlaylist.

Accessing the SiteLibrary creates a sandboxed library for the website. A site can set the "scope" of its library before accessing it, creating it in a manner that makes it available to more than a single page. The site rules work just like cookie permissions in that they take a domain and path and the calling website exists on both. This method keeps SiteB from accessing SiteA's SiteLibrary while allowing a page at SiteA/path/to/page1 create a SiteLibrary that can be accessed at SiteA/path/to/other/page2. Without setting the scope beforehand, the SiteLibrary uses the most restrictive setting, full path and domain.

// allow access to the siteLibrary for all pages on this domain
songbird.setSiteScope("", "/");
var library = songbird.siteLibrary;

Create or Retrieve a MediaList

First, we must create a MediaList. We are guaranteed access to the SiteLibrary, so let's use that to start with. The process of creating a list adds that list to the library used to create it. All media lists must be in a library somewhere. createSimpleMediaList() takes a parameter giving the name of the mediaList to create. It optionally takes a second string which is the site ID that uniquely identifies the media list. If not specified, the site ID defaults to the name. If a mediaList with the given name already exists, then createSimpleMediaList() simply retrieves the existing list and returns that. If no mediaList by that name exists, it will create it.

var myMediaList = songbird.siteLibrary.createSimpleMediaList("mylist");

Add Media to a MediaList

Now that we have an empty MediaList, let's put an mp3 track in it. Again we use the site library, this time to create a MediaItem that gets the URL to the track. The process of creating a MediaItem adds it to the SiteLibrary. Just like MediaLists, all MediaItems must be in a library somewhere. Creation of the MediaItem will cause a scan of the track and any embedded metadata is populated:

var myTrack = songbird.siteLibrary.createMediaItem("http://www.example.com/track.mp3");
myMediaList.add(myTrack);

Add a MediaList to a WebPlaylist

Now we have a MediaList with a MediaItem in it and we want to show it to website visitors. All we have to do is assign the MediaList to a WebPlaylist and it will be displayed below the page:

songbird.webPlaylist.mediaList = myMediaList;

It's important to note that any playlists already displayed (determined by scanning the webpage) will be replaced with calls from the Webpage API.

That's all you need to do to display specific media to the user. Users can drag from this playlist into their own local library.

Sort the WebPlaylist

Unlike Flash-based players, which typically show a fixed playlist, Songbird can display any information you want. This information can be sorted in the same way as a stand-alone media player. Not only does this provide the website with more control over the content, it also provides a much better experience for users, who expect this kind of flexibility from media players.

The WebPlaylist can be sorted as needed. To sort, the column containing data you want to sort by must be currently visible. We'll get to adding and removing columns in a minute. For now, let's just sort by album:

// Sort the tracks by album name, in ascending order.
songbird.webPlaylist.setSortColumn("http://songbirdnest.com/data/1.0#album", "a");

Setting Existing Properties

The default set of properties a MediaItem has are derived from the existing ID3 tag specification. You can change and set them via calls through to mediaItem.setProperty(). You will need to know the URI for the standard properties, which are listed in the setProperty() reference documentation, as well as in the file sbStandardProperties.h. The standard properties' URIs all start with http://songbirdnest.com/data/1.0.

For example, if we want to display a different album name than what has been automatically set from the ID3 tag:

var myTrack = songbird.siteLibrary.createMediaItem("http://www.example.com/track.mp3");
myTrack.setProperty("http://songbirdnest.com/data/1.0#albumName", "Best Album Ever");

Create New Properties

While the default set of properties provide a comprehensive set of properties most sites would want, you are free to add your own site-specific properties. The list of available columns is generated by looking at the properties of the tracks, so if a site wants a specific column to appear they should add it as a property first. For example, an MP3 blog may wish to add a column that lists the most popular songs on a site as rated by users. Properties don't need to be displayed as columns; by setting userViewable to false a site can define a property that is only available programmatically. For example, you might use this feature to store a link for an affiliate purchase program.

// Add our specific properties to the Songbird player
// The parameters are: ID, Display Name, Read Only, Hidden, & Null Sort
songbird.createImageProperty("http://example.com/ccImage", "CC", true, false, 0);
songbird.createTextProperty("http://example.com/userTags", "Tags", true, false, 0);

// create a hidden property on items to store the link to an affiliate program
songbird.createTextProperty("http://example.com/purchaseLink", "link", true, true, 0);

Add Columns

Now you can add your own site-specific columns for whatever special purposes your site requires. But before you can do that, you must first create a MediaList and assign it to a WebPlaylist. Otherwise there won't be any columns to display!

// add the columns we defined as properties earlier
songbird.webPlaylist.insertColumnBefore("http://example.com/ccImage", "http://songbirdnest.com/data/1.0#trackName");
songbird.webPlaylist.insertColumnBefore("http://example.com/userTags", "");

// we want to remove the genre column
songbird.webPlaylist.removeColumn("http://songbirdnest.com/data/1.0#genre");

Add Commands

You can add your own commands to Songbird that allow your MP3 blog to more easily integrate with Songbird and provide viewers with the ability to play, download, and even purchase songs.

The process of creating and making use of commands has a couple of steps to it. First you must tell Songbird you want to add a command. For instance, if we want to add a Download all option to the right-click/context menu as well as having it be a button just below the WebPlaylist at the bottom of the player:

// add a command that performs an action of type 'download-all'. Also defines the label and tooltip.
songbird.commands.addCommand( "action",
        "download-all",
        "Download All",
        "Download all tracks to your library." );

When a user clicks on either of the menu option or the button, an event is sent to the document with the type set to 'download-all'. We'll set up a handler for it:

// Here is our event handler
var handleEvent = function(event) {
        if (event.type == "download-all") {
                songbird.downloadList(songbird.webPlaylist.mediaList);
        }
}

// Now register it as a listener with the document.
document.addEventListener("download-all", handleEvent, true );

Now we're all set up to handle the download message and we'll tell Songbird to download the whole list displayed in the WebPlaylist when a user selects the "Download all" action.

addCommand allows you to specify a few different types; the one we demonstrated here, action, sets your command up in both the context menu and the button below the WebPlaylist. The benefit of this vs. placing button commands in the playlist area itself are that it saves screen real estate vs. having a column in your list. On the other hand, it's not as ideal for showing per-track context in the way that you can with columns/properties in the WebPlaylist.

More Functionality

This is just the beginning of what you can do with Songbird through the Webpage API. Take a look at our example of a music blog and see how you can set up commands that will download just what is selected, start playback and access properties of an item in order to purchase the track from an affiliate program.

Here are some more of the things you can do with the Webpage API:

• Provide a Favorites MediaList for your users to keep tracks from across your site in one place.
• Insert a column for logos that link to an affiliate program's page.
• Add a property to tracks that contains the in-house ID of the track for easy reference.
• Persist MediaLists and MediaItems between user visits.
• With user permission, view the contents of a users library to be able to make music suggestions.
• Listen to the progress of a track and change content in the page (like a background color) to provide a dynamic HTML vizualizer. (In the future we may be able to expose a simple DSP feed).
• Again, with user permission, create a library view in a page. Use open AJAX APIs to build dynamic menus, tag clouds or lists of users tracks and provide a complete interface to the users library (removal of tracks is blocked).

Also be sure to check out our complete Webpage API documentation page. This contains further API documentation on just what each object can do.

Further Information

• Webpage API documentation
• Webpage API discussion forum