Songbird Web Page API Global Object Songbird |
SongbirdThe 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> See AlsoFor 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
siteLibraryAccess 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. TypeExample//Access your site library See AlsodownloadMediaListThis 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. TypeExample// Get the download media list See AlsoaddListener()Add a listener to get notified of changes to Songbird metadata and state. PrototypeaddListener(String key, Object listener) Parameters
Example//Make a listener object. The listener must always have at least this function. See AlsoVisit 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. PrototyperemoveListener(String key, Object listener) Parameters
Example//This example assumes there was a listener object named 'listener' that was previously See AlsodownloadItem()Download a MediaItem. MediaLists and <Library>ies not allowed. PrototypedownloadItem(MediaItem mediaItem) Parameters
Example//Create or get library. See AlsodownloadList()Download a MediaList. As <Library>ies are MediaLists they are allowed here. PrototypedownloadList(MediaList mediaList) Parameters
Example//Create or get site library. See AlsodownloadSelected()Download the MediaItems selected by the user in a WebPlaylist. PrototypedownloadSelected(WebPlaylist webPlaylist) Parameters
Example//Download the mediaitems currently selected by the user in See Alsoplay()Prototypeplay() Begin playback at the current location in the WebPlaylist. Examplesongbird.play(); NoteMetadata for the MediaItems may get updated and overwritten during playback. See Metadata Updates for more details about cases where metadata may get updated. See AlsoplayMediaList()Begin playback of a MediaList at the specified index in the list. PrototypeplayMediaList(MediaList mediaList, Number index) Parameters
Example//Songbird object implements Player. NoteMetadata for MediaItems may get updated and overwritten during playback. See Metadata Updates for more details about cases where metadata may get updated. See AlsoplayURL()Begin playback of a URL. PrototypeplayURL(String url) Parameters
Examplesongbird.playURL("http://path/to/item.mp3"); NoteMetadata 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 AlsosetSiteScope()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. NoteThis 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). PrototypesetSiteScope(String domain, String path) Parameters
Example// sets the site scope to TLD+1 (will throw unless the page was on *.example.com) See Alsolibraries()Access to any library in the system via path or ‘magic’ keyword. Prototypelibraries(String libraryID) Parameters
Examplevar libraryID = "web"; See AlsohasAccess()Check if the code has access to a category. Prototypeboolean hasAccess( String Category ) Parameters
Example... Property CreationProperties 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
Specific Parameters
nullSort values
timeType values
SeecreateTextProperty(), 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 PrototypecreateTextProperty ( in AString ID, in AString displayName, [optional] in boolean readOnly = false, [optional] in boolean viewable = false, [optional] in unsigned long nullSort = 0 ) ParametersSee Property Creation for a complete list of parameter types and their values. Example//This example assumes you already have created See AlsocreateDateTimeProperty() 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. PrototypecreateDateTimeProperty ( 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 ) ParametersSee Property Creation for a complete list of parameter types and their values. Example//This example assumes you already have created See AlsocreateTextProperty() 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 PrototypecreateURIProperty ( in AString ID, in AString displayName, [optional] in boolean readOnly = false, [optional] in boolean viewable = false, [optional] in unsigned long nullSort = 0 ) ParametersSee Property Creation for a complete list of parameter types and their values. Example//This example assumes you already have created See AlsocreateTextProperty() 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 PrototypecreateNumberProperty ( in AString ID, in AString displayName, [optional] in boolean readOnly = false, [optional] in boolean viewable = false, [optional] in unsigned long nullSort = 0 ) ParametersSee Property Creation for a complete list of parameter types and their values. Example//This example assumes you already have created See AlsocreateTextProperty() 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 PrototypecreateImageProperty ( in AString ID, in AString displayName, [optional] in boolean readOnly = false, [optional] in boolean viewable = false, [optional] in unsigned long nullSort = 0 ) ParametersSee Property Creation for a complete list of parameter types and their values. Example//This example assumes you already have created See AlsocreateTextProperty() 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. PrototypecreateRatingsProperty ( in AString ID, in AString displayName, [optional] in boolean readOnly = false, [optional] in boolean viewable = false, [optional] in unsigned long nullSort = 0 ) ParametersSee Property Creation for a complete list of parameter types and their values. Example//This example assumes you already have created See AlsocreateTextProperty() 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 PrototypecreateButtonProperty ( 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 ) ParametersSee Property Creation for a complete list of parameter types and their values. Example//This example assumes you already have created See AlsocreateDateTimeProperty() 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> PrototypecreateDownloadButtonProperty ( 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 ) ParametersSee Property Creation for a complete list of parameter types and their values. Download Mode Types
Example//This example assumes you already have created See AlsocreateTextProperty() createDateTimeProperty() createURIProperty() createNumberProperty() createImageProperty() createRatingsProperty() createButtonProperty() |