Library

A Library is a collection of MediaItems and MediaLists.  It is possible to create a Library using the Songbird::siteLibrary function.

Inherits

MediaList 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 Also

Songbird MediaItem MediaList

Summary
A Library is a collection of MediaItems and MediaLists.
Set this property to true if you wish all new MediaItems created to be scanned for metadata.
Create a MediaItem from a URL.
Create a simple MediaList with the given name.
Create a MediaList from a URL.
Get the site media list with the given siteID.
Get an Enumerator containing all of the MediaLists in the Library.
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.
If this constant is specified when calling enumerateAllItems() or enumerateItemsByProperty(), the EnumerationListener will recieve a copy of the MediaItem instead of the MediaItem present in the MediaList.
If this constant is specified when calling enumerateAllItems() or enumerateItemsByProperty() the EnumerationListener will recieve the actual MediaItem from the MediaList.
The name of the media list.
The type of this media list.
The length (in number of items) present in the media list.
Is the MediaList empty?
Is the MediaList’s content user-editable?
Get a MediaItem from the MediaList by using it’s MediaItem::guid.
Get a MediaItem from the MediaList by using it’s index in the MediaList.
Enumerate all MediaItems in the MediaList.
Enumerate the MediaItems in the MediaList that have a certain property and value match.
Get the index for a MediaItem present in the MediaList.
Get the last index for a MediaItem present in the MediaList.
Verify that this MediaList contains the requested MediaItem.
Add a MediaItem to this MediaList.
Add all the MediaItems from a MediaList into this MediaList.
Remove the first occurrence of the given MediaItem from this MediaList.
Remove a MediaItem from the MediaList using it’s index.
Clear the MediaList.
Get all distinct (unique) values in this MediaList for a given property.

Library Properties

scanMediaOnCreation

Set 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.

Note

This property defaults to true.

Type

Boolean

Library Methods

createMediaItem()

Create a MediaItem from a URL.  You may pass in http and https URLs.  Local file URLs are not permitted.

Prototype

MediaItem createMediaItem(String url)

Parameters

urlA URL referring to a media file.

Returns

The newly created MediaItem.

Throws

Invalid 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.");
}
}

Note

Metadata for the MediaItems may get updated and overwritten during playback.  See Metadata Updates for more details about cases where metadata may get updated.

See Also

createSimpleMediaList() createMediaListFromURL()

createSimpleMediaList()

Create a simple MediaList with the given name.

Prototype

MediaList createSimpleMediaList(String name, String siteID)

Parameters

nameThe name of the MediaList to create.
siteIDAn optional siteID to assign.  If unspecified then the siteID will use the value passed for name.

Returns

The 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 Also

createMediaItem() 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.

Prototype

MediaList createMediaListFromURL(String url, Function callback)

Parameters

urlThe URL of the file to use for creating the MediaList.
callbackThe 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 Also

createMediaItem() createSimpleMediaList()

getMediaListBySiteID()

Get the site media list with the given siteID.

Prototype

MediaList getMediaListBySiteID(String siteID)

Paramters

nameThe siteID of the media list to fetch

Returns

The 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 Also

createSimpleMediaList()

getPlaylists()

Get an Enumerator containing all of the MediaLists in the Library.

Prototype

Enumerator getPlaylists()

Returns

An 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 Reference

Please see http://www.xulplanet.com- /references- /xpcomref- /ifaces- /nsISimpleEnumerator.html for nsISimpleEnumerator interface reference.

mostPlayedArtists

Get the most played artists from the Library.

Prototype

Array mostPlayedArtists

Returns

An array of the most played artistsup to 100.

Example

var 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>

Resource Properties

guid

The global unique identifier of this Library object.

Type

String

Note

MediaItem, MediaList and Library are all Library Objects.

Resource Methods

getProperty()

Get the value of a property for this library object.

Prototype

String getProperty(String id)

Parameters

idThe 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 Properties

http://songbirdnest.com/data/1.0#albumDetailUrlA URL with information on the album
http://songbirdnest.com/data/1.0#albumNameThe name of the album
http://songbirdnest.com/data/1.0#artistDetailUrlA URL with information on the artist
http://songbirdnest.com/data/1.0#artistNameThe name of the artist
http://songbirdnest.com/data/1.0#bitRateThe bit rate of the media, in bits per second
http://songbirdnest.com/data/1.0#bpmThe number of beats per minute
http://songbirdnest.com/data/1.0#columnSpecColumn display data
http://songbirdnest.com/data/1.0#composerNameThe name of the composer
http://songbirdnest.com/data/1.0#copyrightURLA URL with information on the copyright
http://songbirdnest.com/data/1.0#defaultColumnSpecDefault column display data
http://songbirdnest.com/data/1.0#disableDownloadPrevent this item from being downloaded
http://songbirdnest.com/data/1.0#discNumberThe number of disc this media appears on in a compilation
http://songbirdnest.com/data/1.0#downloadDetailsDownload state and progress
http://songbirdnest.com/data/1.0#durationThe duration of this media, in microseconds
http://songbirdnest.com/data/1.0#enableAutoDownloadwhether this item should be automatically downloaded when added to the main library
http://songbirdnest.com/data/1.0#excludeFromHistoryThis track should not be logged in playback history when played
http://songbirdnest.com/data/1.0#genreThe genre of this media
http://songbirdnest.com/data/1.0#hiddenWhether this item should be hidden from the user
http://songbirdnest.com/data/1.0#isPartOfCompilationWhether this media is part of a compilation
http://songbirdnest.com/data/1.0#lastPlayTimeThe last time the media was played
http://songbirdnest.com/data/1.0#lyricistNameThe name of the lyricist
http://songbirdnest.com/data/1.0#lyricsThe lyrics of the media
http://songbirdnest.com/data/1.0#originPageThe page this media was located on
http://songbirdnest.com/data/1.0#originPageTitleThe title of the page this media was located on
http://songbirdnest.com/data/1.0#originURLThe URL this media was retrived from
http://songbirdnest.com/data/1.0#playCountThe number of times this media has been played
http://songbirdnest.com/data/1.0#primaryImageURLThe URL of the primary image
http://songbirdnest.com/data/1.0#producerNameThe name of the producer
http://songbirdnest.com/data/1.0#ratingThe user-set rating of the item, either 0 (unset) or in the range 1-5
http://songbirdnest.com/data/1.0#recordLabelNameThe name of the record label
http://songbirdnest.com/data/1.0#sampleRateThe sample rate of the media, in samples per second
http://songbirdnest.com/data/1.0#skipCountThe number of times this item was skipped
http://songbirdnest.com/data/1.0#totalDiscsThe total number of discs in a compilation
http://songbirdnest.com/data/1.0#totalTracksThe total number of tracks in a compilation
http://songbirdnest.com/data/1.0#trackNameThe name of the track
http://songbirdnest.com/data/1.0#trackNumberThe track number of this media in a compilation
http://songbirdnest.com/data/1.0#yearThe year the media was released

Note

Metadata for the MediaItems may get updated and overwritten during playback.  See Metadata Updates for more details about cases where metadata may get updated.

See Also

setProperty()

setProperty()

Set the value of a property for this library object.

Prototype

setProperty(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 Properties

http://songbirdnest.com/data/1.0#albumDetailUrlA URL with information on the album
http://songbirdnest.com/data/1.0#albumNameThe name of the album
http://songbirdnest.com/data/1.0#artistDetailUrlA URL with information on the artist
http://songbirdnest.com/data/1.0#artistNameThe name of the artist
http://songbirdnest.com/data/1.0#bitRateThe bit rate of the media, in bits per second
http://songbirdnest.com/data/1.0#bpmThe number of beats per minute
http://songbirdnest.com/data/1.0#columnSpecColumn display data
http://songbirdnest.com/data/1.0#composerNameThe name of the composer
http://songbirdnest.com/data/1.0#defaultColumnSpecDefault column display data
http://songbirdnest.com/data/1.0#disableDownloadPrevent this item from being downloaded
http://songbirdnest.com/data/1.0#discNumberThe number of disc this media appears on in a compilation
http://songbirdnest.com/data/1.0#downloadDetailsDownload state and progress
http://songbirdnest.com/data/1.0#durationThe duration of this media, in microseconds
http://songbirdnest.com/data/1.0#enableAutoDownloadwhether this item should be automatically downloaded when added to the main library
http://songbirdnest.com/data/1.0#excludeFromHistoryThis track should not be logged in playback history when played
http://songbirdnest.com/data/1.0#genreThe genre of this media
http://songbirdnest.com/data/1.0#hiddenWhether this item should be hidden from the user
http://songbirdnest.com/data/1.0#isPartOfCompilationWhether this media is part of a compilation
http://songbirdnest.com/data/1.0#lyricistNameThe name of the lyricist
http://songbirdnest.com/data/1.0#lyricsThe lyrics of the media
http://songbirdnest.com/data/1.0#primaryImageURLThe URL of the primary image
http://songbirdnest.com/data/1.0#producerNameThe name of the producer
http://songbirdnest.com/data/1.0#ratingThe user-set rating of the item, either 0 (unset) or in the range 1-5
http://songbirdnest.com/data/1.0#recordLabelNameThe name of the record label
http://songbirdnest.com/data/1.0#sampleRateThe sample rate of the media, in samples per second
http://songbirdnest.com/data/1.0#totalDiscsThe total number of discs in a compilation
http://songbirdnest.com/data/1.0#totalTracksThe total number of tracks in a compilation
http://songbirdnest.com/data/1.0#trackNameThe name of the track
http://songbirdnest.com/data/1.0#trackNumberThe track number of this media in a compilation
http://songbirdnest.com/data/1.0#yearThe year the media was released

Note

Metadata for the MediaItems may get updated and overwritten during playback.  See Metadata Updates for more details about cases where metadata may get updated.

See Also

getProperty()

MediaItem Properties

contentSrc

The URI representing the location of the MediaItem.  If the URI is a URL, it may be QI’ed to an nsIURL.

Type

Number, in bytes.

contentType

The content type, also called mime type, of the MediaItem.

Type

String

Note

This property is never filled currently.

MediaList Constants

ENUMERATIONTYPE_SNAPSHOT

If this constant is specified when calling enumerateAllItems() or enumerateItemsByProperty(), the EnumerationListener will recieve a copy of the MediaItem instead of the MediaItem present in the MediaList.

Note

This is the suggested constant to be used when calling enumerateAllItems() or enumerateItemsByProperty().

Any properties changed on the copy of the MediaItem will also be reflected in the MediaItem present in the list.

Example

//This example assumes you already have a medialist in the variable named "mediaList".
//It also assumes that you have an enumeration listener in the variable named "enumListener".

mediaList.enumerateAllItems(enumListener, 0);

See Also

ENUMERATIONTYPE_LOCKING enumerateAllItems() enumerateItemsByProperty()

ENUMERATIONTYPE_LOCKING

If this constant is specified when calling enumerateAllItems() or enumerateItemsByProperty() the EnumerationListener will recieve the actual MediaItem from the MediaList.

Note

This is the suggested constant to use when attempting to change a lot of properties on MediaItems, or when you need to process them individually without calling any other functions on the MediaList during enumeration.

Example

//This example assumes you already have a medialist in the variable named "mediaList".
//It also assumes that you have an enumeration listener in the variable named "enumListener".

mediaList.enumerateAllItems(enumListener, 1);

See Also

ENUMERATIONTYPE_SNAPSHOT enumerateAllItems() enumerateItemsByProperty()

MediaList Properties

name

The name of the media list.

Type

String

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";

type

The type of this media list.

Type

String

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!");

length

The length (in number of items) present in the media list.

Type

Number

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.");

isEmpty

Is the MediaList empty?

Type

Boolean

Returns

trueMediaList is empty.
falseMediaList is not empty.

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);

//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;

userEditableContent

Is the MediaList’s content user-editable?

Type

Boolean

Returns

trueMediaList content can be modified by user.
falseMediaList 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.

MediaList Methods

getItemByGuid()

Get a MediaItem from the MediaList by using it’s MediaItem::guid.

Prototype

MediaItem getItemByGuid(String guid);

Parameters

guidThe global unique identifier (MediaItem::guid) of the MediaItem.

Returns

The MediaItem with the requested guid.

Throws

Not 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 Also

getItemByIndex() indexOf() lastIndexOf() contains()

getItemByIndex()

Get a MediaItem from the MediaList by using it’s index in the MediaList.

Prototype

MediaItem getItemByIndex(Number index)

Parameters

indexThe index of the MediaItem.  Index starts at 0.

Returns

The MediaItem present at the requested index.

Throws

Not 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 Also

getItemByGuid() indexOf() lastIndexOf() contains()

enumerateAllItems()

Enumerate all MediaItems in the MediaList.

Prototype

enumerateAllItems(EnumerationListener enumListener, Number enumType)

Parameters

enumListenerAn EnumerationListener object.  See example below.
[optional] enumTypeThe type of enumeration desired.  Valid values for enumType are ENUMERATIONTYPE_SNAPSHOT and ENUMERATIONTYPE_LOCKING.  Default is ENUMERATIONTYPE_SNAPSHOT.

Note

Do not use ENUMERATIONTYPE_LOCKING unless you fit a usage scenario described in the ENUMERATIONTYPE_LOCKING constant documentation.

Example

See Also

ENUMERATIONTYPE_SNAPSHOT ENUMERATIONTYPE_LOCKING enumerateItemsByProperty()

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”.

Prototype

enumerateItemsByProperty(String id, String value, EnumerationListener enumListener)

Parameters

idThe ID of the property to match.
valueThe value of the property to match.
enumListenerThe enumeration listener.
[optional] enumTypeThe type of enumeration desired.  Valid values for enumType are ENUMERATIONTYPE_SNAPSHOT and ENUMERATIONTYPE_LOCKING.  Defaults to ENUMERATIONTYPE_SNAPSHOT.

Example

See Also

ENUMERATIONTYPE_SNAPSHOT ENUMERATIONTYPE_LOCKING enumerateAllItems()

indexOf()

Get the index for a MediaItem present in the MediaList.

Prototype

Number indexOf(MediaItem mediaItem, Number startFrom)

Parameters

mediaItemThe MediaItem to find.
startFromIf specfied, the index position at which to start searching.  Index starts at 0.

Returns

The index where the MediaItem was first found.

Throws

Not 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 Also

lastIndexOf() contains()

lastIndexOf()

Get the last index for a MediaItem present in the MediaList.

Prototype

Number lastIndexOf(MediaItem mediaItem, Number startFrom)

Parameters

mediaItemThe MediaItem to find.
startFromThe index position at which to start searching.  Index starts at 0.

Returns

The last index where the MediaItem was first found.

Throws

Not 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 Also

indexOf() contains()

contains()

Verify that this MediaList contains the requested MediaItem.

Prototype

Boolean contains(MediaItem mediaItem)

Parameters

mediaItemThe MediaItem to verify.

Returns

trueThe MediaItem is present in the MediaList.
falseThe MediaItem is not present.

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);

//Check to see if mediaList contains mediaItem.
//The returned value in this case will be true.
var containsItem = mediaList.contains(mediaItem;

See Also

indexOf() lastIndexOf()

add()

Add a MediaItem to this MediaList.

Prototype

add(MediaItem mediaItem);

// additional forms ( Webpage API only )

add(MediaItem mediaItem [, boolean shouldDownload]);

add(String urlToMedia [, boolean shouldDownload]);

add(Array mediaItemURLArray [, boolean shouldDownload]);

Parameters

mediaItemThe MediaItem to add.
urlToMediaItemThe address of the <MediaItem>(s) to add.
mediaItemURLArrayAn array containing the address(es) of the <MediaItem>(s) to add.
shouldDownloada 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 Also

addAll() remove() removeByIndex() clear()

addAll()

Add all the MediaItems from a MediaList into this MediaList.

Prototype

addAll(MediaList mediaList)

Parameters

mediaListThe MediaList whose MediaItems are to be added.

Example

//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.

Prototype

remove(MediaItem mediaItem)

Parameters

mediaItemThe MediaItem to remove.

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 first occurrence of the mediaitem.
mediaList.remove(mediaItem);

... //Now only the second occurrence remains and it's index is now 0.

See Also

add() addAll() removeByIndex()

removeByIndex()

Remove a MediaItem from the MediaList using it’s index.

Prototype

removeByIndex(Number index)

Parameters

indexThe index of the MediaItem to remove.

Throws

Invalid 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 Also

add() addAll() remove()

clear()

Clear the MediaList.  This will remove all MediaItems from this MediaList.

Prototype

clear()

Note

This 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.

Prototype

Enumerator getDistinctValuesForProperty(String id)

Parameters

idThe ID of the property for which all distinct values are desired.

Returns

Enumerator, contains Strings.

Example

See Also

enumerateItemsByProperty()

getProperty()

A Library is a collection of MediaItems and MediaLists.
A MediaItem represents a partial or whole piece of media.
A MediaList is a list of MediaItems.
Enumerate all MediaItems in the MediaList.
Enumerate the MediaItems in the MediaList that have a certain property and value match.
The global unique identifier of this Library object.
Access to a sitelibrary for the current scope (domain and path).
The Songbird object provides several pieces of functionality to your web page: playback, download, listener adding and removing and library creation and retrieval.
When a MediaItem gets played, it’s metadata may change because the playback core is offering new metadata about this MediaItem that wasn’t available when metadata was first read from it because it was added to a Library.
Create a simple MediaList with the given name.
Create a MediaList from a URL.
Create a MediaItem from a URL.
Set the value of a property for this library object.
Get the value of a property for this library object.
If this constant is specified when calling enumerateAllItems() or enumerateItemsByProperty() the EnumerationListener will recieve the actual MediaItem from the MediaList.
If this constant is specified when calling enumerateAllItems() or enumerateItemsByProperty(), the EnumerationListener will recieve a copy of the MediaItem instead of the MediaItem present in the MediaList.
Get a MediaItem from the MediaList by using it’s index in the MediaList.
Get the index for a MediaItem present in the MediaList.
Get the last index for a MediaItem present in the MediaList.
Verify that this MediaList contains the requested MediaItem.
Get a MediaItem from the MediaList by using it’s MediaItem::guid.
Add all the MediaItems from a MediaList into this MediaList.
Remove the first occurrence of the given MediaItem from this MediaList.
Remove a MediaItem from the MediaList using it’s index.
Clear the MediaList.
Add a MediaItem to this MediaList.