LibraryA Library is a collection of MediaItems and MediaLists. It is possible to create a Library using the Songbird::siteLibrary function. InheritsMediaList MediaItem Example//Create or get a library. var library = songbird.siteLibrary("", "");
//Create a medialist using the library. var mediaList = library.createSimpleMediaList("Name of List");
//Create some mediaitems and add them to the medialist. var itemURLs = ["http://path/to/song.mp3", "http://path/to/another/song.mp3"]; for(var url in itemURLs) {
//Calling createMediaItem may throw an exception when it fails //to create the mediaitem.
try { var mediaItem = library.createMediaItem(url); mediaList.add(mediaItem); } catch(e) {
//Dump it. dump("Failed creation of mediaitem: " + e);
//Or alert it. alert("Failed creation of mediaitem: " + e);
//Oops the URL was not valid. if(e.result == Components.results.NS_ERROR_INVALID_ARG) { alert("The URL: " + url + " was not valid."); }
} }
See AlsoSongbird MediaItem MediaList Summary | | | | | Set this property to true if you wish all new MediaItems created to be scanned for metadata. | | | | | | Create a simple MediaList with the given name. | | | | Get the site media list with the given siteID. | | | | Get the most played artists from the Library. | | | | The global unique identifier of this Library object. | | | | Get the value of a property for this library object. | | Set the value of a property for this library object. | | | | The URI representing the location of the MediaItem. | | The content type, also called mime type, of the MediaItem. | | | | | | | | | | The name of the media list. | | The type of this media list. | | The length (in number of items) present in the media list. | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Get all distinct (unique) values in this MediaList for a given property. |
scanMediaOnCreationSet this property to true if you wish all new MediaItems created to be scanned for metadata. Set this property to false if you wish to skip scanning for metadata when MediaItems are created. If you are attempting to set all of your own metadata for MediaItems you create, you may set this to false to prevent your metadata from being overwritten. NoteThis property defaults to true. TypeBoolean
createMediaItem()Create a MediaItem from a URL. You may pass in http and https URLs. Local file URLs are not permitted. PrototypeMediaItem createMediaItem(String url) Parametersurl | A URL referring to a media file. |
ReturnsThe newly created MediaItem. ThrowsInvalid Argument (Components.results.NS_ERROR_INVALID_ARG) if the URL isn’t http or https. Example//Create or get a library. var library = songbird.siteLibrary("", "");
//Create the mediaitem from a url pointing to a media file. var mediaItem = null;
//This function may throw if it fails to create the item because //the URL is invalid. try { mediaItem = library.createMediaItem("http://path/to/file.mp3"); } catch(e) { //Oops, bad URL. if(e.result == Components.results.NS_ERROR_INVALID_ARG) { alert("Oops, the URL was not valid."); } }
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 AlsocreateSimpleMediaList() createMediaListFromURL()
createSimpleMediaList()Create a simple MediaList with the given name. PrototypeMediaList createSimpleMediaList(String name, String siteID) Parametersname | The name of the MediaList to create. | siteID | An optional siteID to assign. If unspecified then the siteID will use the value passed for name. |
ReturnsThe newly created MediaList or null. Example//Create or get a library. var library = songbird.siteLibrary("", "");
//Create an empty medialist. var mediaList = library.createSimpleMediaList("MyList");
See AlsocreateMediaItem() createSimpleMediaList() createMediaListFromURL()
createMediaListFromURL()Create a MediaList from a URL. The URL may point to an m3u, pls, rss or html file. After being created, the MediaList will contain all valid MediaItems it could create from the URLs it found in the file. PrototypeMediaList createMediaListFromURL(String url, Function callback) Parametersurl | The URL of the file to use for creating the MediaList. | callback | The optional function that gets called when the load is complete. This function is passed a single argument that is the newly created list. |
Example//Create or get a library. var library = songbird.siteLibrary("", "");
//Create the medialist from a url pointing to a file. library.createMediaListFromURL("http://path/to/file.m3u", function(list) { alert("loaded " + list.length + " items!"); } );
See AlsocreateMediaItem() createSimpleMediaList()
getMediaListBySiteID()Get the site media list with the given siteID. PrototypeMediaList getMediaListBySiteID(String siteID) Paramtersname | The siteID of the media list to fetch |
ReturnsThe corresponding media list, or null if not found Example//Create or get a library. var library = songbird.siteLibrary("", "");
//Fetch the shopping cart media list var mediaList = library.getMediaListBySiteID("Shopping Cart");
See AlsocreateSimpleMediaList()
getPlaylists()Get an Enumerator containing all of the MediaLists in the Library. PrototypeEnumerator getPlaylists() ReturnsAn Enumerator containing all of the MediaLists present in the Library. Example//Create or get a library. var library = songbird.siteLibrary("", "");
//Get all MediaLists. var mediaLists = library.getPlaylists();
while(mediaLists.hasMoreElements()) { var mediaList = mediaLists.getNext();
//Do something with the MediaList alert(mediaList.name); }
See Also<getArtists()> <albums> <genres> <years> External ReferencePlease see http://www.xulplanet.com- /references- /xpcomref- /ifaces- /nsISimpleEnumerator.html for nsISimpleEnumerator interface reference.
mostPlayedArtistsGet the most played artists from the Library. PrototypeArray mostPlayedArtists ReturnsAn array of the most played artists | up to 100. |
Examplevar artists = window.songbird.mainLibrary.mostPlayedArtists; for (var i in artists) { var elem = document.createElement('li'); elem.textContent = artists[i]; output.appendChild(elem); }
See Also<artists>
guidThe global unique identifier of this Library object. TypeString NoteMediaItem, MediaList and Library are all Library Objects.
getProperty()Get the value of a property for this library object. PrototypeString getProperty(String id) Parametersid | The ID property value requested. |
Example//This example assumes you already have created //a mediaitem and assigned it to mediaItem.
//Get the albumName property from a mediaitem. var albumName = mediaItem.getProperty("http://songbirdnest.com/data/1.0#albumName");
Standard Propertieshttp://songbirdnest.com/data/1.0#albumDetailUrl | A URL with information on the album | http://songbirdnest.com/data/1.0#albumName | The name of the album | http://songbirdnest.com/data/1.0#artistDetailUrl | A URL with information on the artist | http://songbirdnest.com/data/1.0#artistName | The name of the artist | http://songbirdnest.com/data/1.0#bitRate | The bit rate of the media, in bits per second | http://songbirdnest.com/data/1.0#bpm | The number of beats per minute | http://songbirdnest.com/data/1.0#columnSpec | Column display data | http://songbirdnest.com/data/1.0#composerName | The name of the composer | http://songbirdnest.com/data/1.0#copyrightURL | A URL with information on the copyright | http://songbirdnest.com/data/1.0#defaultColumnSpec | Default column display data | http://songbirdnest.com/data/1.0#disableDownload | Prevent this item from being downloaded | http://songbirdnest.com/data/1.0#discNumber | The number of disc this media appears on in a compilation | http://songbirdnest.com/data/1.0#downloadDetails | Download state and progress | http://songbirdnest.com/data/1.0#duration | The duration of this media, in microseconds | http://songbirdnest.com/data/1.0#enableAutoDownload | whether this item should be automatically downloaded when added to the main library | http://songbirdnest.com/data/1.0#excludeFromHistory | This track should not be logged in playback history when played | http://songbirdnest.com/data/1.0#genre | The genre of this media | http://songbirdnest.com/data/1.0#hidden | Whether this item should be hidden from the user | http://songbirdnest.com/data/1.0#isPartOfCompilation | Whether this media is part of a compilation | http://songbirdnest.com/data/1.0#lastPlayTime | The last time the media was played | http://songbirdnest.com/data/1.0#lyricistName | The name of the lyricist | http://songbirdnest.com/data/1.0#lyrics | The lyrics of the media | http://songbirdnest.com/data/1.0#originPage | The page this media was located on | http://songbirdnest.com/data/1.0#originPageTitle | The title of the page this media was located on | http://songbirdnest.com/data/1.0#originURL | The URL this media was retrived from | http://songbirdnest.com/data/1.0#playCount | The number of times this media has been played | http://songbirdnest.com/data/1.0#primaryImageURL | The URL of the primary image | http://songbirdnest.com/data/1.0#producerName | The name of the producer | http://songbirdnest.com/data/1.0#rating | The user-set rating of the item, either 0 (unset) or in the range 1-5 | http://songbirdnest.com/data/1.0#recordLabelName | The name of the record label | http://songbirdnest.com/data/1.0#sampleRate | The sample rate of the media, in samples per second | http://songbirdnest.com/data/1.0#skipCount | The number of times this item was skipped | http://songbirdnest.com/data/1.0#totalDiscs | The total number of discs in a compilation | http://songbirdnest.com/data/1.0#totalTracks | The total number of tracks in a compilation | http://songbirdnest.com/data/1.0#trackName | The name of the track | http://songbirdnest.com/data/1.0#trackNumber | The track number of this media in a compilation | http://songbirdnest.com/data/1.0#year | The year the media was released |
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 AlsosetProperty()
setProperty()Set the value of a property for this library object. PrototypesetProperty(String id, String value) Example//This example assumes you already have created //a mediaitem and assigned it to mediaItem.
//Set the albumName property from a mediaitem. mediaItem.setProperty("http://songbirdnest.com/data/1.0#albumName", "Let Us Play");
Standard Propertieshttp://songbirdnest.com/data/1.0#albumDetailUrl | A URL with information on the album | http://songbirdnest.com/data/1.0#albumName | The name of the album | http://songbirdnest.com/data/1.0#artistDetailUrl | A URL with information on the artist | http://songbirdnest.com/data/1.0#artistName | The name of the artist | http://songbirdnest.com/data/1.0#bitRate | The bit rate of the media, in bits per second | http://songbirdnest.com/data/1.0#bpm | The number of beats per minute | http://songbirdnest.com/data/1.0#columnSpec | Column display data | http://songbirdnest.com/data/1.0#composerName | The name of the composer | http://songbirdnest.com/data/1.0#defaultColumnSpec | Default column display data | http://songbirdnest.com/data/1.0#disableDownload | Prevent this item from being downloaded | http://songbirdnest.com/data/1.0#discNumber | The number of disc this media appears on in a compilation | http://songbirdnest.com/data/1.0#downloadDetails | Download state and progress | http://songbirdnest.com/data/1.0#duration | The duration of this media, in microseconds | http://songbirdnest.com/data/1.0#enableAutoDownload | whether this item should be automatically downloaded when added to the main library | http://songbirdnest.com/data/1.0#excludeFromHistory | This track should not be logged in playback history when played | http://songbirdnest.com/data/1.0#genre | The genre of this media | http://songbirdnest.com/data/1.0#hidden | Whether this item should be hidden from the user | http://songbirdnest.com/data/1.0#isPartOfCompilation | Whether this media is part of a compilation | http://songbirdnest.com/data/1.0#lyricistName | The name of the lyricist | http://songbirdnest.com/data/1.0#lyrics | The lyrics of the media | http://songbirdnest.com/data/1.0#primaryImageURL | The URL of the primary image | http://songbirdnest.com/data/1.0#producerName | The name of the producer | http://songbirdnest.com/data/1.0#rating | The user-set rating of the item, either 0 (unset) or in the range 1-5 | http://songbirdnest.com/data/1.0#recordLabelName | The name of the record label | http://songbirdnest.com/data/1.0#sampleRate | The sample rate of the media, in samples per second | http://songbirdnest.com/data/1.0#totalDiscs | The total number of discs in a compilation | http://songbirdnest.com/data/1.0#totalTracks | The total number of tracks in a compilation | http://songbirdnest.com/data/1.0#trackName | The name of the track | http://songbirdnest.com/data/1.0#trackNumber | The track number of this media in a compilation | http://songbirdnest.com/data/1.0#year | The year the media was released |
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 AlsogetProperty()
contentSrcThe URI representing the location of the MediaItem. If the URI is a URL, it may be QI’ed to an nsIURL. TypeNumber, in bytes.
contentTypeThe content type, also called mime type, of the MediaItem. TypeString NoteThis property is never filled currently.
nameThe name of the media list. TypeString Example//Create or get a library. var library = songbird.siteLibrary("", "");
//Create a medialist. var mediaList = library.createMediaList("simple");
//Give it a name. mediaList.name = "80's hits";
typeThe type of this media list. TypeString Example//Create or get a library. var library = songbird.siteLibrary("", "");
//Create a medialist. var mediaList = library.createMediaList("simple");
//Tell everyone this is a simple medialist. alert("Hello everyone, this is a " + mediaList.type + " medialist!");
lengthThe length (in number of items) present in the media list. TypeNumber Example//Create or get a library. var library = songbird.siteLibrary("", "");
//Create a mediaitem. var mediaItem = library.createMediaItem("http://path/to/item.mp3");
//Create a medialist. var mediaList = library.createMediaList("simple");
//Add same item twice. We now have mediaItem at index 0 and 1. mediaList.add(mediaItem); mediaList.add(mediaItem);
//Tell everyone there are 2 tracks in the medialist. alert("There are " + mediaList.length + " mediaitems in the medialist.");
isEmptyIs the MediaList empty? TypeBoolean ReturnsExample//Create or get a library. var library = songbird.siteLibrary("", "");
//Create a mediaitem. var mediaItem = library.createMediaItem("http://path/to/item.mp3");
//Create a medialist. var mediaList = library.createMediaList("simple");
//Add same item twice. We now have mediaItem at index 0 and 1. mediaList.add(mediaItem); mediaList.add(mediaItem);
//Clear the medialist. mediaList.clear();
//Check to see if the mediaList is empty. //The property in this case will be true. var empty = mediaList.isEmpty;
userEditableContentIs the MediaList’s content user-editable? TypeBoolean Returnstrue | MediaList content can be modified by user. | false | MediaList content should not be modified by user. |
userEditableContent lists have content that may be changed by the user. This is the default behavior. This attribute is different from sbILibraryResource.userEditable in that non-userEditable resources cannot be renamed or removed, while non- userEditableContent lists can. For instance, a medialist residing on a device that has been physically made readonly should not be deleted or renamed, and should not be added media items by the user (either via drag and drop, “send to” menus, or any other interactive method), its userEditable attribute will be set to false. On the other hand, a smart playlist is an instance of a list whose content is always read-only (its userEditableContent attribute is always false), but that may itself be read-write (if its userEditable attribute is true, the default): in this case, like in the previous one, media items should still not be added or removed from the list by the user (either via drag and drop, “send to” menu, or any other interactive method), but the list itself may still be removed from its parent library, renamed, as well as have its rule set modified by the user (which will yield content that may be different but will still be read-only). On the other hand, a smart playlist whose userEditable attribute is false cannot be renamed, removed, added tracks to, nor have its rule set modified by the user.
getItemByGuid()Get a MediaItem from the MediaList by using it’s MediaItem::guid. PrototypeMediaItem getItemByGuid(String guid); ParametersReturnsThe MediaItem with the requested guid. ThrowsNot Available (Components.results.NS_ERROR_NOT_AVAILABLE) when there is no MediaItem with the requested guid. Example//Create or get a library. var library = songbird.siteLibrary("", "");
//Create a mediaitem. var mediaItem = library.createMediaItem("http://path/to/item.mp3");
//Create a medialist. var mediaList = library.createMediaList("simple");
//Add same item twice. We now have mediaItem at index 0 and 1. mediaList.add(mediaItem);
//Get the same item by guid. var sameMediaItem = mediaList.getItemByGuid(mediaItem.guid);
See AlsogetItemByIndex() indexOf() lastIndexOf() contains()
getItemByIndex()Get a MediaItem from the MediaList by using it’s index in the MediaList. PrototypeMediaItem getItemByIndex(Number index) Parametersindex | The index of the MediaItem. Index starts at 0. |
ReturnsThe MediaItem present at the requested index. ThrowsNot Available (Components.results.NS_ERROR_NOT_AVAILABLE) when there is no MediaItem at the requested index. Example//Create or get a library. var library = songbird.siteLibrary("", "");
//Create a mediaitem. var mediaItem = library.createMediaItem("http://path/to/item.mp3");
//Create a medialist. var mediaList = library.createMediaList("simple");
//Add same item twice. We now have mediaItem at index 0 and 1. mediaList.add(mediaItem); mediaList.add(mediaItem);
//Get the mediaitem at index 1. var sameMediaItem = mediaList.getItemByIndex(1);
See AlsogetItemByGuid() indexOf() lastIndexOf() contains()
enumerateItemsByProperty()Enumerate the MediaItems in the MediaList that have a certain property and value match. This function is useful if you are looking for all items having, for example, an artistName value of “Tom Waits”. PrototypeenumerateItemsByProperty(String id, String value, EnumerationListener enumListener) Parametersid | The ID of the property to match. | value | The value of the property to match. | enumListener | The enumeration listener. | [optional] enumType | The type of enumeration desired. Valid values for enumType are ENUMERATIONTYPE_SNAPSHOT and ENUMERATIONTYPE_LOCKING. Defaults to ENUMERATIONTYPE_SNAPSHOT. |
Example
See AlsoENUMERATIONTYPE_SNAPSHOT ENUMERATIONTYPE_LOCKING enumerateAllItems()
indexOf()Get the index for a MediaItem present in the MediaList. PrototypeNumber indexOf(MediaItem mediaItem, Number startFrom) ParametersmediaItem | The MediaItem to find. | startFrom | If specfied, the index position at which to start searching. Index starts at 0. |
ReturnsThe index where the MediaItem was first found. ThrowsNot Available (Components.results.NS_ERROR_NOT_AVAILABLE) when the MediaItem cannot be found. Example//Create or get a library. var library = songbird.siteLibrary("", "");
//Create a mediaitem. var mediaItem = library.createMediaItem("http://path/to/item.mp3");
//Create a medialist. var mediaList = library.createMediaList("simple");
//Add same item twice. We now have mediaItem at index 0 and 1. mediaList.add(mediaItem); mediaList.add(mediaItem);
//Get the first occurrence of mediaItem. //The returned value in this case will be 0. var index = mediaList.indexOf(mediaItem, 0);
See AlsolastIndexOf() contains()
lastIndexOf()Get the last index for a MediaItem present in the MediaList. PrototypeNumber lastIndexOf(MediaItem mediaItem, Number startFrom) ParametersmediaItem | The MediaItem to find. | startFrom | The index position at which to start searching. Index starts at 0. |
ReturnsThe last index where the MediaItem was first found. ThrowsNot Available (Components.results.NS_ERROR_NOT_AVAILABLE) when the MediaItem cannot be found. Example//Create or get a library. var library = songbird.siteLibrary("", "");
//Create a mediaitem. var mediaItem = library.createMediaItem("http://path/to/item.mp3");
//Create a medialist. var mediaList = library.createMediaList("simple");
//Add same item twice. We now have mediaItem at index 0 and 1. mediaList.add(mediaItem); mediaList.add(mediaItem);
//Get the last occurrence of mediaItem. //The returned value in this case will be 1. var index = mediaList.lastIndexOf(mediaItem, 0);
See AlsoindexOf() contains()
contains()Verify that this MediaList contains the requested MediaItem. PrototypeBoolean contains(MediaItem mediaItem) ParametersReturnsExample//Create or get a library. var library = songbird.siteLibrary("", "");
//Create a mediaitem. var mediaItem = library.createMediaItem("http://path/to/item.mp3");
//Create a medialist. var mediaList = library.createMediaList("simple");
//Add same item twice. We now have mediaItem at index 0 and 1. mediaList.add(mediaItem); mediaList.add(mediaItem);
//Check to see if mediaList contains mediaItem. //The returned value in this case will be true. var containsItem = mediaList.contains(mediaItem;
See AlsoindexOf() lastIndexOf()
add()Add a MediaItem to this MediaList. Prototypeadd(MediaItem mediaItem); // additional forms ( Webpage API only ) add(MediaItem mediaItem [, boolean shouldDownload]); add(String urlToMedia [, boolean shouldDownload]); add(Array mediaItemURLArray [, boolean shouldDownload]); ParametersmediaItem | The MediaItem to add. | urlToMediaItem | The address of the <MediaItem>(s) to add. | mediaItemURLArray | An array containing the address(es) of the <MediaItem>(s) to add. | shouldDownload | a boolean indicating whether to download or not. It is optional and if absent defaults to FALSE. (only exposed on WebpageAPI calls currently). This only applies if this media list is in the main library. |
In the additional forms urls to the MediaItems can be passed directly to the MediaList for addition. The MediaItems will be created and added this MediaList. The additional forms are ONLY available through the WebpageAPI. Example//Create or get a library. var library = songbird.siteLibrary("", "");
//Create a mediaitem. var mediaItem = library.createMediaItem("http://path/to/item.mp3");
//Create a medialist. var mediaList = library.createMediaList("simple");
//Add same item twice. We now have mediaItem at index 0 and 1. mediaList.add(mediaItem);
//Alternate forms mediaList.add(mediaItem, false); // no download mediaList.add(mediaItem, true); // download mediaList.add("http://path/to/a/cool/item.mp3"); // no download mediaList.add("http://path/to/a/great/item.mp3", false); // no download mediaList.add("http://path/to/a/rockin/item.mp3", true); // download
mediaList.add(["http://path/to/another/cool/item.mp3", "http://path/to/another/great/item.mp3", "http://path/to/another/rockin/item.mp3"], true);
See AlsoaddAll() remove() removeByIndex() clear()
addAll()Add all the MediaItems from a MediaList into this MediaList. PrototypeaddAll(MediaList mediaList) ParametersExample//This example assumes you already have medialists in //variables named mediaListFrom and mediaListTo.
//Add all mediaitems from mediaListFrom to mediaListTo. mediaListTo.addAll(mediaListFrom);
remove()Remove the first occurrence of the given MediaItem from this MediaList. Prototyperemove(MediaItem mediaItem) ParametersExample//Create or get a library. var library = songbird.siteLibrary("", "");
//Create a mediaitem. var mediaItem = library.createMediaItem("http://path/to/item.mp3");
//Create a medialist. var mediaList = library.createMediaList("simple");
//Add same item twice. We now have mediaItem at index 0 and 1. mediaList.add(mediaItem); mediaList.add(mediaItem);
//Remove the first occurrence of the mediaitem. mediaList.remove(mediaItem);
... //Now only the second occurrence remains and it's index is now 0.
See Alsoadd() addAll() removeByIndex()
removeByIndex()Remove a MediaItem from the MediaList using it’s index. PrototyperemoveByIndex(Number index) ParametersThrowsInvalid Argument (Components.results.NS_ERROR_INVALID_ARG) when the MediaItem cannot be found. Example//Create or get a library. var library = songbird.siteLibrary("", "");
//Create a mediaitem. var mediaItem = library.createMediaItem("http://path/to/item.mp3");
//Create a medialist. var mediaList = library.createMediaList("simple");
//Add same item twice. We now have mediaItem at index 0 and 1. mediaList.add(mediaItem); mediaList.add(mediaItem);
//Remove the duplicate item. mediaList.removeByIndex(1);
See Alsoadd() addAll() remove()
clear()Clear the MediaList. This will remove all MediaItems from this MediaList. Prototypeclear() NoteThis is the preferred way to remove all MediaItems from a MediaList because it is optimized for speed. Example//Create or get a library. var library = songbird.siteLibrary("", "");
//Create a mediaitem. var mediaItem = library.createMediaItem("http://path/to/item.mp3");
//Create a medialist. var mediaList = library.createMediaList("simple");
//Add same item twice. We now have mediaItem at index 0 and 1. mediaList.add(mediaItem); mediaList.add(mediaItem);
... //Do something with the medialist.
//Clear the medialist. mediaList.clear();
//Check to see if the medialist is empty. //The property in this case will be true. var empty = mediaList.isEmpty;
getDistinctValuesForProperty()Get all distinct (unique) values in this MediaList for a given property. This function is useful if you want to know all the unique artistName property values for example. PrototypeEnumerator getDistinctValuesForProperty(String id) Parametersid | The ID of the property for which all distinct values are desired. |
ReturnsEnumerator, contains Strings. Example
See AlsoenumerateItemsByProperty() getProperty()
|