Categories
javascript

Wimpy Player Javascript Control Functions

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

List of available Javascript control functions:

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

Explanations 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:

– Retrieving Information

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:

– Retrieving Information

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:

– Retrieving Information

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 variables in the global scope:

var ourInterval;

var gotoPercent = 30;

// Create function to intermittently 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:

– Retrieving Information

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:

– Retrieving Information

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:

– Retrieving Information

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 “Retrieving Information.”

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:

– Retrieving Information

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