jPlayer

jQuery audio player plugin

jPlayer 1.2.0 Developer Guide

Contents

Related Links

jPlayer Fundamentals

Flash Security Rules

The security rules for jPlayer's SWF file have been relaxed using System.security.allowDomain('*') and may be called from any domain.

Generally, you will upload the SWF file with the JavaScript file to a directory called "js" on your domain. If required, use the constructor option swfPath to change the path.

Technically, the plugin files may be linked to remotely at happyworm.com. However, we request that you don't link to the files on happworm.com, since we do not have sufficient resources to become a CDN just now.

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.

MP3 Encoding

Since some browsers use the Flash element of jPlayer, the MP3 files used must be encoded according to the browser’s Adobe Flash Plugin limitations:

  • Constant Bitrate Encoded.
  • Sample Rate a multiple of 11,0025Hz. ie., 22,050Hz and 44,100Hz are valid sample rates.

Server MP3/OGG Response

Your domain's server must give the correct response for MP3 and OGG files.

  • OGG files must have the content type (MIME Type) of audio/ogg. Browsers are strict with the OGG MIME type and will not work unless the MIME type is correct.
  • MP3 files should have the content type (MIME Type) of audio/mpeg. Browsers do not appear to be affected by the MP3 MIME type.
  • Disable GZIP encoding of MP3 files, otherwise the Adobe Flash Plugin will experience issues.
  • Your server must Accept-Ranges. Some HTML5 browsers enable seeking to new file positions during a download, so the server must allow the new range to be requested. (Affects Chrome 4 on Jetty 6 server.)

How to kill jPlayer with CSS

Since jPlayer uses Flash on some browsers, the jPlayer <div> must not be hidden. jPlayer deals with the styling of its own <div>, and you should leave it alone in your CSS definitions. You should also be careful that any jQuery animations, such as fadeIn() or fadeOut(), are not acting on the jPlayer <div> or any of its parents.

ie., Do not do the following:

<head>
   <style>
      #jquery_jplayer {
         display:none; /* Kills jPlayer when using Flash */
      }
   </style>
</head>

<body>
   <div id="jquery_jplayer"></div>
</body>

jPlayer Files

jPlayer requires that two files are uploaded to your server.
jquery.jplayer.min.js
Jplayer.swf

When updating jPlayer, ensure that both files are uploaded from the plugin ZIP, since both files are subject to change.

Plugin Files

jquery.jplayer.min.js
The plugin's JavaScript file, compiled using closure-compiler.appspot.com with "Simple" optimization.
The jquery.jplayer.min.js file should be added to the <head> of the HTML file after the jQuery JavaScript file. Below is how to include the JavaScript file using an absolute path, relative to the server root.
<head>
  <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4/jquery.min.js">
  </script>
  <script type="text/javascript" src="/jPlayer/js/jquery.jplayer.min.js">
  </script>
</head>
Jplayer.swf
The plugin's Flash 8 file, compiled using the Open Source ActionScript 2 Compiler MTASC.
This file is used in browsers that do not support HTML5 <audio>.
The Jplayer.swf file must be uploaded to your server. The default location is relative to your current page in a folder named "js". To modify the location of the Flash file, use the swfPath constructor option. Below is how to set the swfPath to an absolute path, relative to the server root. See jPlayer Constructor for more information.
$("#jpId").jPlayer( {
  swfPath: "/jPlayer/js"
});
The SWF file version can be seen by accessing the Jplayer.swf URL directly in the browser. The JavaScript and SWF versions may not always be identical and you should use both files from the plugin ZIP file to be sure they are compatible. Alternatively, you may double check using the constructor options {errorAlerts:true,nativeSuport:false}, which will give an alert if there is a mismatch, or use $(id).jPlayer("getData","swfVersionRequired") to return the SWF version required for the JavaScript.

Source Files

jquery.jplayer.js
jPlayer's JavaScript source file. This file may be switched with the jquery.jplayer.min.js file. The operation is identical, but the file size is larger.
This file is readable by humans, assuming they understand JavaScript and jQuery.
Jplayer.as
jPlayer's ActionScript 2 source file. This file is compiled using the Open Source ActionScript 2 Compiler MTASC into the Jplayer.swf file used in the jPlayer plugin.
The Jplayer.as file is not required for jPlayer, and does nothing unless compiled.
This file is readable by humans, assuming they understand Flash's ActionScript 2.

jPlayer Constructor

$(id).jPlayer( Object: options ) : jQuery

Description
The jPlayer constructor is applied to the given id and uses the options, if provided. The <div> used by jPlayer should be empty and not used for anything else. It can be placed at the top level of the <body> to help avoid effects on the page corrupting jPlayer's operation.
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.
The next most important option is the swfPath element, which defines the path of jPlayer's SWF file. Remember to upload the SWF file to your server!
Parameters
options
Object defining any changes to the default configuration of jPlayer.
ready :
Function : (Default: function() {}) : Defines a function to call when the jPlayer plugin is ready for use. To reference the current instance, use this.element. Generally, it is recommended to use a function here to at least this.element.jPlayer("setFile",mp3) 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 Flash code. Thus ensuring the Flash function definitions exist when the JavaScript code is executed.
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.
Independent of trailing slash, ie., "myPath/" is the same as "myPath".
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 $(id).jPlayer("setFile", mp3, [ogg]) for more information.
nativeSupport
Boolean : (Default: true) : Enables native audio support in HTML5 browsers.
This allows the developer to force jPlayer to use the Flash component, by setting this option to false.
This option is useful for checking that the swfPath is correct, when developing on an HTML5 browser.
Warning: Some mobile browsers do not support Flash, but do support HTML5.
preload
String : (Default: "none") : Valid values are "none", "metadata" and "auto", which matches the HTML5 draft standard. Use "auto" to preload the file.
customCssIds
Boolean : (Default: false) : By default, jPlayer uses a predefined set of cssIds. Setting this option to true, disables the automatic association of the default Ids. The developer may then specify a custom set of CSS Ids using the $(id).jPlayer("cssId",fn,id) method.
graphicsFix
Boolean : (Default: true) : Enables a graphical update fix, which is useful for Safari and Chrome browsers. This writes a random number to a <div>, which is shifted off the screen area.
jPlayer projects that do not use progress bars can set this value to false.
Warning: Screen readers may attempt to read this random number out loud.
cssPrefix
String : (Default: "jqjp") : Defines the Id prefix for jPlayer's internally generated HTML code.
Useful if you have a naming conflict, but it is highly unlikely that the developer will need to change this setting.
errorAlerts
Boolean : (Default: false) : Enables fatal error reporting through alerts.
Enable this option to help debug your jPlayer application.
warningAlerts
Boolean : (Default: false) : Enables warning reporting through alerts.
Enable this option to help debug your jPlayer application.
position
String : (Default: "absolute") : Defines the CSS position style of the Flash and HTML5 audio.
left
String : (Default: "0") : Defines the CSS left style of the Flash and HTML5 audio.
When HTML5 audio is used by the browser, this value is forced to {left:"-9999px"}. This hides the default play button used by some mobile browsers when they encounter an <audio> tag.
top
String : (Default: "0") : Defines the CSS top style of the Flash and HTML5 audio.
width
String : (Default: "0") : Defines the width of the Flash.
height
String : (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.4/jquery.min.js">
  </script>
  <script type="text/javascript" src="js/jquery.jplayer.min.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.element.jPlayer("setFile", "../mp3/elvis.mp3"); // Defines the mp3
    }
  });
});

Code Example #2:

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

Code Example #3:

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

Code Example #4: For advanced developers.

$(document).ready(function() {
  $("#jpId").jPlayer( {
    ready: function () {
      // Directly access this instance's jPlayer methods. (Does not support chaining.)
      this.setFile("mp3/elvis.mp3", "ogg/elvis.ogg"); // Defines the counterpart mp3 and ogg files
      this.play(); // Auto-Plays the file
    },
    oggSupport: true
  });
});

Code Example #5: Bad Code!

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

jPlayer Methods

jPlayer is controlled by sending the method name through the $(id).jPlayer() plugin method.

$(id).jPlayer( "cssId", String: methodName, String: methodCssId ) : jQuery

Description
The cssId method is used to create associations between jPlayer methods and CSS entities on the webpage. For example, this enables a play button graphic on the webpage to be associated with the method that executes the play command.
By default, jPlayer uses a predefined set of cssIds. Setting the customCssIds constructor option to true, allows the developer to specify a custom set of CSS Ids using the cssId method.
The methodName may only have one methodCssId associated with it through jPlayer. An existing association will be removed if a new association is given.
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.
methodCssId
String containing the name of the CSS Id to associate with the methodName

Code Examples:

$(document).ready(function() {
  $("#jpId").jPlayer( {
    ready: function () {
      this.element.jPlayer("setFile", "mp3/elvis.mp3");
    },
    customCssIds: true
  })
  .jPlayer( "cssId", "play", "thePlayButton" )
  .jPlayer( "cssId", "loadBar", "theLoadBar" );
});

$(id).jPlayer( "setFile", String: mp3, [String: ogg] ) : jQuery

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 .jPlayer("setFile", mp3, [ogg]) method must be used to define an MP3 [and OGG] file before the jPlayer will be able perform other methods like .jPlayer("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 cancelled.
When {nativeSupport: true}, 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.
When {nativeSupport: false}, jPlayer will use the Flash solution for all browsers.
When {nativeSupport: true} and {oggSupport: true} the priority favours HTML5 over Flash and OGG over MP3:
1) HTML5 with OGG, 2) HTML5 with MP3, 3) Flash with MP3
Parameters
mp3
String : Defines the URL of the MP3 file
The URL given must conform to standard URL Encoding Rules.
ogg
[Optional] String : Defines the URL of the OGG file. Mandatory when {oggSupport: true}
The URL given must conform to standard URL Encoding Rules.

Code Examples:

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

$(id).jPlayer( "clearFile" ) : jQuery

Description
This method is used to clear the audio file and stop playback. If an audio file is downloading at the time, the download will be cancelled.
After this command is issued, playback commands such as jPlayer("play") will be ignored until after a new file has been specified using the jPlayer("setFile",mp3[,ogg]) method.
Parameters
none
This method has no parameters.

Code Examples:

$("#jpId").jPlayer( "clearFile" );

$(id).jPlayer( "load" ) : jQuery

Description
This method is used to preload the MP3 [or OGG] file before the play command is given.
This method allows you to selectively preload the files you choose after changing the file using setFile. If you want all files to preload by default, use the jPlayer constructor option {preload:"auto"}.
Parameters
none
This method has no parameters.

Code Examples:

$("#jpId").jPlayer("load");

$(id).jPlayer( "play" ) : jQuery

Description
This method is used to play the MP3 [or OGG] 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").jPlayer("play");

$(id).jPlayer( "pause" ) : jQuery

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

Code Examples:

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

$(id).jPlayer( "stop" ) : jQuery

Description
This method is used to stop the MP3 [or OGG] file.
The play-head will be reset to the start of the song.
If issued immediately after a setFile command, when the browser is using HTML5 audio, this command will initially fail and an internal timeout is setup to retry the command every 100ms until it succeeds.
Parameters
none
This method has no parameters.

Code Examples:

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

$(id).jPlayer( "playHead", Number: percentOfLoaded ) : jQuery

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.
If issued immediately after a setFile command, when the browser is using HTML5 audio, this command will initially fail and an internal timeout is setup to retry the command every 100ms until it succeeds.
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 $(id).jPlayer("onProgressChange", Function: handleChanges) and $(id).jPlayer("getData", String: dataName) for information on gaining access to loadPercent and playPercentRelative values.

Code Examples:

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

$(id).jPlayer( "playHeadTime", Number: playedTime ) : jQuery

Description
This method moves the play head to a new position defined in milliseconds.
If issued immediately after a setFile command, when the browser is using HTML5 audio, this command will initially fail and an internal timeout is setup to retry the command every 100ms until it succeeds.
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 $(id).jPlayer("onProgressChange", Function: handleChanges) and $(id).jPlayer("getData", String: dataName) for information on gaining access to playedTime and totalTime values.

Code Examples:

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

$(id).jPlayer( "volume", Number: percent ) : jQuery

Description
This method is used to control the volume of the MP3 [or OGG] 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").jPlayer("volume", 25);
$("#jpId").jPlayer("volume", volumeValue);

$(id).jPlayer( "volumeMin" ) : jQuery

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

Code Examples:

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

$(id).jPlayer( "volumeMax" ) : jQuery

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

Code Examples:

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

$(id).jPlayer( "onSoundComplete", Function: endOfSong ) : jQuery

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

Code Examples:

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

$("#jpId").jPlayer("onSoundComplete", function() {
  // Directly access this instance's jPlayer methods. (Does not support chaining.)
  this.play(); // Auto-Repeat
});

$(id).jPlayer( "onProgressChange", Function: handleChanges ) : jQuery

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. This event occurs every 100ms when an MP3 [or OGG] file is playing.
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 in milliseconds

Code Examples:

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

$(id).jPlayer( "getData", String: dataName ) : Variable

Description
This method is used to access configuration information inside jPlayer.
The configuration object may also be accessed through $(id).data("jPlayer.config"). However, since this give full read/write access to the data, this is only recommended for advanced developers.
Parameters
dataName
String defining the data element's name to return from jPlayer's internal config object.
The returned value can is either a Boolean, Number, String, Function or an Object, depending on the data requested.
Constructor option data set at creation:
ready : Function
swfPath : String
cssPrefix : String
volume : Number
nativeSupport : Boolean
oggSupport : Boolean
customCssIds : Boolean
graphicsFix : Boolean
errorAlerts : Boolean
warningAlerts : Boolean
position : String
width : Number
height : Number
top : Number
left : Number
quality : String
bgcolor : String
Internal Configuration Data:
canPlayMP3 : Boolean : True if the browser supports MP3 files.
canPlayOGG : Boolean : True if the browser supports OGG files.
html5 : Boolean : True if jPlayer has the option of using HTML5.
usingFlash : Boolean : True if jPlayer is using the Flash component.
usingMP3 : Boolean : True if jPlayer is using MP3 files, or false if using OGG files.
swf : String : The URL of the Jplayer.swf Flash file.
id : String : The HTML entity Id of the jPlayer instance.
fid : String : The HTML entity Id of the Flash.
aid : String : The HTML entity Id of the HTML5 <audio>.
aSel : jQuery : The jQuery selector for the HTML5 <audio>.
hid : String : The HTML entity Id of the hidden graphicsFix <div>.
hSel : jQuery : The jQuery selector for the hidden graphicsFix <div>.
i : Integer : The jPlayer instance number. (Starts at zero.)
audio : HTMLAudioElement : Browser's <audio> DOM object.
swfVersionRequired : String : The SWF version compatible with the JavaScript version.
swfVersion : String : The version of the SWF file, or "n/a" on HTML5 browsers. Initially "unknown".
version : String : The version of the JavaScript file, ie., The jPlayer version.
Diagnostic Information:
diag.isPlaying : Boolean
diag.loadPercent : Number
diag.playedPercentRelative : Number
diag.playedPercentAbsolute : Number
diag.playedTime : Number : milliseconds
diag.totalTime : Number : milliseconds
diag.src : String : The URL of the active audio file. (Either the MP3 or OGG file.)
CSS Id Information:
cssId.play
cssId.pause
cssId.stop
cssId.loadBar
cssId.playBar
cssId.volumeMin
cssId.volumeMax
cssId.volumeBar
cssId.volumeBarValue
Objects that share the cssId structure:
cssId : Object : The HTML element Id names.
cssSelector : Object : The jQuery selectors relating to the cssId.
cssDisplay : Object : The initial css display definitions of the cssId.
clickHandler : Object : The click handler functions of the cssId.

Code Examples:

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

setInterval( function() {
  if($("#jpId").jPlayer("getData", "diag.isPlaying"))
    $("#jpPlaying").text("Listen up!");
  } else {
    $("#jpPlaying").text("Silence is golden!");
  }

  var config = $("#jpId").data("jPlayer.config");
  var mSecLeft = config.diag.totalTime - config.diag.playedTime;
  $("#jpTimeLeft").text(mSecLeft + " milliseconds remain!");
}, 500 );

jPlayer Functions

$.jPlayer.convertTime( Number: milliSeconds ) : String

Description
This function is used to convert a time, in milliseconds, to a string formatted in hours, minutes and seconds. The format of the conversion is defined using the object $.jPlayer.timeFormat.
Parameters
milliseconds
Number : The number of milliseconds to convert.
Returns
String : The formatted time.

Code Examples:

$("#jpId").jPlayer("onProgressChange", function(lp,ppr,ppa,pt,tt) {
  $"#playTime").text($.jPlayer.convertTime(pt)); // Default format of 'mm:ss'
  $"#totalTime").text($.jPlayer.convertTime(tt)); // Default format of 'mm:ss'
});

jPlayer Objects

$.jPlayer.defaults : Object

Description
This object holds the defaults for jPlayer instances. As an alternative to defining the options object through the jPlayer constructor, developers may modify the $.jPlayer.defaults object to configure all subsequent instances of jPlayer. Changing the defaults after instancing jPlayer will have no effect on the existing instances.
This object's properties match those listed for the jPlayer constructor's options object.
$(id).jPlayer( Object: options ) : jQuery

Code Example:

$(document).ready(function() {
  $.jPlayer.defaults.oggSupport = true;
  $("#jpId").jPlayer( {
    ready: function () {
      this.element.jPlayer("setFile", "mp3/elvis.mp3", "ogg/elvis.ogg");
    }
  });
});

$.jPlayer.timeFormat : Object

Description
This object is used to format the time returned by the function $.jPlayer.convertTime( Number: milliSeconds )
Properties
showHour
Boolean : (Default: false) : Displays the hours.
showMin
Boolean : (Default: true) : Displays the minutes.
showSec
Boolean : (Default: true) : Displays the seconds.
padHour
Boolean : (Default: false) : Zero pads the hour if less than 10.
padMin
Boolean : (Default: true) : Zero pads the hour if less than 10.
padMin
Boolean : (Default: true) : Zero pads the hour if less than 10.
sepHour
String : (Default: ":") : Zero pads the hour if less than 10.
sepMin
String : (Default: ":") : Zero pads the hour if less than 10.
sepSec
String : (Default: "") : Zero pads the hour if less than 10.

Code Example:

$.jPlayer.timeFormat.showHour = true;
$.jPlayer.timeFormat.sepHour = " hours ";
$.jPlayer.timeFormat.sepMin = " minutes ";
$.jPlayer.timeFormat.sepSec = " seconds";

$("#jpId").jPlayer("onProgressChange", function(lp,ppr,ppa,pt,tt) {
  $"#playTime").text($.jPlayer.convertTime(pt)); // Format: 'h hours mm minutes ss seconds'
});

jPlayer's Predefined CSS Ids

jPlayer has a predefined set of CSS Ids built in. Below are the default associations between the jPlayer method and the CSS Id.

To define custom Ids use $(id).jPlayer( "cssID", String: methodName, String: methodCssId ) and set the customCssIds constructor option to true.

Default cssId
methodName : methodCssId
"play" : "jplayer_play"
"pause" : "jplayer_pause"
"stop" : "jplayer_stop"
"loadBar" : "jplayer_load_bar"
"playBar" : "jplayer_play_bar"
"volumeMin" : "jplayer_volume_min"
"volumeMax" : "jplayer_volume_max"
"volumeBar" : "jplayer_volume_bar"
"volumeBarValue" : "jplayer_volume_bar_value"

jPlayer Graphical Skins

In an attempt to promote a standard approach to skin development, we are proposing the following standard HTML structure and CSS class naming conventions. The Ids used match the predefined cssIds used by jPlayer, and should not be used for CSS definitions. The skin's CSS should be defined using the standard class names shown below.

A skin should be written to work with both HTML structures, the single and playlist variants, so that a single CSS file is required for a skin. Likewise, all artwork should be included in a single image file. Links to an example skin is given further down.

The skin structure has been designed for accessibility and conforms with the HTML 4.01 Spec. The tabindex attribute is used to control the tabbing order and may be modified to suit the user's needs.

Note that, the pause control artwork can be hidden in the CSS. jPlayer takes the default display type for the pause button from the play button's CSS styling. This avoids the pause button showing briefly at page load.

Standard skin structure: Single Track
As used by this demo.
<div class="jp-single-player">
  <div class="jp-interface">
    <ul class="jp-controls">
      <li><a href="#" id="jplayer_play" class="jp-play" tabindex="1">play</a></li>
      <li><a href="#" id="jplayer_pause" class="jp-pause" tabindex="1">pause</a></li>
      <li><a href="#" id="jplayer_stop" class="jp-stop" tabindex="1">stop</a></li>
      <li><a href="#" id="jplayer_volume_min" class="jp-volume-min" tabindex="1">min volume</a></li>
      <li><a href="#" id="jplayer_volume_max" class="jp-volume-max" tabindex="1">max volume</a></li>
    </ul>
    <div class="jp-progress">
      <div id="jplayer_load_bar" class="jp-load-bar">
        <div id="jplayer_play_bar" class="jp-play-bar"></div>
      </div>
    </div>
    <div id="jplayer_volume_bar" class="jp-volume-bar">
      <div id="jplayer_volume_bar_value" class="jp-volume-bar-value"></div>
    </div>
    <div id="jplayer_play_time" class="jp-play-time"></div>
    <div id="jplayer_total_time" class="jp-total-time"></div>
  </div>
  <div id="jplayer_playlist" class="jp-playlist">
    <ul>
      <li>Track title</li>
    </ul>
  </div>
</div>
Standard skin structure: For Playlists
As used by this demo.
<div class="jp-playlist-player">
  <div class="jp-interface">
    <ul class="jp-controls">
      <li><a href="#" id="jplayer_play" class="jp-play" tabindex="1">play</a></li>
      <li><a href="#" id="jplayer_pause" class="jp-pause" tabindex="1">pause</a></li>
      <li><a href="#" id="jplayer_stop" class="jp-stop" tabindex="1">stop</a></li>
      <li><a href="#" id="jplayer_volume_min" class="jp-volume-min" tabindex="1">min volume</a></li>
      <li><a href="#" id="jplayer_volume_max" class="jp-volume-max" tabindex="1">max volume</a></li>
      <li><a href="#" id="jplayer_previous" class="jp-previous" tabindex="1">previous</a></li>
      <li><a href="#" id="jplayer_next" class="jp-next" tabindex="1">next</a></li>
    </ul>
    <div class="jp-progress">
      <div id="jplayer_load_bar" class="jp-load-bar">
        <div id="jplayer_play_bar" class="jp-play-bar"></div>
      </div>
    </div>
    <div id="jplayer_volume_bar" class="jp-volume-bar">
      <div id="jplayer_volume_bar_value" class="jp-volume-bar-value"></div>
    </div>
    <div id="jplayer_play_time" class="jp-play-time"></div>
    <div id="jplayer_total_time" class="jp-total-time"></div>
  </div>
  <div id="jplayer_playlist" class="jp-playlist">
    <ul>
      <!-- The function displayPlayList() uses this unordered list -->
      <li></li>
    </ul>
  </div>
</div>
Additional Standard CSS classes
jplayer_playlist_current
Example Skin: Blue Monday
The CSS File of the Blue Monday skin.
The Image File of the Blue Monday skin.
The Adobe Photoshop PSD Files for the Blue Monday skin.
Accessibility
While the skin conforms with the HTML 4.01 Spec, unfortunately some browsers do not adhere to the spec. For example, Safari does not include <a> elements in the tab order. If you wish to correct this, the <a> can be replaced with <input> or <button> elements. Using these form elements requires an empty transparent GIF file to be specified for each element, which complicates use when used in dynamic web apps such as WordPress. The <input> and <button> elements also behave differently cross-browser, in particular where Internet Explorer moves the artwork down and to the right when it is clicked on. For these reason, our standard skin uses the <a> element.
The accesskey attribute may be added to each <a> element to provide access key support. The use of access keys depends on your target users. Most users do not even know how to initiate an access key and it varies from browser to browser. The key itself also needs to be conveyed to the user in some manner. Since access keys can interfere with the operation of some browsers we have not used the attribute in the default skin. After invesigation, a clearly labled link is prefered by the majority of screen reader users. ie., Our play button has the word "play" in the link, even though the text is not visible when using a standard browser.

jPlayer Compatibility

jQuery

Compatibility verified with:

  • jQuery 1.4.x
  • jQuery 1.3.x
  • 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.6 (Windows, Mac) †
    • Displaying a load bar is not possible when using HTML5 and OGG files ({oggSupport: true}), as HTMLAudioElement.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) ‡
  • Safari 5 (Windows) ‡
  • Safari 5 (Mac) ‡
    • Changing the play head during download corrupts the audio.buffered information. This causes the load bar to equal the play bar value. This is a browser bug in its DOM.
  • Mobile Safari (iPhone iOS3, iPod Touch iOS3)
    • The MP3 plays in the QuickTime plugin.
  • Mobile Safari (iPad, iPhone iOS4, iPod Touch iOS4) ‡
    • MP3 plays natively in browser.
    • Multiple instances tend to fail after switching between the jPlayer instances a few times.
    • Play and load bar progress do not work well when using multiple instances of jPlayer. This browser enables one audio element at a time, so playing 2 instances together is not possible.
    • Changing the play head during download corrupts the audio.buffered information. This causes the load bar to equal the play bar value. This is a browser bug in its DOM.
  • Google Chrome 4(Windows, Mac) † ‡
    • Displaying a load bar is not possible when using HTML5 native audio, as the TimeRanges object of the HTMLAudioElement.buffered property is not implemented according to the HTML5 Draft Spec in this browser. Currently, HTMLAudioElement.buffered.end(0) returns HTMLAudioElement.duration.
  • Google Chrome 5 (Windows, Mac) † ‡
    • Same issues as Google Chrome 4
  • Opera 9 (Windows)
    • Progress bar steps are quantised to 1% increments.
  • Opera 10 (Windows, Mac)
  • Opera 10.5 (Windows, Mac) †
    • Displaying a load bar is not possible when using HTML5 native audio, as the TimeRanges object of the HTMLAudioElement.buffered property is not implemented according to the HTML5 Draft Spec in this browser. Currently, HTMLAudioElement.buffered.length always returns zero.

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

jPlayer Known Issues

Incompatible Browsers

jPlayer does not work on the following browsers:

  • Wii Opera
  • Playstation 3 Browser

Event Driven Mobile Browsers

The following Mobile browsers require user initiated events to trigger commands that effect audio playback.

  • Mobile Safari
    • This affects the operation of a .jPlayer("play") in the ready() function. See the Safari Web Content Guide for iPhone OS for more information. Quote: "Setting the currentTime property, or calling the pause, play, or load methods fail if they are not called from a touch or gesture event handler."

The Firebug Bug

The Firebug add-on for Firefox can occasionally cause problems with jPlayer. This only happens if the Firebug window is open when the page loads/reloads and when jPlayer is using the Flash component. ie., When only using MP3 files. Even then, the problem is intermittent and usually jPlayer works fine. The problem appears to be that Firebug interferes with the registration of the Flash's external interface functions.

This problem is listed here since developers commonly use Firebug while developing their projects.

Reference: HTML5 Browser Audio Support

Here are details on the supported formats by HTML5 browsers. All browser versions are their latest official release.

HTML5 Audio File Format

HTML5 browsers and their supported audio file formats:

  • Firefox (Mac, PC): OGG
  • Safari (Mac, PC): MP3
  • Mobile Safari iOS4 (iPad, iPhone, iPod): MP3
  • Opera (Mac, PC): OGG
  • Chrome (Mac, PC): MP3, OGG

HTML5 Audio Streams

HTML5 browsers and their support for audio streams. (Note that, jPlayer's Flash fall-back for non-HTML5 browsers works with MP3 streams.)

Audio streams work on:

  • Firefox (Mac, PC): OGG - Has an initial pause (~15 sec) where stream appears to buffer.
  • Safari (Mac): MP3
  • Mobile Safari iOS4 (iPad, iPhone, iPod): MP3
  • Opera (Mac, PC): OGG

Audio streams fail on:

  • Safari (PC): MP3
  • Chrome (Mac, PC): MP3, OGG

External Resources

Some links to resources about HTML5 audio support:

Help us improve jPlayer

Developing and supporting jPlayer is almost a full-time job and we are really just beginning. Help us continue to help you.

Click here to lend your support to: jPlayer: the CSS styleable jQuery audio player plugin and make a donation at www.pledgie.com !

Hire Us!

Need an audio based solution realized or just need some help. Hire Happyworm! Contact: hello@happyworm.com.

Also by Happyworm

Qwiiz

Massively multiplayer real-time quiz game. Cross platform and tuned for the iPad.

Collaborate

jQuery JavaScript Library

ActionScript 2 Compiler