Songbird

The Songbird object provides several pieces of functionality to your web page: playback, download, listener adding and removing and library creation and retrieval.

This object provides you with functions that enable you to initiate playback of URL’s, MediaLists and WebPlaylists.  Basic playback control functions are also provided.

The Songbird object provides download functionality as well.  You may use it to download MediaItems, MediaLists and user selected items present in the WebPlaylist.

You may listen for download events by adding “downloadstart” or “downloadcomplete” event listeners to the document object.  These events will only be sent to handlers within the scope of the page that originated the downloaded items.  The event listener is provided the downloaded media item within the main Songbird library.  To access the media item properties, the user must have enabled remote access to the main Songbird library.

The Songbird object is accessible (from Javascript) using the “songbird” global variable attached to the currently loaded document.  See the example below.

Example

<script>
//Get the currently playing artist.
var artist = songbird.currentArtist;

//Create default library with current domain and path automatically guessed.
//This is the suggested way to create your site library.
var library = songbird.siteLibrary;

// Look up the artist in your web service database
// ...

//Create a media item from a file
var mediaItem = library.createMediaItem("http://mirrors.creativecommons.org/ccmixter/contrib/Wired/David%20Byrne%20-%20My%20Fair%20Lady.mp3");

//Create a simple media list.
var mediaList = library.createSimpleMediaList("PlaylistName");

//Add a mediaitem to it.
mediaList.add(mediaItem);

//Play it.
songbird.playMediaList(mediaList, 0);

//You may also want to trigger a download to the users machine, for this mediaitem.
function onDownloadComplete(aEvent) {
// The event item is the one in the user's main library.
alert(aEvent.item.guid);
alert(aEvent.status);
}
document.addEventListener("downloadcomplete", onDownloadComplete, false);
songbird.downloadItem(mediaItem);
</script>

See Also

For more information about the MediaItem object, see the MediaItem reference.  For more information about the MediaList object, see the MediaList reference.  For more information about the WebPlaylist object, see the WebPlaylist reference.

Summary
The Songbird object provides several pieces of functionality to your web page: playback, download, listener adding and removing and library creation and retrieval.
The name of the player.
The name of the artist for the currently playing track.
The name of the album for the currently playing media item.
The track name of the currently playing media item.
This is the playing state of the application.
This is the pause state of the application.
The shuffle state for playback.
The location of playback within the current media, in milliseconds.
The volume of the application on a range from 0 to 255.
True if muted or the volume is set to 0, false otherwise
The collection of Commands associated with the current page.
The current WebPlaylist object associated with this <Player> instance.
The main Library for Songbird.
The web Library for Songbird.
Access to a sitelibrary for the current scope (domain and path).
This MediaList is the list that gets all the MediaItemss that get added throught the 3 download methods.
Add a listener to get notified of changes to Songbird metadata and state.
Remove a listener that was previously added using addListener.
Download a MediaItem.
Download a MediaList.
Download the MediaItems selected by the user in a WebPlaylist.
play()
Begin playback of a MediaList at the specified index in the list.
Begin playback of a URL.
Stop playback.
Pause playback.
Skip to the next item, if there is one, and begin playing.
Skip to the previous item, if there is one, and begin playing.
Set the scope for which to access site-specific privilegs such as the siteLibrary.
Access to any library in the system via path or ‘magic’ keyword.
Check if the code has access to a category.
Properties define the list of available columns, as well as provide a means of storing data about a MediaItem.
Add a text property to the system that will be available for all media items.
Add a date time property to the system that will be available for all media items.
Add a URI property to the system that will be available for all media items.
Add a number property to the system that will be available for all media items.
Add an image property to the system that will be available for all media items.
Add a ratings property to the system that will be available for all media items.
Add a button property to the system that will be available for all media items.
Add a download button property to the system that will be available for all media items.

Properties

name

The name of the player.

Type

String

currentArtist

The name of the artist for the currently playing track.

Type

String

currentAlbum

The name of the album for the currently playing media item.

Type

String

currentTrack

The track name of the currently playing media item.

Type

String

playing

This is the playing state of the application.  If stopped this will be false, otherwise this will be true.  If the application is paused this will be true so for a complete status you need to check the paused state as well.

Type

boolean

paused

This is the pause state of the application.  This will be true if the application has been paused during playback.  It will be false if not paused or stopped.

Type

boolean

repeat

The repeat state for playback.  This can be one of three values

0no repeat
1repeat the current track forever
2repeat the current playlist forever

Type

integer

shuffle

The shuffle state for playback.  This will be true if shuffle is enabled, false otherwise.

Type

boolean

position

The location of playback within the current media, in milliseconds.

Type

integer

volume

The volume of the application on a range from 0 to 255.

Type

integer

mute

True if muted or the volume is set to 0, false otherwise

Type

boolean

commands

The collection of Commands associated with the current page.

Type

Commands

webPlaylist

The current WebPlaylist object associated with this <Player> instance.

Type

WebPlaylist

mainLibrary

The main Library for Songbird.  This will contain all the MediaItems the user has on their system.

Type

Library

Example

var mainLib = songbird.mainLibrary;

See Also

webLibrary libraries() siteLibrary

webLibrary

The web Library for Songbird.  This will contain all the MediaItems that have been discovered on web pages the user has visited.

Type

Library

Example

var webLib = songbird.webLibrary;

See Also

mainLibrary libraries() siteLibrary

siteLibrary

Access to a sitelibrary for the current scope (domain and path).  If you wish to change the scope, use setSiteScope().

If a library was already created for the scope, the existing library will be returned.

Type

Library

Example

//Access your site library
var library = songbird.siteLibrary;

See Also

setSiteScope()

downloadMediaList

This MediaList is the list that gets all the MediaItemss that get added throught the 3 download methods.  If the user has enabled downloading, tracks can be added to this playlist directly in order to begin downloads.

Type

MediaList

Example

// Get the download media list
var dlList = songbird.downloadMediaList;

See Also

downloadItem() downloadList() downloadSelected()

Methods

addListener()

Add a listener to get notified of changes to Songbird metadata and state.

Prototype

addListener(String key, Object listener)

Parameters

keyThe key for the metadata or state value.
listenerThe listener that will get called when the metadata or state value specified by the key changes.

Example

//Make a listener object. The listener must always have at least this function.

//You may add any number of functions and properties to it for your own use.

//Make sure to save this object somewhere so you may unregister it when you are done
//listening for changes.
var listener = {
observer: function(subject, topic, data) {
}
}

var key = "metadata.genre";

songbird.addListener(key, listener);

...

songbird.removeListener(key, listener);

See Also

removeListener()

Visit Listener Topics for a list of keys for metadata and state.

Visit http://www.xulplanet.com- /references- /xpcomref- /ifaces- /nsIObserver.html for nsIObserver interface reference.

removeListener()

Remove a listener that was previously added using addListener.

Prototype

removeListener(String key, Object listener)

Parameters

keyThe key for the metadata or state value.
listenerThe listener that was previously added using addListener.

Example

//This example assumes there was a listener object named 'listener' that was previously
//created and added using the key 'metadata.genre'.

...

var key = "metadata.genre";
songbird.removeListener(key, listener);

See Also

addListener()

downloadItem()

Download a MediaItemMediaLists and <Library>ies not allowed.

Prototype

downloadItem(MediaItem mediaItem)

Parameters

mediaItemThe MediaItem to download.

Example

//Create or get library.
var library = songbird.siteLibrary("", "");

//Create the mediaitem.
var mediaItem = library.createMediaItem("http://path/to/item.mp3");

//Download the mediaitem to the users local machine.
songbird.downloadItem(mediaItem);

See Also

downloadList() downloadSelected()

downloadList()

Download a MediaList.  As <Library>ies are MediaLists they are allowed here.

Prototype

downloadList(MediaList mediaList)

Parameters

mediaListThe MediaList to download.

Example

//Create or get site library.
var library = songbird.siteLibrary("", "");

//Create mediaitem.
var mediaItem = library.createMediaItem("http://path/to/item.mp3");

//Create medialist to download.
var mediaList = library.createSimpleMediaList("Name of List");

//Add item to medialist.
mediaList.add(mediaItem);

//Download the medialist.
songbird.downloadList(mediaList);

See Also

downloadItem() downloadSelected()

downloadSelected()

Download the MediaItems selected by the user in a WebPlaylist.

Prototype

downloadSelected(WebPlaylist webPlaylist)

Parameters

webPlaylistThe WebPlaylist from which to download the selected MediaItems.

Example

//Download the mediaitems currently selected by the user in
//the current webplaylist.

songbird.downloadSelected(songbird.webPlaylist);

See Also

downloadItem() downloadList()

play()

Prototype

play()

Begin playback at the current location in the WebPlaylist.

Example

songbird.play();

Note

Metadata for the MediaItems may get updated and overwritten during playback.  See Metadata Updates for more details about cases where metadata may get updated.

See Also

playURL() playMediaList() pause() stop() previous() next()

playMediaList()

Begin playback of a MediaList at the specified index in the list.

Prototype

playMediaList(MediaList mediaList, Number index)

Parameters

mediaListThe MediaList to play.
indexWhere to start playing in the list.  Index starts at 0.

Example

//Songbird object implements Player.
//Play the media list, starting with item at index 2.

player.playMediaList(mediaList, 2);

Note

Metadata for MediaItems may get updated and overwritten during playback.  See Metadata Updates for more details about cases where metadata may get updated.

See Also

play() playURL() pause() stop() previous() next()

playURL()

Begin playback of a URL.

Prototype

playURL(String url)

Parameters

urlThe URL to play.

Example

songbird.playURL("http://path/to/item.mp3");

Note

Metadata for the MediaItem associated with this URL may get updated and overwritten during playback.  See Metadata Updates for more details about cases where metadata may get updated.

See Also

play() playMediaList() pause() stop() previous() next()

stop()

Stop playback.

Prototype

stop()

Example

songbird.stop();

See Also

play() playURL() playMediaList() pause() previous() next()

pause()

Pause playback.

Prototype

pause()

Example

songbird.pause();

See Also

play() playURL() playMediaList() stop() previous() next()

next()

Skip to the next item, if there is one, and begin playing.

If there is no next item playback will continue until the end of the current item.

Prototype

next()

Example

songbird.next();

See Also

play() playURL() playMediaList() pause() stop() previous()

previous()

Skip to the previous item, if there is one, and begin playing.

If there is no previous item playback will continue until the of the current item.

Prototype

previous()

Example

songbird.previous();

See Also

play() playURL() playMediaList() pause() stop() next()

setSiteScope()

Set the scope for which to access site-specific privilegs such as the siteLibrary.  By default, the page’s current domain and path is used.  Use an empty string for the domain and the path to use the default values.

Note

This may not be called more than once, and not after accessing the siteLibrary.  Accessing siteLibrary without calling setSiteScope() defaults to the most restrictive scope possible (i.e. full host name, deepest path).

Prototype

setSiteScope(String domain, String path)

Parameters

domainThe domain name of the library.  This may be an empty string.
pathThe path within the domain for the library.  This may be an empty string.

Example

// sets the site scope to TLD+1 (will throw unless the page was on *.example.com)
songbird.setSiteScope("example.com", "");
// sets the site scope to default values
// (will throw because it has already been set once)
songbird.setSiteScope("", "");

See Also

siteLibrary

libraries()

Access to any library in the system via path or ‘magic’ keyword.

Prototype

libraries(String libraryID)

Parameters

libraryIDLibrary ID you wish to access, this can be a path or ‘magic’ keyword.  Currently supported keywords are “main” and “web”.

Example

var libraryID = "web";
var library = songbird.libraries(libraryID);

See Also

siteLibrary

hasAccess()

Check if the code has access to a category.

Prototype

boolean hasAccess( String Category )

Parameters

CategoryThe category to check for access to.  See Security for a list of valid categories.

Example

...
if (songbird.hasAccess('Read Current'))
{
var artist = songbird.currentArtist;
}
...

Property Creation

Properties define the list of available columns, as well as provide a means of storing data about a MediaItem.  This section defines and explains the parameters for the various property creation methods below.

Common Parameters

IDA unique text id of the new property.  Does not need to be in URL format but that is a recommended format for ensuring uniqueness.
displayNameThe displayed name of the property.
readOnlyIf true this property’s value can NOT be edited by the user.
viewableIf true this property will be viewable in all locations of Songbird including the main library.
nullSortThe type of null sorting desired.  When sorted will empty values sort small or large; see below for more detail.

Specific Parameters

timeTypeDetermines the formatting of the datetime string.  Present only in createDateTimeProperty().
buttonLabelThe text displayed on a button.  Present only in createButtonProperty() and createDownloadButtonProperty().  For standard button properties the absence of this parameter at property creation allows buttons to have different text on them by setting the value of the property on various MediaItems.  That is not possible with download buttons as the value determines the state and therefore the display of the button.  The text for download buttons MUST be set at creation or the button will not have any and will not draw properly.

nullSort values

0Null values are infinitely small.  This is the default.
1Null values are infinitely large.
2Null values are always first (regardless of sort direction)
3Null values are always last

timeType values

-1Unintialized
02007-03-28 , in localized format
1HH:mm:ss.ms, in localized format.  Limited to 24 hour days.
2Long date format, 2007-03-28 12:33:01 , no milliseconds.
3Duration, represented in HH:mm:ss.ms, in localized format.  May exceed 24 hours
4Timestamp format, respects unix time, microsecond format.  Also internal storage type.

See

createTextProperty(), createDateTimeProperty(), createURIProperty(), createNumberProperty(), createImageProperty(), createRatingsProperty(), createButtonProperty(), createDownloadButtonProperty()

createTextProperty()

Add a text property to the system that will be available for all media items.  Properties define the set of possible columns available to the WebPlaylist

Prototype

createTextProperty ( in AString ID, in AString displayName, [optional] in boolean readOnly = false, [optional] in boolean viewable = false, [optional] in unsigned long nullSort = 0 )

Parameters

See Property Creation for a complete list of parameter types and their values.

Example

//This example assumes you already have created
//a mediaitem and assigned it to mediaItem.

// Create a property that indicates what store this item is from.
songbird.createTextProperty("http://example.com/Store",
"Store", true, false, 0);

// Add the store name to the media item
mediaitem.setProperty("Store", "Amazon");

See Also

createDateTimeProperty() createURIProperty() createNumberProperty() createImageProperty() createRatingsProperty() createButtonProperty() createDownloadButtonProperty()

createDateTimeProperty()

Add a date time property to the system that will be available for all media items.  Properties define the set of possible columns available to the WebPlaylist.  This property accept values for time in microseconds, 5 minutes 52 seconds would be a value of 352000000.  For the date based time types the time is the number of microseconds from the linux epoch: 1 January 1970 00:00:00 UTC.

Prototype

createDateTimeProperty ( in AString ID, in AString displayName, in PRInt32 timeType, [optional] in boolean readOnly = false, [optional] in boolean viewable = false, [optional] in unsigned long nullSort = 0 )

Parameters

See Property Creation for a complete list of parameter types and their values.

Example

//This example assumes you already have created
//a mediaitem and assigned it to mediaItem.

// Create a property of when this item was added to the store
songbird.createDateTimeProperty("http://example.com/DateAdded",
"Added", true, false, 0);

// Add the added date to the media item
mediaitem.setProperty("DateAdded", "4948575738");

See Also

createTextProperty() createURIProperty() createNumberProperty() createImageProperty() createRatingsProperty() createButtonProperty() createDownloadButtonProperty()

createURIProperty()

Add a URI property to the system that will be available for all media items.  Properties define the set of possible columns available to the WebPlaylist

Prototype

createURIProperty ( in AString ID, in AString displayName, [optional] in boolean readOnly = false, [optional] in boolean viewable = false, [optional] in unsigned long nullSort = 0 )

Parameters

See Property Creation for a complete list of parameter types and their values.

Example

//This example assumes you already have created
//a mediaitem and assigned it to mediaItem.

// Create a property that links to the store
songbird.createURIProperty("http://example.com/StoreLink",
"Store", true, false, 0);

// Add a url to the media item
mediaitem.setProperty("StoreLink", "http://www.store.com/item.php?id=1");

See Also

createTextProperty() createDateTimeProperty() createNumberProperty() createImageProperty() createRatingsProperty() createButtonProperty() createDownloadButtonProperty()

createNumberProperty()

Add a number property to the system that will be available for all media items.  Properties define the set of possible columns available to the WebPlaylist

Prototype

createNumberProperty ( in AString ID, in AString displayName, [optional] in boolean readOnly = false, [optional] in boolean viewable = false, [optional] in unsigned long nullSort = 0 )

Parameters

See Property Creation for a complete list of parameter types and their values.

Example

//This example assumes you already have created
//a mediaitem and assigned it to mediaItem.

// Create a property that shows the price of this item
songbird.createNumberProperty("http://example.com/Price", "Price", true);

// Add a price to the media item
mediaitem.setProperty("Price", "0.99");

See Also

createTextProperty() createDateTimeProperty() createURIProperty() createImageProperty() createRatingsProperty() createButtonProperty() createDownloadButtonProperty()

createImageProperty()

Add an image property to the system that will be available for all media items.  Properties define the set of possible columns available to the WebPlaylist

Prototype

createImageProperty ( in AString ID, in AString displayName, [optional] in boolean readOnly = false, [optional] in boolean viewable = false, [optional] in unsigned long nullSort = 0 )

Parameters

See Property Creation for a complete list of parameter types and their values.

Example

//This example assumes you already have created
//a mediaitem and assigned it to mediaItem.

// Create a property that shows the logo of the store this item is from
songbird.createImageProperty("http://example.com/Logo",
"Logo", true, false, 0);

// Add a logo to the media item
mediaitem.setProperty("Logo", "http://www.domain.com/image.jpg");

See Also

createTextProperty() createDateTimeProperty() createURIProperty() createNumberProperty() createRatingsProperty() createButtonProperty() createDownloadButtonProperty()

createRatingsProperty()

Add a ratings property to the system that will be available for all media items.  Properties define the set of possible columns available to the WebPlaylist.

Prototype

createRatingsProperty ( in AString ID, in AString displayName, [optional] in boolean readOnly = false, [optional] in boolean viewable = false, [optional] in unsigned long nullSort = 0 )

Parameters

See Property Creation for a complete list of parameter types and their values.

Example

//This example assumes you already have created
//a mediaitem and assigned it to mediaItem.

// Create a property that shows what the average rating for this item is
songbird.createRatingsProperty("http://example.com/StoreRatings", "Ratings");

// Add a share button to the media item
mediaitem.setProperty("StoreRatings", "2");

See Also

createTextProperty() createDateTimeProperty() createURIProperty() createNumberProperty() createImageProperty() createButtonProperty() createDownloadButtonProperty()

createButtonProperty()

Add a button property to the system that will be available for all media items.  Properties define the set of possible columns available to the WebPlaylist

Prototype

createButtonProperty ( in AString ID, in AString displayName, in AString buttonLabel, [optional] in boolean readOnly = false, [optional] in boolean viewable = false, [optional] in unsigned long nullSort = 0 )

Parameters

See Property Creation for a complete list of parameter types and their values.

Example

//This example assumes you already have created
//a mediaitem and assigned it to mediaItem.

// Create a property that allows the user to share this item with others
songbird.createButtonProperty("http://example.com/ShareItem",
"Share", "Share Me", true, false, 0);

// Add a share button to the media item
mediaitem.setProperty("ShareItem", "Share me");

See Also

createDateTimeProperty() createURIProperty() createNumberProperty() createImageProperty() createRatingsProperty() createButtonProperty() createDownloadButtonProperty()

createDownloadButtonProperty()

Add a download button property to the system that will be available for all media items.  Properties define the set of possible columns available to the WebPlaylist.  The value to set on this button is a triple field value that includes the size of the object and the amount downloaded.  The fields are separated by ‘|’ characters.  The format is:

<mode>|<total size>|<current size>

Prototype

createDownloadButtonProperty ( in AString ID, in AString displayName, in AString buttonLabel, [optional] in boolean readOnly = false, [optional] in boolean viewable = false, [optional] in unsigned long nullSort = 0 )

Parameters

See Property Creation for a complete list of parameter types and their values.

Download Mode Types

0none
1new
2starting
3downloading
4paused
5complete

Example

//This example assumes you already have created
//a mediaitem and assigned it to mediaItem.

// Create a property that will allow the user to get the item (Download)
songbird.createDownloadButtonProperty("http://example.com/DownlodButton",
"Download", "Get", true, false, 0);

// Add a download button to the media item
mediaitem.setProperty("DownloadButton", "1|0|0");

See Also

createTextProperty() createDateTimeProperty() createURIProperty() createNumberProperty() createImageProperty() createRatingsProperty() createButtonProperty()

The Commands Object allows remote web pages to add and remove commands.
The WebPlaylist UI object.
A Library is a collection of MediaItems and MediaLists.
A MediaList is a list of MediaItems.
A MediaItem represents a partial or whole piece of media.
Add a listener to get notified of changes to Songbird metadata and state.
Access to a sitelibrary for the current scope (domain and path).
The web Library for Songbird.
Access to any library in the system via path or ‘magic’ keyword.
The main Library for Songbird.
Set the scope for which to access site-specific privilegs such as the siteLibrary.
Download a MediaItem.
Download a MediaList.
Download the MediaItems selected by the user in a WebPlaylist.
Remove a listener that was previously added using addListener.
When a MediaItem gets played, it’s metadata may change because the playback core is offering new metadata about this MediaItem that wasn’t available when metadata was first read from it because it was added to a Library.
Begin playback of a URL.
Begin playback of a MediaList at the specified index in the list.
Pause playback.
Stop playback.
Skip to the previous item, if there is one, and begin playing.
Skip to the next item, if there is one, and begin playing.
play()
Sites can check what security restrictions it has through the songbird javascript object using the Songbird::hasAccess() function.
Add a date time property to the system that will be available for all media items.
Add a button property to the system that will be available for all media items.
Add a download button property to the system that will be available for all media items.
Add a text property to the system that will be available for all media items.
Add a URI property to the system that will be available for all media items.
Add a number property to the system that will be available for all media items.
Add an image property to the system that will be available for all media items.
Add a ratings property to the system that will be available for all media items.
Properties define the list of available columns, as well as provide a means of storing data about a MediaItem.