Complete JavaScript API technology framework

From Winamp Developer Wiki
Revision as of 04:29, 30 November 2010 by Culix (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Breadcrumb -- Wiki Main : Skin Developer : Visual Developer : Plug-in Developer : Online Service Developer : Articles Page : FAQ : Glossary

Contents

Overview

The purpose of the Winamp Online Service API is to allow content creators to interact with the Winamp client in order to provide to create custom experiences for their users based on the power of Winamp. The overall idea is to include exceptional web sites within Winamp Online Services.

The Winamp Online Service API is made up of methods that can be called from scripts within web pages rendered by the Winamp client. The API can be invoked using any scripting language supported by the Microsoft Internet Explorer web browser (5.5 and above). For simplicity, examples in this document will use JavaScript.

Setup

The Winamp Online Services API is designed to allow web pages, hosted (displayed) within the embedded browser of the Winamp client, to access the functionality of the client. There are several steps necessary to allow this to take place.

  1. Make sure you have the latest version of the Winamp client that supports online services.
  2. Make sure you have the latest version of the ml_webdev plugin (ml_webdev.dll). The presence of this plugin will create a "Web Dev Test Platform" within the Medial Library pane.
  3. In order to change the starting web page for the online service, start the Winamp client and configure the plugin.
    1. Select Options->Preferences->Plug-ins->Media Library.
    2. Select "API 2 Test Platform" and press "Configure selected plugin".
    3. On the Web Dev Preferences dialog, set the URL field to the URL of the initial web page for the online service. For example, file://c:\myonlineservice\webdev.html
  4. Click on "Web Dev Test Platform" in the Media Library. You may have to right click and choose refresh to see the new web page.

You should now see the initial page of your online service in the Winamp embedded browser.

window.external

The Winamp JavaScript API can be accessed through the window.external object in the Document Object Model (DOM) exposed by the IE browser control embedded within the Winamp client. The API methods can only be accessed thru the Winamp client and are not available if the web page is displayed outside of the client.

The invocation of all methods follow this form

window.external.API.Method

Properties can also be accessed using a similar form:

window.external.API.Property

Where API is a singleton class that defines a group of related methods (i.e., functionality). For example, Transport (Stop, Play, Next, etc) which controls the "buttons" of the Winamp player.

Method is a function you can call as part of a particular API. For example the following call will stop the Winamp client:

window.external.Transport.Stop();

Property is an internal variable for the particular API that can be queried and in some cases set. For example the following will provide access to the Winamp client shuffle "button":

var shuffle = window.external.Transport.shuffle;  // gets the current state
    OR
window.external.Transport.shuffle = true;         // turns on shuffle

See the documentation on each API below for a complete list of methods and properties.


Transport API

The Transport API is used to control the Winamp client. "Transport controls" was the name given to the buttons on the front panel that controlled hardware devices. This name is used in Winamp for the same purpose. It is also used to access information about the currently playing song.

The Transport API can also be used to register for events involved with asset playback. See the section Transport Events API.

Methods

Prev()

Transport.Prev() can be used to press the "Previous Track" button on the Winamp player. Invoking Prev() while an asset is already playing will cause the previous asset to begin playback immediately. Invoking Prev() while the player is stopped will cause the previous asset to play next time playback starts.

Prototype:

bool Prev();

Example:

var rc = window.external.Transport.Prev();

Return Value: A boolean value indicating whether the request was successful.

Play()

Transport.Play() can be used to press the "Play" button on the Winamp player. Invoking Play() on an asset already playing will cause the asset to restart playback. Pressing Play() on a paused asset will cause it to begin playing from its current position.


Prototype:

bool Play();

Example:

var rc = window.external.Transport.Play();

Return Value: A boolean value indicating whether the request was successful.

Pause()

Transport.Pause() can be used to press the "Pause" button on the Winamp player. Issuing Pause() again, or Play() will cause the asset to continue to play from the location where it was paused.

Prototype:

bool Pause();

Example:

var rc = window.external.Transport.Pause();

Return Value: A boolean value indicating whether the request was successful.

Stop()

Transport.Stop() can be used to press the "Stop" button on the Winamp player.

Prototype:

bool Stop();

Example:

var rc = window.external.Transport.Stop();

Return Value: A boolean value indicating whether the request was successful.

Next()

Transport.Next() can be used to press the "Next Track" button on the Winamp player. Invoking Next() while the player is stopped will cause the next asset to play next time playback starts.

Prototype:

bool Next();

Example:

var rc = window.external.Transport.Next();

Return Value: A boolean value indicating whether the request was successful.

GetMetadata()

Transport.GetMetadata() can be used to fetch metadata for the currently playing asset. The "tag" parameter is specific to different asset encoding formats so a knowledge of the metadata field names is necessary to request specific data about an asset. Some field names are common but others are specific to the encoding format of the asset.

Prototype:

string GetMetadata(tag);
where:
     tag = (string) identifier for the metadata to be returned.

Example:

var metaStr = window.external.Transport.GetMetadata("artist");

Return Value: A string value containing the requested metadata.

Properties

bool shuffle

Transport.shuffle provides access to the Winamp client shuffle "button".

Example:

 var isShuffling = window.external.Transport.shuffle; // get shuffle state
 window.external.Transport.shuffle = true;            // turns on shuffle

bool repeat

Transport.repeat provides access to the Winamp client repeat "button".

Example:

 var isRepeating = window.external.Transport.repeat; // get repeat state
 window.external.Transport.repeat = false;           // turns off repeat

int position

Transport.position provides access to the position being played within the current asset. Setting this value can change the location where playback occurs. position is in milliseconds.

Example:

 var position = window.external.Transport.position; // get position in current track
 window.external.Transport.position = 221559;       // move playback of the current track 
                                                    // to the specified position.

bool playing (read only)

Transport.playing indicates whether the Winamp Player is currently playing.

Example:

 var isPlaying = window.external.Transport.playing; // is player playing?

bool paused (read only)

Transport.paused indicates whether the Winamp Player has been paused.

Example:

 var isPaused = window.external.Transport.paused; // is player paused?

int length (read only)

Transport.length provides access to the length in seconds of the track currently playing.

Example:

 var length = window.external.Transport.length; // get length of current track in secs

string url (read only)

Transport.url provides access to the URL (or filename) of the track currently playing.

Example:

 var url = window.external.Transport.url; // get url of current track

string title (read only)

Transport.title provides access to the title of the track currently playing.

Example:

 var title = window.external.Transport.title; // get title of current track

Transport Events API

The Event mechanism of the Transport API allows javascript programmers to specify a callback method that will be invoked whenever certain Transport events take place. An Event object is passed back to the method from which properties can be accessed that provide more information about the event.

RegisterForEvents()

The RegisterForEvents() method can be used to specify a JavaScript function that is to be called when any Transport Events occur. An event object is passed that indicates the type of event.

Prototype:

boolean RegisterForEvents(handler);

Example:

var rc = window.external.Transport.RegisterForEvents(EventHandler);

Return value: boolean value indicating whether the request was successful.

UnregisterFromEvents()

The UnregisterFromEvents() method is used to stop receiving notifications about Transport events.

Note: The original handler used in RegisterForEvents() must be passed back into UnregisterFromEvents().

Prototype:

boolean UnregisterFromEvents(handler);

Example:

var rc = window.external.Transport.UnregisterFromEvents(EventHandler);

Return value: boolean value indicating whether the request was successful.

Events

The Transport API Event mechanism requires a JavaScript callback method that accepts a single parameter, a reference to a function. This function will be invoked with an "event" object that will indicate the type of event that occurred as well as contain properties containing more information about the event.

OnStop

The OnStop event is triggered when the Winamp client is stopped.

properties

integer event.position = contains the position within the file where the "Stop" was issued. position is the number of milliseconds from the start of the asset.

OnPlay

The OnPlay event is triggered when the Winamp client begins playback. If the client is paused and then restarted by "pressing Play", the OnPause event is triggered rather than an OnPlay event.

properties

string event.filename = contains the filename/URL of the asset starting playback.

OnPause

The OnPause event is triggered when the Winamp client is paused or unpaused. If the client is started after being paused, by "pressing Play", the OnPause event is triggered rather than an OnPlay event.

properties

boolean event.paused = true (the player was paused), false (the player was unpaused)

OnEndOfFile

The OnEndOfFile event is triggered when the player reaches the end of a track.

properties

None

Callback function

The callback function is invoked whenever a Transport event is detected. The callback function is specified in both the RegisterForEvents() and UnregisterFromEvents() methods. The method takes a single parameter, which is loaded with an object identifying the event that occurred.

Example:

function EventHandler(event){
{
    if (event.event == "OnStop"){
      alert("OnStop: position=" + event.position);
    }
    else if (event.event == "OnEndOfFile"){
      alert("OnEndOfFile");
    }
    else if (event.event == "OnPause"){
      alert("OnPause: paused=" + event.paused);
    }
    else if (event.event == "OnPlay"){
      alert("OnPlay: filename=" + event.filename);
    }
    else {
      alert("Unrecognized Event received");
    }
}

PlayQueue API

Provides access to the play queue ("Winamp Playlist"). If you need access to the currently playing song, use the Transport API instead.

Note that the Play Queue is the list of assets that are scheduled to be played by the Winamp client. This is not necessarily the same as a user playlist. Once placed in the play queue, assets can be rearrainged or deleted from the play queue without affecting a user playlist. Individual assets can be placed in the play queue without being contained within a user playlist. Additionally, after adding a playlist to the play queue, changes to the playlist will not affect the assets in the play queue.

Methods

Play()

The PlayQueue.Play() method stops playback, clears the play queue, enqueues the asset specified by the URL and starts playback. If the URL cannot be found, playback will stop, the play queue will be cleared, the URL (or title and length) will appear in the queue but playback will not be started.

Prototype:

bool Play(URL);
bool Play(URL, title);
bool Play(URL, title, length);
where:
    URL = (string) identifies the location of the asset, for a file that is
      local or on an attached network drive this would be the fully
      qualified path and filename.  For files served from a web server,
      it would be the http URL.
    title = (string) used as the title when initially placed in
      the play queue.  
    length = (integer) used as the length when initially place
      in the play queue

Note, title and length are displayed in the play queue to identify what is to be played. In order to reduce network activity, the real title and length are only accessed (using the URL) when the asset is about to commence playback. At this point the title and length are updated to their real values.

Example:

var rc = window.external.PlayQueue.Play("c:\\Winamp\\01 - Hello.mp3",
   "My Cool Title",1024);

Return Value: A boolean value indicating whether the request was successful.

Enqueue()

PlayQueue.Enqueue() is used to add an asset to the play queue. The selected asset is added to the bottom of the queue and current playback is not interrupted.

Prototype:

bool Enqueue(URL);
bool Enqueue(URL, title);
bool Enqueue(URL, title, length);
    URL = (string) identifies the location of the asset, for a file that is
      local or on an attached network drive this would be the fully
      qualified path and filename.  For files served from a web server,
      it would be the http URL.
    title = (string) used as the title when initially placed in
      the play queue.  
    length = (integer) used as the length when initially place
      in the play queue

Note, title and length are displayed in the play queue to identify what is to be played. In order to reduce network activity, the real title and length are only accessed (using the URL) when the asset is about to commence playback. At this point the title and length are updated to their real values.

Example:

var rc = window.external.PlayQueue.Enqueue("c:\\Winamp\\01 - Hello.mp3",
   "My Cool Title",1024);

Return Value: A boolean value indicating whether the request was successful.

Insert()

The PlayQueue.Insert() method can add an asset to the play queue at a specific index.

Prototype:

bool Insert(position, URL);
bool Insert(position, URL, title);
bool Insert(position, URL, title, length);
where:
     position = (integer) a zero based number indicating the location within
          the play queue to insert the new asset.
          Note: Position is "zero based" so the first entry in the 
                queue is at position 0.
     url = (string) the URL of the asset to be added
     title = (string) the title to be displayed in the Play Queue.
     length = (integer) the length of the asset to be displayed in 
          the play queue.

Note, title and length are displayed in the play queue to identify what is to be played. In order to reduce network activity, the real title and length are only accessed (using the URL) when the asset is about to commence playback. At this point the title and length are updated to their real values.

Example:

var rc = window.external.PlayQueue.Insert(1, "c:\\mySongs\\mySong.mp3",300);

Return Value: A boolean value indicating whether the request was successful.

ClearQueue()

The PlayQueue.ClearQueue() method removes all assets from the play queue. This does not stop the current playback. ClearQueue is commonly used to prepare the Play Queue for the addition of new assets.

Prototype:

bool ClearQueue()

Example:

var rc = window.external.PlayQueue.ClearQueue();

Return Value: A boolean value indicating whether the request was successful.

GetMetadata()

PlayQueue.GetMetadata() can be used to obtain asset metadata about an asset in the play queue.

Prototype:

String GetMetadata(position, metadatatag);
where:
  position - (integer) is the position of the asset within the playlist.
  Note: Position is "zero based" so the first entry in the 
    queue is at position 0.
  metadatatag - (string) is a tag describing which metadata is requested.

Example:

var mdata = window.external.PlayQueue.GetMetadata(2,"artist");

Return Value: A String that contains the metadata requested for the asset located at the specified position in the play queue

GetTitle()

PlayQueue.GetTitle() retrieves the title of the asset at the specified position within the play queue.

Prototype:

String GetTitle(position);
where:
  position - (integer) is the position of the asset within the playlist.
  Note: Position is "zero based" so the first entry in the 
    queue is at position "0".

Example:

var title = window.external.PlayQueue.GetTitle(1);

Return value: A String containing the Title of the asset at the requested position in the play queue

GetURL()

PlayQueue.GetURL() is used to obtain the URL from the asset at the specified position in the play queue

Prototype:

String GetURL(position);
where:
  position - (integer) is the position of the asset within the playlist.
  Note: Position is "zero based" so the first entry in the 
    queue is at position "0".

Example:

var url = window.external.PlayQueue.GetURL(1);

Return value: A String containing the URL of the asset at the rquested position in the play queue.

Properties

int length (read only)

PlayQueue.length contains the length of the current play queue

int cursor

PlayQueue.cursor provides access to the position of the currently playing asset within the play queue. This cursor is 0 based, meaning that the first asset in the Play Queue has a cursor value of 0. Valid values range from 0 to the length of the play queue minus one.

If this value is changed before playback is started, the next asset to play will be the one assigned to this property. However, if a song is already playing and this property is changed, the current asset will continue to play even though this property has been updated. At the point that the current asset playback completes, the player will increment the cursor position and play the next asset in the queue rather than the one to which cursor was set. So, for example, to specify the next asset to play while an asset is currently playing, set the cursor property to the position of the asset to play minus one.

Playlists API

The Playlists API is used to process user playlists.

Methods

GetPlaylists()

Prototype:

Array GetPlaylists();

Example:

var playlists = window.external.Playlists.GetPlaylists();

Return Value: A array-like object that can be used to examine all user playlists.

Each element of the array represents a user playlist and contains the following properties

  • filename - filename of the playlist
  • title - name of the playlist
  • playlistId - a unique identifier for the playlist, so you can retrieve it later. Also used with OpenPlaylist/SavePlaylist
  • length - total length (time) in seconds. Cached data - not guaranteed to be accurate
  • numitems - number of items in the playlist. Cached data - not guaranteed to be accurate

OpenPlaylist()

Playlists.OpenPlaylist() returns a Playlist object for the specified playlist ID. You must use Playlists.GetPlaylists() before issuing this request.

Prototype:

Playlist OpenPlaylist(playlistId);
where:
  playlistId - (string) the Id of the playlist to be opened.

Example:

var playlist1 = window.external.Playlists.OpenPlaylist(playlistId);

Return Value: The Playlist object with the specified playistId.

SavePlaylist()

Playlists.SavePlaylist() saves the specified playlist object with the specified ID.

Prototype:

bool SavePlaylist(playlistId, playlist_to_save);
where:
   playlistId (string) is the id of the playlist to be saved.
   playlist_to_save (Playlist) is the Playlist object to be saved.

Example:

var rc = window.external.Playlists.SavePlaylist(playlistId, pl);

Return Value: A boolean value indicating whether the request was successful.


Playlist Object

Playlist objects can be created/returned by the OpenPlaylist() method as well as various other APIs.

Methods

GetItemFilename()

The GetItemFilename() method retrieves the filename/URL of the item at the specified index into the playlist.

Prototype:

String GetItemFilename(position);
where:
  position = (number) position of the item in the playlist for which the filename
                  should be returned.  
  Note: Position is "zero based" so the first entry in the 
    playlist is at position 0.

Example:

var filename = playlst.GetItemFilename(0);

Return value: A string containing the filename/URL of a particular item in the playlist

GetItemTitle()

The GetItemTitle() method returns the title of the asset at the requested index.

Prototype:

String GetItemTitle(position);
where:
  position = (number) position of the item in the playlist for which the title
                  should be returned.
  Note: Position is "zero based" so the first entry in the 
    playlist is at position 0.

Example:

var title = playlst.GetItemTitle(0);

Return value: The song title of the given item in the playlist

GetItemLength()

The GetItemLength() method retrieves the play length of the asset at the requested index.

Number GetItemLength(position);
where:
  position = (number) position of the item in the playlist for which the length
                  should be returned.
  Note: Position is "zero based" so the first entry in the 
    playlist is at position 0.

Example:

var itemLength = playlst.GetItemLength(0);

Return value: A number specifying the play length of the asset, in milliseconds.

Reverse()

The Reverse() method reverses the order of the assets within a playlist, i.e., the first becomes last and the second becomes second to last, etc.

Prototype:

Reverse();

Example:

var rc = playlst.Reverse();

Swap()

The Swap() method exchanges the assets at the two specified positions.

Prototype:

Swap(Number position1, Number position2)
where: 
  position1 = (number) the index of the first item to be swapped.
  position2 = (number) the index of the second item to be swapped.
  Note: position1 and position2 are "zero based" so the first entry in the 
    playlist is at position 0.

Example:

var rc = playlst.Swap(0,1);
Randomize()

The Randomize() method re-arranges the order of the playlist, placing the assets in random positions.

Prototype:

Randomize();

Example:

var rc = playlst.Randomize();
Remove()

The Remove() method removes an asset from the playlist. Subsequent assets are moved to lower number positions in the array.

Prototype:

Remove(position);
where:
  position = (number) the position of the asset to be removed.
  Note: Position is "zero based" so the first entry in the 
    playlist is at position 0.

Example:

var rc = playlst.Remove(0);
SortByTitle()

The SortByTitle() method re-arrainges the order of the playlist so that it is alphabetical order by title.

Prototype:

SortByTitle();

Example:

var rc = playlst.SortByTitle();
SortByFilename()

The SortByFilename() method re-arrainges the order of the playlist so that it is alphabetical order by filename.

Prototype:

SortByFilename();

Example:

var rc = playlst.SortByFilename();
SetItemFilename()

Sets the filename of the asset at the specified location in the playlist.

playlistObj.SetItemFilename(position, filename);
where:
  position = (number) position of the entry in the playlist to alter the filename
  filename = (string) the new filename 
  Note: Position is "zero based" so the first entry in the 
    playlist is at position 0.

Example:

var rc = playlst.SetFilename(0, "c:\\\\myfavorites\\myfavsong.mp3");
SetItemTitle()

Sets the title of the asset at the specified location in the playlist.

Prototype:

SetItemTitle(position, title);
where:
  position = (number) position of the entry in the playlist to alter the filename
  title = (string) the new title 
  Note: Position is "zero based" so the first entry in the 
    playlist is at position 0.

Example:

var rc = playlst.SetItemTitle(0, "My Favorite Title");
SetItemLength()

Sets the length of the asset at the specified location in the playlist.

SetItemLength(position, length);
where:
  position = (number) position of the entry in the playlist to alter the filename
  length = (number) the new length 
  Note: Position is "zero based" so the first entry in the 
    playlist is at position 0.

Example:

var rc = playlst.SetItemLength(0, 1000);
InsertURL()

Inserts the specified asset in front of the asset at the specified position. That and subsequent items are "pushed" to a higher position in the array.

InsertURL(position, url);
InsertURL(position, url, title);
InsertURL(position, url, title, length);
where:
  position = (number) position within the playlist before which to insert the asset
  url = (string) the URL of the asset to be inserted
  title = (string) title of the asset to be inserted
  length = (number) length (milliseconds) of the asset to be inserted
  Note: Position is "zero based" so the first entry in the 
    playlist is at position 0.
  Note: title and length are user specified and do not have to match
  the actual values of the asset.  When the asset is played, the 
  values will be replaced in the Play Queue when the URL is opened 
  for playback but will othewise retain the above values in the 
  playlist.

Return value: A boolean value indicating whether the request was successful.

AppendURL()

The Playlist.AppendURL() method appends an asset URL to the playlist.

Playlist.AppendURL(url);
Playlist.AppendURL(url, title);
Playlist.AppendURL(url, title, length);
where:
  url = (string) the URL to the asset to be appended
  title = (string) title of the asset to be appended
  length = (number) length (milliseconds) of the asset to be appended
  Note: title and length are user specified and do not have to match
  the actual values of the asset.  When the asset is played, the 
  values will be replaced in the Play Queue when the URL is opened 
  for playback but will othewise retain the above values in the 
  playlist.

Return value: A boolean value indicating whether the request was successful.

Clear()

The Playlist.Clear() method will remove all assets from the playlist.

Playlist.Clear();

Return value: A boolean value indicating whether the request was successful

Properties

int numitems (read only)

The Playlist.numitems property contains the number of assets within the playlist.

Bookmarks API

The Bookmarks API provides methods to manage bookmarks.

Methods

Add()

Prototype:

boolean Add(url, title);
where:
  url = (string) The url of the asset to be bookmarked.
  title = (string) A suitable title to be used within the bookmark.

Example:

var rc = window.external.Bookmarks.Add("c:\myfavs\songstocodeby.mp3", 
    "Songs To Code By");

Return value: A boolean value indicating whether the request was successful.

Podcasts API

The Podcasts API provides methods to manage Podcasts.

Methods

Subscribe()

The Podcasts.Subscribe() method is used to add a channel to the list of podcast subscriptions, automatically subscribe to the podcast and begin downloading of the available episodes. Once downloaded the episodes can be selected for playback.

Prototype:

bool Subscribe(url);
where:
    url = (string) the Podcast URL to subscribe to.

Example:

var rc = window.external.PodCasts.Subscribe("http://services.winamp.com/rss/news");

Return value: boolean value that indicates whether the request was successful.

Config API

The Config API provides a means by which properties can be saved. Properties added using the Config API are persistent across Winamp launches.

Adding and Retrieving Properties

Adding a property is accomplished by identifying a property and assigning it a value. Once assigned, the value can be retrieved like any other objects properties.

Example:

window.external.Config.myProperty = "Test";
var myProp = window.external.Config.myProperty;  // myProp is set to "Test"

Storing and Retrieving advanced data types

Internally, all properties are stored as strings. If you need to store datatypes more advanced than String, Number, or Boolean, it is recommended that you create a JSON string out of your data type.

Security API

Methods

GetActionAuthorization()

The Security.GetActionAuthorization() method can be used to determine whether a user has previously allowed or denied the functioning of a particular API's methods. Group strings match API names.

Prototype:

number Security.GetActionAuthorization(group);
where:
   group = (string) Name of API to check for permission.

Example:

var rc = window.external.Security.GetActionAuthorization("Transport");

Return Data:

  • -1 = Either the user has not specified whether to allow/deny use of this API or the action usage is unrestricted.
  • 0 = The user has previously specified to deny use of this API/method.
  • 1 = The user has previously specified to allow use of this API/method.

MediaCore API

Methods

IsRegisteredExtension()

MediaCore.IsRegisteredExtension() method can be used to determine if the Winamp client is able to playback a specific format. The file extension of the asset usually indicates the format. This method is important since Winamp support for different formats is contained within plugins which may or may not exist for use.

Prototype:

boolean IsRegisteredExtension(ext);
where:
  ext = (string) identifies the format to be queried for support in the form of a 
      character string of the extension (a starting period is optional).

Example:

var canPlay = window.external.MediaCore.IsRegisteredExtension("mp3"); 

Return value: Boolean value indicating whether the format is supported.

GetMetadata()

MediaCore.GetMetadata() method can be used to obtain metadata about an asset. This method differs from Transport.GetMetadata() in that the asset does not have to be currently playing. It differs from PlayQueue.GetMetadata() in that it doesn't have to be present in the play queue.

Prototype:

string GetMetadata(url, tag);
where:
   url = (string) containing the URL for which metadata is to be retrieved.
   tag = (string) the specific piece of metadata to be returned.

Example:

var art = window.external.MediaCore.GetMetadata(
        "c:\\my favs\\myfavorite.mp3","artist");

Return value: A string containing the metadata requested.

AddMetadataHook()

MediaCore.AddMetadataHook() method can be used to add or override metadata for an asset. For example, some assets such as those that are streamed may not contain metadata. This method allows the online service to add metadata for the specified asset. Subsequent GetMetadata() methods will return this information. Online services can override the metadata present within an asset using this method. This method can be used by services that define or can obtain their own metadata for the assets they provide rather than rely on what might or might not be present in the asset itself.

Prototype:

string AddMetadataHook(url, tag, value);
where:
   url = (string) containing the URL for which metadata is to be added.
   tag = (string) the specific metadata key for which a value will be added.
   value - (string) the value of the metadata key being added.

Example:

var rc = window.external.MediaCore.AddMetadataHook(
        "c:\\my favs\\myfavorite.mp3","artist","myself");

Return value: A boolean value that indicates whether the request was successful.

RemoveMetadataHook()

MediaCore.RemoveMetadataHook() method can be used to remove metadata added through the AddMetadataHook() method. Subsequent GetMetadata() requests will return whatever metadata was available previously, if any.

Prototype:

string RemoveMetadataHook(url, tag);
string RemoveMetadataHook(url);
where:
   url = (string) containing the URL for which metadata is to be removed.
   tag = (string) the specific metadata key for which a value will be removed.

If only the url parameter is provided, all metadata added with AddMetadataHook() for the specified url will be removed.

Example:

var rc = window.external.MediaCore.RemoveMetadataHook(
        "c:\\my favs\\myfavorite.mp3","artist");

Return value: A boolean value that indicates whether the request was successful.

History API

The History branch of the Media Library pane is actually a database containing information about previously played assets. The History API allows a service to search and retrieve information from this database. By specifying a query string, Winamp will return an array of objects that match the values specified in the query.

Methods

Query()

Prototype:

results = History.Query(queryString);
where:
  queryString = a properly formed string to match data to be returned.

Example:

var results = window.external.History.Query("LASTPLAYED<[now]");

Return value: An "array-like" object that contains the results of the query.

Each entry of the array contains the following properties:

  • String filename
  • String title
  • Number length
  • Number playcount
  • Date lastplay


Query String format: <field> <comparison> [value] [<logic operator> <field> <comparison> [value] [...]]


Fields:

Keyword Description
LASTPLAY Date and time when this asset was last played.
FILENAME Full filename (including path)
LENGTH Length, in seconds (or hh:mm:ss)
TITLE Title
PLAYCOUNT Number of times the asset has been played.


Comparison Operators:

Operator Description
'=' String or integer equals value
'!=' String or integer does not equal value
'<' String or integer is less than value
'>' String or integer is greater than value
'<=' String or integer is less than or equal to value
'>=' String or integer is greater than or equal to value
HAS String contains value
NOTHAS String does not contain value
LIKE String is similar to value ("the" and whitespace are ignored)
BEGINS String begins with value
BEGINSLIKE String begins like value
ENDS String ends with value
ISEMPTY (no comparison value required) TRUE if <field> is empty
ISNOTEMPTY (no comparison value required) TRUE if <field> is not empty


Values can be:

  • "strings with spaces" or strings_without_spaces
  • integers can be "32" or just 32
  • integers for LENGTH can be a plain integer (seconds), or mm:ss or hh:mm:ss
  • date/timestamps should be [datetime data], which can be either an absolute or relative time. i.e.: [3 weeks ago], [18:15], [05/30/2003], [yesterday noon], [3 days ago 5 pm], [now], [5 mn before may 30th], etc.


Application API

Methods

LaunchURL()

The Application.LaunchURL() method launches a URL in the bento browser or default browser. The default browser is launched if force_external = true or in skins that don't define a browser.

Prototype:

boolean LaunchURL(url, force_external);
where:
     url = (string) The url to open in the browser
     force_external = (boolean) will force the url to be displayed in a browser
          outside of the Winamp client.

Example:

var rc = LaunchURL("http://www.winamp.com", true); 

Return value: A boolean value indicating whether the request was successful.

Properties

int version (read only)

The version property returns the version number of the browser control within the Winamp client as an integer, e.g. 555 for 5.55, 560 for 5.6

string versionstring (read only)

The versionstring property returns the version number of the browser control within the Winamp client as a string, e.g. "5.55" for 5.55

string language (read only)

Language identifier from the currently installed language pack. Follows ISO 639-1 two letter language codes

string languagepack (read only)

Language pack identifier from the currently installed language pack. follows the form lc-CC where lc is the two letter ISO 639-1 language code and CC is the two letter ISO 3166 country code.

Note: do not count on the country code being the same as the user's current location.

Skin API

The skin color API is a bit of a challenge. This API reflects some the idiosyncrasies of the underlying skinning system. "Classic" skins define a palette of 24 colors for the skin and an additional 6 colors for the playlist editor. "Modern" skins define these as well as any number of other colors retrievable by name (e.g. wasabi.tree.text for the text color on tree views). A website relying on any of these extra "named" colors should be careful to implement a fallback color based on the classic palette, as no named colors exist in classic skins!

Methods

GetClassicColor()

The Skin.GetClassicColor() method is used to retrieve color information regarding different Skin UI elements.

Prototype:

GetClassicColor(classiccolornumber);
 where:
   classiccolornumber = (integer) A number in the range 0-23 identifying the Skin's UI element 
        for which the color should be returned.

Example:

 var wndBgColor = window.external.Skin.GetClassicColor(2);

Return value: The HTML color constant used for the specified Skin UI element.

Classic Color Numbers

Number Description
0 Item Background
1 Item Foreground
2 Window Background
3 Button Foreground
4 Window Foreground
5 Hilite
6 Selection
7 List Header Background
8 List Header Text
9 List Header Frame Top
10 List Header Frame Middle
11 List Header Frame Bottom
12 List Header Empty Background
13 Scrollbar Foreground
14 Scrollbar Background
15 Scrollbar Inverse Foreground
16 Scrollbar Inverse Background
17 Scrollbar Dead Area
18 Selection Bar Foreground
19 Selection Bar Background
20 Inactive Selection Bar Foreground
21 Inactive Selection Bar Background
22 Alternating Item Background
23 Alternating Item Foreground

GetPlaylistColor()

The Skin.GetPlaylistColor() method is used to retrieve color information regarding different Playlist UI elements.

Prototype:

GetPlaylistColor(playlistcolornumber);
 where:
   playlistcolornumber = (integer) a number in the range 0-5 identifying the Playlist's UI 
        element for which the color should be returned.

Example:

 var normalBgColor = window.external.Skin.GetPlaylistColor(2);

Return value: The HTML color constant used for the specified Playlist UI element.

Playlist Color Numbers

Number Description
0 Normal
1 Current
2 Normal Background
3 Selected Background
4 Video Window Status Bar Foreground
5 Video Window Status Bar Background

GetSkinColor()

The Skin.GetSkinColor() method is used to retrieve color information regarding different Playlist UI elements.

Prototype:

GetSkinColor(skincolorname);
 where:
   skincolorname = (string) identifying the Skin's UI 
        element for which the color should be returned.

Example:

 var buttonTextColor = window.external.Skin.GetSkinColor("wasabi.button.text");

Return value: The HTML color constant used for the specified Playlist UI element.

Skin Color Names

Name Description
"wasabi.list.item.selected.fg" Selected item text foreground color
"wasabi.list.column.separator" Color of line between columns
Item Lists, Lists with playable items
"wasabi.itemlist.outline.current" Currently playing outline color
"wasabi.itemlist.outline.focus" Focused item dashed outline color
"wasabi.itemlist.selborder"
Message box
"wasabi.msgBox.background" Messagebox background color
"wasabi.textBar.text" Text object & message box text color
"wasabi.textBar.background" Text object & message box text background color
Buttons
"wasabi.button.text" Buttons text color
"wasabi.button.hiliteText" Buttons hilite text color, used by tab windows
"wasabi.button.dimmedText" Buttons dimmed text color, when disabled
Popup menus
"wasabi.popup.text" Menu items text color
"wasabi.popup.hiliteText" Hilited item text color
"wasabi.popup.dimmedText" Disabled item text color
Components
"wasabi.component.title.foreground" Old title bar text color when using TTF
"wasabi.component.title.border" Old title bar text outline when using TTF
Labeled Windows
"wasabi.labelwnd.foreground" Text foreground color
"wasabi.labelwnd.background" Text drop shadow color
Edit Windows
"wasabi.edit.selection" Selected text
"wasabi.edit.text" Text
"wasabi.edit.background" Text background
"wasabi.text.color"
"wasabi.text.color.inverse"

Properties

string name (test)

The Skin.name property gives access to the name of skin currently in use. Changing this value will change the skin displayed for the player.

string font (read only)

The Skin.font property provides the font name currently used in the player.

string fontsize (read only)

The Skin.fontsize property provides the size of the font currently used in the player.

Metadata tag names

When retrieving metadata through Winamp, a freeform string is passed. The popular file formats (MP3, WMA, FLAC, M4A) will respond uniformly to a common base of strings. However, each file format is idiosyncratic in how metadata is stored. Some file types will respond to additional strings which are not documented here.

Remember that the metadata is only as good as the tagging in the file itself. A poorly tagged track will return poor metadata.

Common metadata tags

bitrate
length
type
title
artist
albumartist
album
genre
year
disc
publisher
comment
track
composer
conductor