jPlayer

jQuery audio player plugin

jPlayer 0.2.4 beta Developer Guide

Contents

jPlayer Fundamentals

Flash Security Rules

JPlayer plugin's SWF file must be on your domain.

You cannot link to the jPlayer's SWF file on happyworm.com as this violates the same domain policy.

You need to upload the files to a directory called "js" on your domain. If required, use the constructor option swfPath to change the path.

Technically, the JS file of the plugin may be linked to remotely at happyworm.com, but you will need to have a local copy of the Jplayer.swf file on your domain.

Attempting to run jPlayer locally on your computer will generate Flash security violations and you would need to enable the local file access using the Flash Settings Manager. See the Flash Player Help for more information.

jPlayer Constructor

$(id).jPlayer( Object: options )

Description
The jPlayer constructor is applied to the given id and uses the options, if provided.
Note that the most important option is the ready element, which is a function defining the actions to perform once jPlayer is ready for use. Attempting to issue commands to jPlayer before the ready() has been called will result in runtime errors.
Parameters
options
Object defining any changes to the default configuration of jPlayer.
ready :
Function : (Default: undefined) : Defines a function to call when the jPlayer plugin is ready for use. Generally, it is recommended to use a function here to at least jPlayer.setFile(f) the jPlayer to a valid mp3 file ready for use.
The ready function is defined at creation to eliminate a race condition between the javascript code and whether the Flash is ready. Thus ensuring the Flash function definitions exist when the javascript code is executed.
cssPrefix
String : (Default: "jqjp") : Defines the prefix for jPlayer's CSS class manipulation.
See jPlayer CSS Classes for more information.
swfPath
String : (Default: "js") : Defines the relative or absolute path of the jPlayer plugin's SWF file.
This allows the developer to place the jPlayer's SWF file in an alternative relative or absolute path.
The URL given must conform to standard URL Encoding Rules.
volume
Number : (Default: 80) : Defines the initial volume as a percentage.
oggSupport
Boolean : (Default: false) : Enables ogg support in HTML5 with OGG format browsers.
This allows the developer specify an alternative OGG file counterpart for each mp3 file.
See jPlayer.setFile(mp3, [ogg]) for more information.
position
String : (Default: "absolute") : Defines the CSS position style of the Flash.
left
Number : (Default: 0) : Defines the CSS left style of the Flash.
top
Number : (Default: 0) : Defines the CSS top style of the Flash.
width
Number : (Default: 0) : Defines the width of the Flash.
height
Number : (Default: 0) : Defines the height of the Flash.
quality
String : (Default: "high") : Defines the quality of the Flash.
bgcolor
String : (Default: "#ffffff") : Defines the background color of the Flash.

HTML entry, with an example id for jPlayer:

<head>
  <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.3/jquery.min.js">
  </script>
  <script type="text/javascript" src="js/jquery.jplayer.js>
  </script>
  <script> $(document).ready(function() { /* Your Code */ });
  </script>
</head>
<body>
  <div id="jpId"></div>
</body>

Code Example #1:

$(document).ready(function() {
  $("#jpId").jPlayer( {
    ready: function () {
      $(this).setFile("../mp3/elvis.mp3"); // Defines the mp3
    }
  });
});

Code Example #2:

$(document).ready(function() {
  $("#jpId").jPlayer( {
    ready: function () {
      $(this).setFile("mp3/elvis.mp3", "ogg/elvis.ogg"); // Defines the counterpart mp3 and ogg files
    },
    oggSupport: true,
    swfPath: "http://www.myDomain.com/jPlayer/js",
    cssPrefix: "my_jp_class"
  });
});

Code Example #3:

$(function() { // executed when $(document).ready()
  $("#jpId").jPlayer( {
    ready: function () {
      $(this).setFile("http://www.myDomain.com/mp3/elvis.mp3").play(); // Auto-Plays the file
    },
    swfPath: "jPlayer/js"
  });
});

Code Example #4: Bad Code!

$(document).ready(function() {
  $("#jpId").jPlayer( {
    ready: function () {
      $(this).setFile("elvis.mp3");
    }
  });
  $("#jpId").play(); // BAD: The plugin is not ready yet
});

jPlayer Methods

jPlayer.jPlayerId( String: methodName, String: methodCssId ) : jPlayer

jPlayer.jPlayerId( String: methodName ) : String

Description
This jPlayerId method is used to create or read associations between jPlayer methods and CSS entities on the webpage.
Creation associates a handler method inside the plugin with a CSS Id on the webpage. This enables an element on the webpage to be associated with the method that, for example, executes the play command.
Reading returns the CSS Id associated with the method.
Parameters
methodName
String containing the name of the method to associate with the methodCssId.
"play"
the method that plays the mp3
"pause"
the method that pauses the mp3
"stop"
the method that stops the mp3
"loadBar"
the method that listens to and manipulates the load bar
"playBar"
the method that manipulates the play bar
"volumeMin"
the method that mutes the volume
"volumeMax"
the method that maximises the volume
"volumeBar"
the method that listens to the volume bar
"volumeBarValue"
the method that manipulates the volume's value
"bufferMsg"
the method that outputs a buffer message
methodCssId
(Optional) String containing the name of the CSS Id to associate with the methodName
This parameter is optional. If ommitted, the CSS Id of the associated method is returned.
Requesting an unknown or unset method CSS Id generates a warning alert popup and returns a false.

Code Examples:

$("#jpId").jPlayerId( "play", "thePlayButton" );
$("#jpId").jPlayerId( "loadBar", "theLoadBar" );
myPauseButtonId = $("#jpId").jPlayerId( "pause" );

jPlayer.setFile( String: mp3, [String: ogg] ) : jPlayer

Description
This method is used to define the file to play. The MP3 file is mandatory, and the OGG file is an optional alternative counterpart specified when {oggSupport: true} is given as a constructor option. When {oggSupport: true} both the mp3 and ogg parameters are mandatory.
The .setFile(mp3, [ogg]) method must be used to define an MP3 [and OGG] file before the jPlayer will be able perform other methods like .play().
The plugin does not begin downloading the new file defined by the .setFile() method.
Any song being played when the command is issued will be stopped and the download canceled.
jPlayer will use the HTML5 solution if available and the Flash solution for other browsers. When {oggSupport: true}, the OGG file will be used on browsers that support HTML5 with OGG format, otherwise the MP3 will be used with either HTML5 or Flash.
Priority favours HTML5 over Flash and OGG over MP3: 1) HTML5 with OGG, 2) HTML5 with MP3, 3) Flash with MP3
Parameters
mp3
String defining the path to the MP3 file
The URL given must conform to standard URL Encoding Rules.
ogg
[Optional] String defining the path to the OGG file. Mandatory when {oggSupport: true}
The URL given must conform to standard URL Encoding Rules.

Code Examples:

$("#jpId").setFile( "mp3/elvis.mp3" ); // for a local file
$("#jpId").setFile( "http://www.domain.com/mp3/elvis.mp3" ); // for a remote file
$("#jpId").setFile( "mp3/elvis.mp3" ).play(); // to define and play the local file
$("#jpId").setFile( "mp3/elvis.mp3", "ogg/elvis.ogg" ); // for {oggSupport: true}

jPlayer.play() : jPlayer

Description
This method is used to play the MP3 file.
If necessary, the file will begin downloading.
Play will either begin from the start of the MP3 or from where the play-head was when previously paused.
Parameters
none
This method has no parameters.

Code Examples:

$("#jpId").play();

jPlayer.pause() : jPlayer

Description
This method is used to pause the MP3 file.
When paused, the play-head time is stored in the plugin.
Parameters
none
This method has no parameters.

Code Examples:

$("#jpId").pause();

jPlayer.stop() : jPlayer

Description
This method is used to stop the MP3 file.
The play-head will be reset to the start of the song.
Parameters
none
This method has no parameters.

Code Examples:

$("#jpId").stop();

jPlayer.playHead( Number: percentOfLoaded ) : jPlayer

Description
This method moves the play head to a new position. The primary use is internal to the plugin to handle clicks on the loadBar and move the play head to the new position.
Parameters
percentOfLoaded
Number (0 to 100) defining the percentage played when compared to the current percentage downloaded.
Only when completely downloaded does the percentage relate to the total length of the mp3 file.
Eg. A 4 minute song, that is 50% downloaded and given the percentOfLoaded of 50% would move to 25% into the total song, which is at 1 minute.
See jPlayer.onProgressChange( Function: handleChanges ) for information on gaining access to loadPercent and playPercentRelative values.

Code Examples:

$("#jpId").playHead(0); // Begins playing at the start.
$("#jpId").playHead(10); // Begins playing at 10% of the downloaded length.
$("#jpId").playHead(100); // Begins playing at the downloaded length.

jPlayer.playHeadTime( Number: playedTime ) : jPlayer

Description
This method moves the play head to a new position defined in milliseconds.
Parameters
playedTime
Number defining the new play head in milliseconds from the start of the song.
If used while downloading, play will begin once the file has downloaded to that point.
See jPlayer.onProgressChange( Function: handleChanges ) for information on gaining access to playedTime and totalTime values.

Code Examples:

$("#jpId").playHeadTime(0); // Begins playing at the start.
$("#jpId").playHeadTime(10000); // Begins playing 10 seconds into the song.

jPlayer.volume( Number: percent ) : jPlayer

Description
This method is used to control the volume of the MP3 file being played.
Parameters
percent
Number defining the percentage of maximum volume.
To mute the volume use: 0
For half volume use: 50
For maximum volume use: 100

Code Examples:

$("#jpId").volume( 25 );
$("#jpId").volume( volumeValue );

jPlayer.volumeMin() : jPlayer

Description
This method is used to mute the the MP3 file being played.
Parameters
none
This method has no parameters.

Code Examples:

$("#jpId").volumeMin();

jPlayer.volumeMax() : jPlayer

Description
This method is used to maximise the volume of the MP3 file being played.
Parameters
none
This method has no parameters.

Code Examples:

$("#jpId").volumeMax();

jPlayer.onSoundComplete( Function: endOfSong ) : jPlayer

Description
This method is used to define a function that is executed when the MP3 file finishes playing.
Parameters
endOfSong
Function that is executed when the MP3 file ends.

Code Examples:

$("#jpId").onSoundComplete( function() {
  $(this).play(); // Auto-Repeat
});

jPlayer.onProgressChange( Function: handleChanges ) : jPlayer

Description
This method is used to define a function that takes 5 parameters and is executed every time the plugin updates the progress of the load bar or play bar.
Parameters
handleChanges( Number: loadPercent, Number: playedPercentRelative,
Number: playedPercentAbsolute, Number: playedTime, Number: totalTime )
Function executed every time the progress changes.
Parameters:
loadPercent
Number (0 to 100) defining the percentage downloaded
playedPercentRelative
Number (0 to 100) defining the percentage played when compared to the percentage downloaded.
playedPercentAbsolute
Number (0 to 100) defining the the current play position in percentage
playedTime
Number defining the current play position in milliseconds
totalTime
Number defining the total play time of the MP3 in milliseconds

Code Examples:

$("#jpId").onProgressChange( function(lp,ppr,ppa,pt,tt) {
  $("#myLoadInfo").text(lp+"%"); // Show the percentage loaded
  $"#myPlayInfo").text(ppa+"%"); // Show the percentage played
});

jPlayer.jPlayerGetInfo( String: element ) : Object

Description
This method is used to access configuration information inside jPlayer.
This method is still rather basic, as the information available is somewhat limited.
Parameters
element
String defining the element name to return from jPlayer's internal config object.
The returned value can is either a Boolean, Number, String or Object, depending on the element requested.
This documentation will be reviewed in later releases to list the available information elements.
jPlayer will be reviewed in future to make available all internal information.

Code Examples:

$("#jpId").jPlayer( {
  ready: function() {
    $(this).setFile("elvis.mp3").play();
    $("#jpHTML5").text("html5 = " + $(this).jPlayerGetInfo("html5")); // Displays the HTML5 state
  }
});

jPlayer's CSS Classes

The jPlayer plugin uses a number of classes, defined in the CSS, that allow the plugin to control how jPlayer's artwork is displayed on the webpage. All the classes are optional and their use depends on how you choose to represent the jPlayer graphically. CSS classes are defined in the CSS stylesheet for the webpage, and are valid for IDs declared by the jPlayer.jPlayerId() method.

All classes should be defined as ID specific classes. Eg. #mySpecificId.myClass { ... }

cssPrefix_hover

Description
The cssPrefix_hover class is used for the Mouse Hover state, however you may style the :hover yourself in the CSS if you wish.
This functionality solves a problem in IE7 where the CSS :hover state was not working with <div> tags used to define the artwork areas.
The hover state is available to all id's declared by the jPlayer.jPlayerId() method.
In practice you probably only want to use the functionality for the user inputs on the jPlayer interface you create.
ie., Play, Pause and Stop buttons, the volume buttons and maybe the Load Bar.
Default class: jqjp_hover

Code Examples:

#thePlayButton {
  background: url("images/jplayer_play.gif") no-repeat top left;
}

#thePlayButton.jqjp_hover {
  background: url("images/jplayer_play_hover.gif") no-repeat top left;
}

cssPrefix_buffer

Description
The cssPrefix_buffer class is used for the Load Bar's buffer state.
When the MP3 file is buffering, this class is applied to the id declared by: .jPlayerId("loadBar", "theLoadBar")
Default class: jqjp_buffer

Code Examples:

#theLoadBar {
  background: url("images/jplayer_load_bar.gif") repeat-x top left;
}

#theLoadBar.jqjp_buffer {
  background: url("images/jplayer_load_bar_buffer.gif") repeat-x top left;
}

jPlayer Compatibility

jQuery

Compatibility verified with:

  • jQuery 1.3.2
  • jQuery 1.3.1
  • jQuery 1.3
  • jQuery 1.2.6

Browser

Compatibility verified with:

  • Internet Explorer 6 (Windows)
  • Internet Explorer 7 (Windows)
  • Internet Explorer 8 (Windows)
  • Firefox 3 (Windows, Ubuntu)
  • Firefox 3.5 (Windows) †
    • Displaying a load bar is not possible when using HTML5 and OGG files ({oggSupport: true}), as HTMLMediaElement.buffered is not implemented in this browser.
    • When using {oggSupport: true}, the browser appears to enable file seeking, which can cause the music to pause briefly when a new play position is selected.
  • Safari 3 (Windows, Mac)
  • Safari 4 (Windows, Mac) ‡
  • Google Chrome 2 (Windows)
  • Opera 9 (Windows)
    • Progress bar steps are quantised to 1% increments.

† Uses HTML5 audio with OGG files, when {oggSupport: true} is set.
‡ Uses HTML5 audio with MP3 files.

Discuss

jQuery JavaScript Library

ActionScript 2 Compiler

Help us improve jPlayer