Wimpy JavaScript Controls - Function Reference

makeWimpyPlayer()

See Example 1

See Example 2

See Example 3

Renders a player on your page based on the options established within the rave.js file. The rave.js file contains more information about the available options in the javaScript comments.

To render a player:

<script language="JavaScript" >
  makeWimpyPlayer();
</script>

To render a player with one file:

<script language="JavaScript" >
  makeWimpyPlayer("file1.mp3");
</script>

To render a player with a few files, separate each file with a "pipe" character, see Example 2.

To render a player with a few files, with each file having additional information:, see Example 3.

wimpy_play()

Starts the player or plays the track that is currently selected in the playlist.

wimpy_stop()

Stops the currently loaded track

wimpy_pause()

Pauses the currently loaded

wimpy_gotoTrack()

Goes to a specific track listed in the playlist. The only way to determine which track to "go to" is by referencing a number. Example wimpy_gotoTrack(3) would play the third item in the current playlist.

wimpy_next()

Plays the next track in the playlist

wimpy_prev()

Rewinds the play head to the beginning of the track, or goes to the previous item in the playlist depending on the current status of the player's play head.

wimpy_clearPlaylist()

Clears the playlist

wimpy_appendPlaylist()

Returns: nothing

See Example 5

Adds tracks to the player's playlist. Loads XML data into the player.

To add an MP3 file to the playlist

<script language='javascript'>
var addFiles = "";
addFiles += "<playlist>";
addFiles += "  <item>";
addFiles += "    <filename>example1.flv</filename>";
addFiles += "    <artist>killeen and gieson</artist>";
addFiles += "    <title>Example 1</title>";
addFiles += "    <link>http://www.gieson.com</link>";
addFiles += "    <image>example1.jpg</image>";
addFiles += "  </item>";
addFiles += "  <item>";
addFiles += "    <filename>example2.flv</filename>";
addFiles += "    <artist>Killeen and Gieson</artist>";
addFiles += "    <title>Example 2</title>";
addFiles += "    <link>http://www.plaino.com</link>";
addFiles += "    <image>example2.jpg</image>";
addFiles += "  </item>";
addFiles += "</playlist>";
</script>

<a href="javascript:;"
onClick="wimpy_appendPlaylist(addFiles)">
Add Multiple Tracks
</a>

wimpy_getTrackInfo()

Returns: Object

See Example 6

Returns all the information for a track as an Object. If no argument is passed in, the info for the track that is currently playing will be returned.

In your HTML:

<a href="javascript:;"
onClick="wimpy_getTrackInfo();">
Get info about current track.
</a>

Wimpy returns:

anObject.artist = "The tracks artist";
anObject.title = "The track's title";
anObject.whatever = "Whatever else is available"

To retrieve information on a specific item in the playlist , enter the a number as an argument. The number that you enter should correspond to the playlist item. For example, entering "3" as the argument will get the info for the third item in the playlist.

wimpy_getTrackInfo(3)

In the example above, all the information for the third item in the playlist will be returned. NOTE: If the playlist is being sorted, the item may be different than the order in which the source XML playlist.

If the player has not yet started to play a track, the info for the first item in the playlist is returned.

If the player does not have anything in the playlist Wimpy will return false (boolean).

See also:

- Reading a Returned Object

wimpy_loadExternalPlaylist()

Returns: nothing

Loads a playlist file into the player.

Example:

handleWimpyInit()

Returns: Boolean

See Example 6

This function will get pinged when Wimpy is ready and able to accept JavaScript calls / interaction. Wimpy will call this function as needed to inform you of the event.

In order for this function to be enabled, the variable "enableWimpyEvents" to be set to true. Open rave.js in a text editor and scroll down to the "Advanced Usage" area.

Example:

var enableWimpyEvents = true;

See also wimpy_amReady_ask()

handlTrackStarted()

Returns: Object

See Example 6

This function gets pinged every time a track starts to play. Wimpy will call this function as needed to inform you of the event.

In order for this function to be enabled, the variable "enableWimpyEvents" to be set to true. Open rave.js in a text editor and scroll down to the "Advanced Usage" area.

Example:

var enableWimpyEvents = true;

Wimpy will return an Object that contains all of the track information.

See also:

- Reading a Returned Object

handleTrackDone()

Returns: Object

See Example 6

// This function gets pinged each time a track finishes playing. Wimpy will call this function as needed to inform you of the event.

In order for this function to be enabled, the variable "enableWimpyEvents" to be set to true. Open rave.js in a text editor and scroll down to the "Advanced Usage" area.

Example:

var enableWimpyEvents = true;

Wimpy will return an Object that contains all of the track information.

See also:

- Reading a Returned Object

wimpy_amReady_ask()

Returns: Boolean

See Example 6

Checks to see if Wimpy has been initialized and is ready to accept JavaScript calls / interaction.

Example:

<a href="javascript:;"
onClick="wimpy_loadExternalPlaylist("http://path/to/playlist.xml");">
Load a playlist.
</a>

wimpy_setVolume()

Returns: nothing

See Example 6

Set the player's volume

Example:

<a href="javascript:;"
onClick="wimpy_setVolume(50);">
Set Volume to 50 percent.
</a>

wimpy_setLoopTrackState()

Returns: nothing

See Example 6

Sets the "loop track" button to the specified state.

State options are:
on
off

Example:

wimpy_setRandomState()

Returns: nothing

See Example 6

Sets the "random playback " button to the specified state.

State options are:
on
off

Example:

wimpy_setRepeatState()

Returns: nothing

See Example 6

Sets the "repeat track " button to the specified state.

State options are:
on
off

Example:

wimpy_setMuteState()

Returns: nothing

See Example 6

Sets the "loop track" button to the specified state.

State options are:
on
off

Example:

wimpy_updateInfoDisplay()

Returns: nothing

See Example 6

Puts new information into the scroll info display area.

Accepts two arguments, the first refers to the Artist, the second the Title of the track.

This option is useful when running Icecast streams and allows you update the scrolling display dynamically.

Example:

wimpy_getPlayheadPercent()

Returns: Number

Gets the current playhead percentage.

wimpy_setPlayheadPercent()

Returns: nothing

Sets the playhead to the specified percentage.

NOTE: This option was not designed to for use milliseconds after launching a file. In other words, some folks might be trying to use this function to "pick up" playing where a user left off last time they visited a page.

Although this kind of functionality can be achieved, it will require additional scripting to accomplish because the file must have enough data loaded before Wimpy can advance the playhead.

For example, lets say you launch a track, then immediately call this function and set the argument to 95 (meaning "set the playhead so that the track starts playing at 95%"... Since it is highly likely that the file has not been fully loaded milliseconds after launching it, Wimpy will not advance the playhead to 95%. Wimpy can only advance the playhead to a percentage that has been loaded.

This means that you will probably need to use the wimpy_getLoadPercent function before calling this "set" function in order to determine how much of the file has been loaded, and / or if it is safe to advance the playhead.

Here's a potential method for achieving this kind of functionality:

// Create a player:
makeWimpyPlayer();

// In the rave.js, add a function call inside wimpy_amReady() as:
function wimpy_amReady(retval){
    loadAndListen( "myFile.flv");
}

// Create a new function in rave.js as:
function loadAndListen(myFile){
   // Add a track to the player and launch it (so it starts to load)
   wimpy_appendPlaylist(myFile, true);
   // Pause the player immediately
   wimpy_pause();
   // Set an interval call to wait until enough data has been
   // loaded before setting the playhead position:
   ourInterval = setInterval('checkLoadStatus()', 1000);
}

// Establish varibles in the global scope:
var ourInterval;
var gotoPercent = 30;

// Create function to intermitenly check the load percent:
function checkLoadStatus(){
   var loaded  = wimpy_getLoadPercent();
   if(loaded > gotoPercent){
      wimpy_setPlayheadPercent(gotoPercent);
      clearInterval(ourInterval);
   }
}

wimpy_getPlayheadSeconds()

Returns: Number

Gets the playhead position in seconds.

wimpy_setPlayheadSeconds()

Returns: nothing

Sets the playhead to the specified second.

See "NOTE" in wimpy_setPlayheadPercent();

.

wimpy_getLoadPercent()

Returns: Number

Retrieves the loading status according to percent loaded (0-100).

wimpy_getLoadState()

Returns: Object

See Example 6

Retrieves all information associated with file loading.

The object will contain the following variables:

See also:

- Reading a Returned Object

wimpy_getPlayerState()

Returns: Object

See Example 6

Retrieves all information associated with clip playback.

The object will contain the following variables:

See also:

- Reading a Returned Object

wimpy_getTotalPlaylistItems()

Returns: Number

See Example 6

Returns the total number of tracks loaded into the playlist.

wimpy_returnPlaylistItem()

Returns all the information for a specific track loaded into the Wimpy playlist.

Wimpy returns the information as an array, where the first index of the array is a string identifying the name of the function (e.g. "wimpy_returnPlaylistItem " which allows you to distinguish between different function calls returned to the function that is defined in js_wimpy_returnOnComplete.

This function requires js_wimpy_returnOnComplete to be established within rave.js. See the comments within rave.js for how to use this feature.

<a href="javascript:;"
onClick="wimpy_returnPlaylistItem(2);"> <-- Specify the track number inside the ().

Get info about a specific track

</a>

See readme_wimpy_mp3_js_example6.html for example of how to use this feature.

See also:

- Reading a Returned Object

wimpy_getPlaylistXML()

Returns: XML

See Example 6

Returns the current playlist as a string in the form of XML data.

wimpy_getPlaylist()

Returns: Array

See Example 6

Returns an array where each item in the array is an object. that refers to a playlist item.

Example:

returned_array[0] = playlist_item_object
returned_array[1] = playlist_item_object
returned_array[2] = playlist_item_object

Each "playlist_item_object" can be interpreted using the method described in "Reading a Returned Object."

This method is provided so that you don't have to convert the XML into a usable array or object. It should be noted that in each playlist_item_object, the <item> XML is also included in the XMLdata  variable.

See also:

- Reading a Returned Object

wimpy_callPlugin()

Allows you to call a custom plugin.

wimpy_callPlugin(pluginID, argument)

Where pluginID refers to the ID name given to the plugin. The ID can be modified using Skin Machine.

Only one argument is allowed to be sent it. If your plugin requires more than one argument to be sent in, the argument must be formatted according to the method described by the plugin author. Usually this means "packaging" the multiple arguments with some kind of delimiter, such as a pip " | " or carat " ^ ".

Example:

var myPluginID = "CoolPlugin";
var arg1 = "http://path/to/something";
var arg2 = "true";
var combinedArgument = arg1 + "|" + arg2;
wimpy_callPlugin(myPluginID, combinedArgument);