User Tools

Site Tools


Events and Listeners

Nightingale'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 Nightingale player itself.

DOM Event Listeners (e.g. document.addEventListener())

Default/Standard Events

Nightingale augments the standard DOM events you can attach listeners to via document.addEventListener(). Specifically, Nightingale 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 playing¹
trackchange Fired immediately after a new track starts playing¹
playbackstopped Fired when playback is stopped
PlaylistCellClick FIXME Fired when the user clicks on an item in the WebPlaylist
RemoteAPIPermissionChanged Fired when the user changes Webpage API permissions via the Nightingale preferences
RemoteAPIPermissionDenied Fired when the user denies your webpage use of the Webpage API

¹Note: These get called even when the new track is the same as the last track played


var currentTrack;
var handleEvent = function(event) {
    if (event.type == "beforetrackchange") {
      alert("Ah... " + event.item.getProperty('') +
            ".  Weren’t they a one hit wonder?”);
    } else if (event.type == "trackchange") {
      alert(“Where’d you find “ +
            event.item.getProperty('') +
            “?  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");

Nightingale Listeners (e.g. songbird.addListener())

You can also add additional media player metadata listeners via the songbird.addListener() FIXME 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 FIXME.

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 FIXME defined off the global songbird object such as songbird.currentArtist which are often useful for explicitly querying to find out current metadata.

developer_center/recipe_book/webpage_api/events_and_listeners.txt · Last modified: 2013/12/28 11:05 by geekshadow