Wimpy JavaScript Controls - Function Reference

By Mike Gieson
Available at www.wimpyplayer.com
©2002-2007 plaino

This page contains a description of available JavaScript controls fundtions for Wimpy Rave.
For more information about how to set up Wimpy Rave, see the "Overview" page.

Contents:

- List of available Javascript control funcitons
- Explainations and example code

List of available Javascript control funcitons:

Initialization

makeWimpyPlayer
handleWimpyInit
wimpy_amReady_ask
wimpy_callPlugin
handlTrackStarted
handleTrackDone
wimpy_updateInfoDisplay
wimpy_setVolume
wimpy_setMuteState
wimpy_setLoopTrackState
wimpy_setRandomState
wimpy_setRepeatState

Playback Control

wimpy_play
wimpy_stop
wimpy_pause
wimpy_gotoTrack
wimpy_next
wimpy_prev
wimpy_getPlayheadPercent
wimpy_setPlayheadPercent
wimpy_getPlayheadSeconds
wimpy_setPlayheadSeconds
wimpy_getLoadPercent
wimpy_getLoadState
wimpy_getPlayerState

Playlist

wimpy_clearPlaylist
wimpy_appendPlaylist
wimpy_loadExternalPlaylist
wimpy_getTotalPlaylistItems
wimpy_returnPlaylistItem
wimpy_getPlaylistXML
wimpy_getPlaylist
wimpy_getTrackInfo




Explainations and example code:

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.

<a href="javascript:;"
onClick="wimpy_play();">
Play
</a>

 

 

 

wimpy_stop()

Stops the currently loaded track

<a href="javascript:;"
onClick="wimpy_stop();">
Stop
</a>

 

 

 

wimpy_pause()

Pauses the currently loaded

<a href="javascript:;"
onClick="wimpy_pause();">
Pause
</a>

 

 

 

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.

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

 

 

 

wimpy_next()

Plays the next track in the playlist

<a href="javascript:;"
onClick="wimpy_next();">
Next
</a>

 

 

 

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.

<a href="javascript:;"
onClick="wimpy_prev();">
Previous
</a>

 

 

 

wimpy_clearPlaylist()

Clears the playlist

<a href="javascript:;"
onClick="wimpy_clearPlaylist();">
Clear Playlist
</a>

 

 

 

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:

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

 

 

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:

<a href="javascript:;"
onClick="wimpy_setLoopTrackState('on')">
on
</a>

 

 

wimpy_setRandomState()

Returns: nothing

See Example 6

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

State options are:
on
off

Example:

<a href="javascript:;"
onClick="wimpy_setRandomState('on')">
on
</a>

 

 

wimpy_setRepeatState()

Returns: nothing

See Example 6

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

State options are:
on
off

Example:

<a href="javascript:;"
onClick="wimpy_setRepeatState('on')">
on
</a>

 

 

wimpy_setMuteState()

Returns: nothing

See Example 6

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

State options are:
on
off

Example:

<a href="javascript:;"
onClick="wimpy_setLoopTrackState('on')">
on
</a>

 

 

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:

<a href="javascript:;"
onClick='wimpy_updateInfoDisplay("My New Artist", "My New Title")'>
Update Artist and Title
</a>

 

 

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:

percent

A "float" number from 0.0 to 1.0.

Example:
0.34
(the file is 34% loaded)

 

loaded

Number of bytes loaded

Example:
5035075 (bytes)

 

total

Total file size in bytes

Example:
7481037 (bytes)

 

status

The state identified by a number: -1, 0, 1

Example
-1 = loading is complete / no more loading is needed.
0 = an error occurred while attempting to load
1 = loading is in progress \

 

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:

buffering

Boolean value indicating whether or not the track is buffering

The spinning "wait" icon is a graphic representation of this value.

 

 

bufferState

A numerical representation of the buffer status:

1 = Buffer is full
0 = Buffer is empty
-1 = Buffer is flushing

 

buffer

Number of seconds worth of media in the buffer. See also "bufferSeconds."

printTime

A nicely formatted time signature. representing the current time.

remaining_nice

A nicely formatted time signature. representing the remaining time.

remaining

Number of seconds remaining

current_nice

A nicely formatted time signature. representing the current time.

current

Number of seconds that have been played. (e.g. The position of the playhead in seconds)

duration_nice

A nicely formatted time signature. representing the total time.

duration

The total time of the track in seconds.

percent

The current percentage of playback. This is graphically represented by the scrubber handle.

status

A numerical representation of the players overall status:

1 = playing
0 = paused or stopped

 

init

A numerical representation of the tracks initialization status:

1 = track is queued and ready to play or playing.
0 = no track is queued nothing can play.

 

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