jPlayer

HTML5 Audio & Video for jQuery

a project by happyworm

The jPlayer 0.2.2 beta release has been superseded by a new release.
Use the navigation bar above to access the latest release, jPlayer 2.3.0.

jPlayer 0.2.2 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.

jPlayer Constructor

$(id).jPlayer( Object: options )

Description
The jPlayer constructor is applied to the given id and uses the options, if provided.
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. This is defined at creation to eliminate a possible race condition. Ensuring that the function definition exists when Flash triggers it's ready event.
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 path of the jPlayer plugin's SWF file.
This allows the developer to place the jPlayer's SWF file in an alternative relative path.
position
String : (Default: "absolute") : Defines the CSS position style of the Flash.
left
String : (Default: "0") : Defines the CSS left style of the Flash.
top
String : (Default: "0") : Defines the CSS top style of the Flash.
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.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();
});

Code Example #2:

$(document).ready(function() {
  $("#jpId").jPlayer( {
    ready: function () {
	  $("#jpId").setFile("../mp3/elvis.mp3").play();
	},
	cssPrefix: "my_jp_class"} );
  });
});

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: filename ) : jPlayer

Description
This method is used to define the MP3 file to play.
The .setFile(f) method must be used to define an MP3 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.
Parameters
filename
String defining the path to the MP3 file
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

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() { $("#jpId").play(); } );
$("#jpId").onSoundComplete( function() { /* Something groovy! */ } );

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+"%");
	$"#myPlayInfo").text(ppa+"%");
});
$("#jpId").onProgressChange( function(lp,ppr,ppa,pt,tt) { /* Something groovy! */ } );

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)
  • Safari 3 (Windows, Mac)
  • Google Chrome 1 (Windows)
  • Opera 9 (Windows)
    • Progress bar steps are quantised to 1% increments.