Updating Extensions for Songbird 1.0

The New World Order (An Introduction to the new API)

The IDL files describing and documenting the new Media Core API can be found in the mediacore component in OpenGrok.  Previously we had a hodgepodge of interfaces hanging off of the PlaylistPlaybackService, now we have a considerably more structured interface.  The root of everything interesting starts with the sbIMediacoreManager.  From this object, we can get references to all the various sequencers, balance controls, playback controls, etc. that we'd need to invoke playback control, observe currently playing views and items, and attach listeners.  We recommend taking a look through the IDL file for sbIMediacoreManager to familiarise yourself with the organisation and hierarchy.  We've highlighted some of the most often used members and functions here below:

sbIMediaCoreManager

Listeners (sbIMediacoreEventListener)

Listening for media core events is now greatly simplified.  You simply create an object that implements the sbIMediacoreEventListener interface, which is composed simply of one function:

void onMediacoreEvent(in sbIMediacoreEvent aEvent)

Once your listener is attached, its onMediacoreEvent member method will be called for every media core event generated by the Media Core Manager, or one of its members (e.g. sequencer, the media cores themselves, etc.).  onMediacoreEvent is passed an sbIMediacoreEvent.  This event's interface has 5 key members:

• type = The event type (as listed in the sbIMediacoreEvent interface)
• error = An sbIMediacoreError, which you can debug if your type is ERROR_EVENT
• data = The actual event data/payload.
  • This varies depending on the event type, please consult the IDL for the latest descriptions of what data will be for the various event types.  For track change events, this will be the sbIMediaItem, for volume change, this will be the new volume level, etc.
    
• origin = The sbIMediacore that generated the event itself
• target = An sbIMediacoreEventTarget pointing to the event target that dispatched the actual event

Listener (Track Change/Stop) Example

For an example of how to add a listener that observes track changes, please see our Media Playback Recipe.

Hide/Show Display Pane Buttons

Inspired by atrieu's Display Pane Buttons add-on, we've built in similar functionality for showing/hiding display panes.  While this is no different from toggling display panes being visible/hidden from the menubar, this does mean that users are more likely to unload/load your add-ons.  If you have an add-on that responds to media playback state, you might already be listening for media core events such as track changes, etc.  To ensure your add-on properly initialises when being hidden/re-shown, you may want to check the currently playing state from your initialisation/onLoad routine and act accordingly.  For most add-ons this is as simple as doing the following:

if (typeof(gMM) == "undefined")
    var gMM = Cc["@songbirdnest.com/Songbird/Mediacore/Manager;1"]
             .getService(Ci.sbIMediacoreManager);

// Check to see if we're already playing something
if ((gMM.status.state == Ci.sbIMediacoreStatus.STATUS_PLAYING) ||
	(gMM.status.state == Ci.sbIMediacoreStatus.STATUS_PAUSED) ||
	(gMM.status.state == Ci.sbIMediacoreStatus.STATUS_BUFFERING))
{
	var currentItem = gMM.sequencer.currentItem;
	// Do something with the media item
}

Which Display Pane?

For add-ons which can be installed into different display panes, it can be helpful to determine which display pane you are currently being shown in.  To do this, we use the display pane manager (sbIDisplayPaneManager):

var displayPaneMgr = Cc["@songbirdnest.com/Songbird/DisplayPane/Manager;1"]
			.getService(Ci.sbIDisplayPaneManager);
var dpInstantiator = displayPaneMgr.getInstantiatorForWindow(window);
var myDisplayPane = dpInstantiator.displayPane;
// Do something neat

Once you have the display pane, you can check its ID to see if it's one of the following:

• displaypane_contentpane_bottom
• displaypane_right_sidebar
• displaypane_servicepane_bottom
  

Display Pane Header Tabs

This is a feature for add-ons, like mashTape, that wish to utilise as much space as possible.  For add-ons that may switch between different states (like mashTape with its News, Artist Info, Photo, and Video tabs), you can now embed XUL tab elements directly into the display pane header.

The first step is grab the display pane as covered previously.  You can then invoke the displayPane.enableTabs() method and pass it a pointer to your XUL tabpanels that you've defined.  Assuming you've got some XUL like:

<tabbox flex="1" orient="horizontal" id="my-tabbox">
    <tabpanels flex="1" id="my-tabpanels">
        <hbox><label value="Hello" /></hbox>
        <hbox><label value="World" /></hbox>
    </tabpanels>
</tabbox>

To enable tabs to hook up to these tabpanels, you can then run some Javascript like so:

var tabpanels = document.getElementById("my-tabpanels");
myDisplayPane.enableTabs(tabpanels);

To add tabs to the tabbar, you simply then run:

myDisplayPane.addTab("Tab1");
myDisplayPane.addTab("Tab2");

... and you will have hooked up the two tabs to the two tabpanels defined in your XUL.