Events and Listeners
Songbird's Webpage API has a few different event-type mechanisms for observing and reacting to things going on. In addition to the usual document.addEventListener() mechanism, there is also a songbird.addListener() for watching media player events that occur within the Songbird player itself.
DOM Event Listeners (e.g. document.addEventListener())
Default/Standard Events:
Songbird augments the standard DOM events you can attach listeners to via document.addEventListener(). Specifically, Songbird handles the following additional events.
| downloadstart | Fired when a media item download is initiated via songbird.downloadItem(), downloadList(), downloadSelected(), or when items are added to the songbird.downloadMediaList list |
| downloadcomplete | Fired when the media item download is completed |
| beforetrackchange | Fired just before a new track starts playing1 |
| trackchange | Fired immediately after a new track starts playing1 |
| playbackstopped | Fired when playback is stopped |
| PlaylistCellClick | Fired when the user clicks on an item in the WebPlaylist |
| RemoteAPIPermissionChanged | Fired when the user changes Webpage API permissions via the Songbird preferences |
| RemoteAPIPermissionDenied | Fired when the user denies your webpage use of the Webpage API |
1 Note: These get called even when the new track is the same as the last track played
2 Note: This is in Songbird 0.6 and higher only.
Example:
var currentTrack;
var handleEvent = function(event) {
if (event.type == "beforetrackchange") {
alert("Ah... " + event.item.getProperty('http://songbirdnest.com/data/1.0#artistName') +
". Weren’t they a one hit wonder?”);
} else if (event.type == "trackchange") {
alert(“Where’d you find “ +
event.item.getProperty('http://songbirdnest.com/data/1.0#trackName') +
“? I thought they burned all the copies of that.”);
// cache the track for further look-up if you like
currentTrack = event.item;
}
}
document.addEventListener("beforetrackchange", handleEvent, false);
document.addEventListener("trackchange", handleEvent, false);
Custom/Command Events:
For every command you define (via songbird.commands.addCommand()), you can define custom events to be fired when that command is initiated. For example, to define your own command and associate code to be executed when the command is fired:
var onMyCommand = function onMyCommand(event) {
if (event.type == "my-command") {
alert("Yay. My command event fired.");
}
}
document.addEventListener( "my-command", onMyCommand, true );
songbird.commands.addCommand("action", "my-command",
"My Command", "Execute my whizzy command");
Songbird Listeners (e.g. songbird.addListener())
You can also add additional media player metadata listeners via the songbird.addListener() call. This call takes an observer object, and a topic to listen for as its arguments. The list of listener topics you can listen to can be found in our Webpage API Documentation.
For example, to have code that's executed when the user changes the volume or pauses/plays a track:
obs = {
observe: function ( aSubject, aTopic, aData) {
if (aTopic == "faceplate.volume") {
alert(aData + "?!?!? Turn it down or you'll go deaf!");
} else if (aTopic == "faceplate.paused" && aData) {
alert("Good, it's time for you to take a break anyway.");
}
}
}
songbird.addListener("faceplate.volume", obs);
songbird.addListener("faceplate.paused", obs);
Explicitly Querying/Polling for Data
From inside your event listeners, you may find it useful to poll to find the currently playing metadata. Songbird provides a number of properties defined off the global songbird object such as songbird.currentArtist which are often useful for explicitly querying to find out current metadata.
