jPlayer Developer Guide : HTML5 Audio & Video for jQuery

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

jPlayer 2.0.0 Developer Guide

If you are new to jPlayer, check out the Quick Start Guide.

jPlayer Fundamentals

Essential jPlayer Media Formats

The media formats that are essential to jPlayer are those that are supported by both the Flash solution and the HTML5 browsers that do not support Flash, such as iOS. It is important that one of these formats is supplied to jPlayer so that popular browsers will be able to play your media. After an essential format has been supplied, additional counterpart formats may be supplied to increase cross-browser support of the HTML5 solution. See the jPlayer({"supplied": "formats"}) option for more details.

Audio

One of the following audio formats must be supplied:

Note that, there is little to no benefit in providing both, due to the way support pans out with HTML5 browsers supporting either both or neither.

Video

The following video format must be supplied:

Setting the size of jPlayer

jPlayer uses the width and height css definitions from the div element it is instanced on. This allows you to define the window size through standard CSS rules. Note that the background-color may be set using the constructor option jPlayer ({"backgroundColor":"#RRGGBB"})

Note that a feature change affects the next release. This system will have to change to enable viewing features, since there is an issue with jQuery returning the CSS definitions in pixels even when defined as percent. jPlayer development patch 2.0.3 notes and details.

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. Use the constructor option jPlayer({"swfPath":path}) to change the path.

Technically, the plugin files may be linked to remotely at jplayer.org. However, we request that you don't link to the files on jplayer.com, since we do not have sufficient resources to become a CDN just now. Additionally, the Flash fallback on the remote server would require the use of absolute URLs for all jPlayer("setMedia", media) URLs.

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.

To develop locally, install a server on your system, such as Apache, to enable a localhost on your computer.

Media Encoding

The media supplied must conform with the codecs supported by HTML5 browsers. The essential jPlayer formats (MP3 or M4A for audio and M4V for video) must also conform with the codecs supported by the Adobe Flash plugin.

jPlayer needs to distinguish between audio and video. This is because jPlayer behaves slightly differently for the two different media types. For example, the video needs to be shown. As a result, formats that are containers have an audio and video type included in their abbreviation to make them unique. For example, M4A and M4V are both MP4 files, and jPlayer knows to play them as audio and video respectively.

MP3

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,025Hz. ie., 22,050Hz and 44,100Hz are valid sample rates.

M4A / M4V

The MP4 file is a container that supports both audio and video. The M4A format is an audio MP4, and the M4V format is a video MP4. The recommended encoding options for standard and mobile browsers are:

H.264 Baseline Profile Level 3.0 video, up to 640 x 480 at 30 fps. Note that B frames are not supported in the Baseline profile.
AAC-LC audio, up to 48 kHz.

OGA / OGV: The OGG file is a container that supports both audio and video. The OGA format is an audio OGG, and the OGV format is a video OGG. The Vorbis and Theora codecs appear to have full support.

WEBMA / WEBMV: The WebM file is a container that supports both audio and video. The WEBMA format is an audio WebM, and the WEBMV format is a video WebM. The Vorbis and VP8 codecs appear to have full support.

WAV

The WAV format is supported by many HTML5 browsers. We recommend that you avoid it though as a counterpart format. The recommended encoding options are:

8-bit and 16-bit linear PCM
Only codec "1" (PCM) is supported.

The following formats have been added in jPlayer development patches (available on GitHub) and are not available in jPlayer 2.0.0.

Encoders:

References:

Server Response

MIME Type

Your domain's server must give the correct MIME type (content type) for all media URLs.

Failure to give the correct MIME type will stop the media from working on some HTML5 browsers. This is a common cause of problems that only affect Firefox and Opera. Other browsers are less strict, but the MIME type should always be checked that it is correct if you having problems getting media to play on any browser.

Media MIME Types

MP3: audio/mpeg
MP4: audio/mp4 video/mp4
OGG: audio/ogg video/ogg
WebM: audio/webm video/webm
WAV: audio/wav

If you use a common extension for both audio and video media, for example audio.mp4 and video.mp4, then simply use the video version of the MIME type for both of them. ie., video/mp4

On Apache servers, you can use the .htaccess file to set the MIME type based on the file extension:

# AddType TYPE/SUBTYPE EXTENSION

AddType audio/mpeg mp3
AddType audio/mp4 m4a
AddType audio/ogg ogg
AddType audio/ogg oga
AddType audio/webm webma
AddType audio/wav wav

AddType video/mp4 mp4
AddType video/mp4 m4v
AddType video/ogg ogv
AddType video/webm webm
AddType video/webm webmv

Do Not GZIP the Media

Disable GZIP encoding of all the media files. Media files are already compressed and the GZIP will just waste CPU on your server.

The Adobe Flash Plugin will experience issues if you GZIP the media.

Do not GZIP the Jplayer.swf file either. Feel free to GZIP the JavaScript.

Byte-Range Requests

Your server must enable Range requests. This is easy to check for by seeing if your server's resonse includes the Accept-Ranges in its header. Most HTML5 browsers enable seeking to new file positions during a download, so the server must allow the new Range to be requested.

Failure to accept byte Range requests will cause problems on some HTML5 browsers. Often the duration cannot be read from the file as some formats require that the start and end of the file is read to know its duration. Chrome tends to be the browser that has most problems if the Range request is not enabled on the server, but all browsers will have some issue even if it is only that you have to wait for all the media to load before jumping close to the end.

This problem is known to affect Jetty 6 servers with their default configuration.

Protecting Your Media

Be careful when trying to restrict access to your media files. The media URL must be accessible over the internet by the user and its response must be in the format expected.

Using the server response to disable the local cache of media can cause problems with some HTML5 browsers. This can cause the duration of the media to be unknown, which will show as a NaN in the duration of jPlayer.

If you do some magic on the backend to make it more secure, them make sure you are accepting the byte Range requests described above.

How to kill jPlayer with CSS or jQuery

Since jPlayer uses Flash on some browsers, the jPlayer <div> must not be hidden. Mobile browsers do not appear to like their HTML5 media being hidden either.

You can change the size of the jPlayer <div> to zero if you want to make it invisible. 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.

For example, do not do the following:

<head>
   <style>
      #jquery_jplayer {
         display:none; /* Kills jPlayer when using Flash */
      }
   </style>
   <script type="text/javascript">
     $("#jquery_jplayer").hide(); /* Kills jPlayer when using Flash */
   </script>
</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

32.5KB (Gzip: 8.1KB)

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

7.5KB

The plugin's Flash 10 file, compiled using Adobe Flash CS4 Professional.

This file is used in browsers that do not support HTML5 <video> and <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"
});

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.fla

jPlayer's Adobe Flash CS4 Professional editor file. This file is compiled using Adobe Flash CS4 Professional into the Jplayer.swf file used in the jPlayer plugin. The Jplayer.fla file is not required for jPlayer, and does nothing unless compiled.

This file is empty, except for setting its class to Jplayer.as.

Jplayer.as

jPlayer's ActionScript 3 source file. 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 3.

happyworm.jPlayer AS3 package

Contains jPlayer's ActionScript 3 source files for classes used in Jplayer.as. These files are not required for jPlayer, and do nothing unless compiled.

These files are readable by humans, assuming they understand Flash's ActionScript 3.

jPlayer Constructor

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

Description

The jPlayer constructor is applied to the given cssSelector (normally an id selector) and uses the options, if provided. The <div> used by jPlayer should be empty and not used for anything else.

In some cases, the jPlayer div can be placed at the top level of the <body> to help avoid effects on the page corrupting jPlayer's operation. This applies to an audio player that does not use the poster feature of jPlayer.

Note that the most important option is the ready event handler, which is a function defining the actions to perform once jPlayer is ready for use. Attempting to issue commands to jPlayer before the ready event occurs will result in jPlayer raising error events if the Flash fallback is used and commands will be ignored.

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!

Note that a bug has been found in jPlayer 2.0.0 when using jQuery 1.6+ with the automatic ID creation. This affected jPlayer when a jQuery class selector is used to select the jPlayer div, $(".some-class"), and no ID is defined in the html. jPlayer development patch 2.0.21 notes.

Parameters

options

Object defining any changes to the default configuration of jPlayer.

ready :

Function : (Default: undefined) : Defines an event handler function that is bound to the $.jPlayer.event.ready event. To reference the current instance, use $(this). Generally, it is recommended to use a function here to at least $(this).jPlayer("setMedia",media) the instance to a valid url ready for use.

The ready event handler 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.
The handler is bound with the .jPlayer namespace.

Note that a bug has been found in jPlayer 2.0.0 with the ready event when used with the Flash fallback, where the ready event will trigger twice if setMedia is used in the event handler. jPlayer development patch 2.0.2 notes.

swfPath

String : (Default: "js") : Defines the path of jPlayer's Jplayer.swf file. This allows the developer to place the SWF file wherever they choose by using an alternative relative path, absolute path or server root relative path.

You can test that your swfPath is correct on an HTML5 browser that supports flash, by using the constructor option jPlayer({solution:"flash, html").

An incorrect swfPath will generate $.jPlayer.event.error events with error type $.jPlayer.error.FLASH when you issue commands like jPlayer("setMedia", media)

Independent of trailing slash, ie., "myPath/" is the same as "myPath".
The URL given must conform to standard URL Encoding Rules.

solution

String : (Default: "html, flash") : Defines the priority of the html and flash solutions. The default is to use HTML first, with a Flash fallback. Swapping the order to "flash, html" causes the Flash to be used first, with an HTML fallback.

Depending on the supplied formats, jPlayer may even use both solutions. For example, using jPlayer as a media player with {supplied:"mp3,oga,m4v"} would on browsers like Firefox require the Flash solution to play the video media format, while the audio media can be played in the HTML solution.

While you could specify only one solution, we do not recommend that you do it!

The solution picked by jPlayer depends on your brower and the formats in the supplied option.

The Flash fallback in Internet Explorer 9 was enabled in jPlayer development patch 2.0.8 notes.
The Flash fallback was originally disabled in IE9 as it did not work with IE9 beta.

supplied

String : (Default: "mp3") : Defines the formats supplied to jPlayer. The order defines the priority, with the left most format being highest. Formats to the right are lower priority.

See Media Encoding for more details on the formats. See Essential Formats for more details on why some formats are manditory.

Essential Audio formats: mp3 or m4a.
Essential Video format: m4v.

Counterpart formats: oga, ogv, wav, webma, webmv.

Note that additional counterpart formats were added for fla and flv in jPlayer development patch 2.0.13 notes.

All formats in the supplied option must be given in every jPlayer("setMedia",media) command. However, you can supply both video and audio formats if you want and then only use the video or audio media when using jPlayer("setMedia",media) command. (You must give all the audio formats or all the video formats in the supplied option.)

The solution priority dominates the priority of the supplied formats. jPlayer works by finding the first working format in a given solution. So in Chrome with {solution:"html,flash"} and {supplied:"mp3,oga"} the mp3 file would play in native HTML, even though Chrome could play either.

The format picked by jPlayer depends on your brower and the solution option.
Essential formats are those supported by Flash and (luckily) by browsers that do not allow Flash. ie., iPad/iPhone
Counterpart formats are supplied to improve x-browser HTML5 media support.
Rumors based on jPlayer 1.2.0 suggest that for Android to work, the mp3 format should be higher priority than oga.

preload

String : (Default: "metadata") : Valid values are "none", "metadata" and "auto", which matches the HTML5 draft standard. Use "auto" to preload the file.

Preload is a hint to the user agent, not a command. Some browsers ignore this option.

volume

Number : (Default: 0.8) : Defines the initial volume as a value from 0 to 1.

Note that a feature change affects the next release. The volume is an option and will be maintained as an option correctly, rather than copying to the status and maintaining it there. jPlayer development patch 2.0.5 notes.

muted

Boolean : (Default: false) : Defines the initial muted state.

backgroundColor

String : (Default: "#000000") : Defines the background color of the jPlayer <div> and the Flash. The string is an RGB hash of the form "#RRGGBB".

cssSelectorAncestor

String : (Default: "#jp_interface_1") : Defines the cssSelector of an ancestor of all cssSelectors. Usually an id.

Note that a feature change affects the next release. The default value will be changing to (Default: "#jp_container_1"). jPlayer development patch 2.0.3 notes and details.

cssSelector

Object : (Default: {cssSelectors}) : This object defines all the selectors used to associate jPlayer's controls and feedback with the HTML in the page. By default, jPlayer uses a predefined set of cssSelectors.

idPrefix

String : (Default: "jp") : Defines the Id prefix for jPlayer's internally generated HTML code.

Useful if you have a naming conflict, but it is unlikely that the developer will need to change this setting.

errorAlerts

Boolean : (Default: false) : Enables error reporting through alerts.

Enable this option to help debug your jPlayer application.

Note that a bug has been found in jPlayer 2.0.0 with the errorAlerts option, where any alerts will interfere with the Flash fallback's ready event. jPlayer development patch 2.0.1 notes.

warningAlerts

Boolean : (Default: false) : Enables warning reporting through alerts.

Enable this option to help debug your jPlayer application.

Note that a bug has been found in jPlayer 2.0.0 with the warningAlerts option, where the errorAlerts option was actually being used to enable the warnings. jPlayer development patch 2.0.1 notes.

eventType

Function : (Default: undefined) : Just like the jPlayer ready event, you can bind a handler to any of the jPlayer Events Types. The events include of the HTML5 media events.

You can bind handlers to events like timeupdate to perform an action when it occurs. See Using jPlayer Events for more information and examples.

Note that eventType itself is not a constructor option. Eg., The ready constructor option is an eventType.
Warning: The flash fallback does not emulate all events.
Warning: HTML5 media events vary x-browser.

The following options have been added in jPlayer development patches (available on GitHub) and are not available in jPlayer 2.0.0.

emulateHtml

Boolean : (Default: false) : Enables the HTML bridge.

This option enables a bridge that emulates the HTML media properties and events on the jPlayer element. All properties are read only. The majority of the useful media properties are emulated.

This option was added in jPlayer development patch 2.0.10 notes.

Example use with Popcorn.js. Note that this code is for an audio player.

ready: function(event) {
  if(event.jPlayer.html.used && event.jPlayer.html.audio.available) {
    // Use the actual HTML media element
    p = Popcorn('#' + $(this).data("jPlayer").internal.audio.id);
  } else {
    // Use enable the HTML bridge with the Flash fallback
    $(this).jPlayer("option","emulateHtml",true);
    p = Popcorn('#' + $(this).attr("id"));
  }
}

noConflict

String : (Default: "jQuery") : Allows the global variable name of jQuery to be set.

This option can be changed to whatever you require after using the jQuery.noConflict(true) command. The jQuery variable name is important for the Flash fallback to communicate with jPlayer's JavaScript.

This option was added in jPlayer development patch 2.0.9 notes.

wmode

String : (Default: "opaque") : Allows the wmode of the Flash fallback to be set.

Valid wmode values: window, transparent, opaque, direct, gpu

This option was added in jPlayer development patch 2.0.6 notes.
Changed the default to "opaque" (from "window") in jPlayer development patch 2.0.19 notes.

fullScreen

Boolean : (Default: false) : Sets the inital state of the full screen mode.

This option is normally changed through the full screen and restore screen buttons on the interface.

This option was added in jPlayer development patch 2.0.3 notes and details.

size

object : Sets the size of the restored screen mode.

This option was added in jPlayer development patch 2.0.3 notes and details.

Object Properties

width: String : (Default: [Video:"480px"] [Audio:"0px"]) : The width as a CSS rule.
height: String : (Default: [Video:"270px"] [Audio:"0px"]) : The height as a CSS rule.
cssClass: String : (Default: [Video:"jp-video-270p"] [Audio:""]) : The class name added to the cssSelectorAncestor when in this mode.

sizeFull

object : Sets the size of the full screen mode.

This option was added in jPlayer development patch 2.0.3 notes and details.
Changed the default of height to "100%" (from "90%") in jPlayer development patch 2.0.19 notes.

Object Properties

width: String : (Default: [Video:"100%"] [Audio:"0px"]) : The width as a CSS rule.
height: String : (Default: [Video:"100%"] [Audio:"0px"]) : The height as a CSS rule.
cssClass: String : (Default: [Video:"jp-video-full"] [Audio:""]) : The class name added to the cssSelectorAncestor when in this mode.

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).jPlayer("setMedia", {
        mp3: "../mp3/elvis.mp3" // Defines the mp3 url
      });
    }
  });
});

Code Example #2:

$(document).ready(function() {
  $("#jpId").jPlayer( {
    ready: function () {
      $(this).jPlayer("setMedia", {
        m4a: "mp3/elvis.m4a", // Defines the m4a (AAC) url
        oga: "ogg/elvis.ogg" // Defines the counterpart oga url
      });
    },
    supplied: "m4a, oga",
    swfPath: "/jPlayer/js"
  });
});

Code Example #3:

$(function() { // executed when $(document).ready()
  $("#jpId").jPlayer( {
    ready: function () {
      $(this).jPlayer("setMedia", {
        m4v: "http://www.myDomain.com/myVideo.m4v" // Defines the m4v url
      }).jPlayer("play"); // Attempts to Auto-Play the media
    },
    supplied: "m4v",
    swfPath: "jPlayer/js"
  });
});

Code Example #4:

$(function() { // executed when $(document).ready()
  $("#jpId").jPlayer( {
    ready: function () {
      $(this).jPlayer("setMedia", {
        m4v: "/media/myVideo.m4v", // Defines the m4v url
        ogv: "/media/myVideo.ogv" // Defines the counterpart ogv url
      }).jPlayer("play"); // Attempts to Auto-Play the media
    },
    solution: "flash, html", // Flash with an HTML5 fallback.
    supplied: "m4v, ogv",
    swfPath: "/scripts"
  });
});

Code Example #5: Bad Code!

$(document).ready(function() {
  $("#jpId").jPlayer( {
    ready: function () {
      $(this).jPlayer("setMedia", {
        mp3: "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( "setMedia", Object: media ) : jQuery

Description

This method is used to define the media to play. The media parameter is an object that has properties defining the different encoding formats and a poster image.

The jPlayer("setMedia", media) method must be used to define the media before jPlayer will be able perform other methods like jPlayer("play").

All formats defined in the constructor option jPlayer({supplied: "f1, f2, fN") must be given a valid url to the media encoded in that format. The exception is when using both video and audio media types in a single jPlayer. Then either all the supplied audio formats or all the supplied video formats must be defined.

The constructor option jPlayer({solution: "s1, s2") can be used to define the priority of the HTML and Flash solutions used by jPlayer.

jPlayer distinguishes between the media types, and using both together in a single setMedia command makes it difficult to determine what actually plays. The decision is based on the priority of solution and supplied and the browser being used. ie., The 1st one that can work in the supplied priority, will work, be that video or audio.

jPlayer does not begin downloading the new media defined by the setMedia method, unless the constructor option jPlayer({preload: "auto") is used. Even then, the media may not download as it depends on the browser you are using. Mobile browser such as Mobile Safari on iOS 4.2 require a gesture before any media is downloaded or played. ie., The user must press a button to initiate the load or play operations the 1st time.

Any media playing when the command is issued will be paused and the download cancelled.

However, if you are switching between media types, for example video to audio, and jPlayer is using the HTML solution, then the previous media type is paused and if it was video, hidden. Otherwise the iPhone's built in video player hangs when the src is cleared to cancel the download.

Do not use relative URLs for the media. The media URLs must be absolute or relative to the server root. For example, "http:www.jplayer.org/media/video.m4v" or "/media/video.m4v".

Relative URLs will have problems with the Flash fallback with M4A and M4V formats. If your Jplayer.swf file is on another domain, (for some reason that makes sense to you,) then absolute URLs must be used.

Parameters

media

Object : Defines the media format URLs and poster

mp3: String : Defines the URL of the mp3 audio format
m4a: String : Defines the URL of the m4a audio format (AAC/MP4)
m4v: String : Defines the URL of the m4v video format (H.264)
oga: String : Defines the URL of the oga audio format (OGG)
ogv: String : Defines the URL of the ogv video format (OGG)
webma: String : Defines the URL of the webm audio format
webmv: String : Defines the URL of the webm video format
wav: String : Defines the URL of the wav audio format
poster: String : Defines the URL of the poster image

The URLs given must conform to standard URL Encoding Rules.

Note that only the properties listed are used by jPlayer, so you could store all kinds of other info in the same object if your project works better that way. For example, the title and album names of an audio track. However, we do plan to expand the media object properties in the future Properties may one day include: stream, chapters, subtitles.

Code Examples:

$("#jpId").jPlayer( {
  ready: function() {
    $(this).jPlayer( "setMedia", {
      m4a: "m4a/elvis.m4a",
      oga: "oga/elvis.oga",
      webma: "webm/elvis.webm"
    });
  },
  supplied: "webma, m4a, oga"
);

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

Description

This method is used to clear the media and stop playback. If a media 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 and raise error events until after new media has been specified using the jPlayer("setMedia",media) method.

There are very few circumstances when it is appropriate to use this method. In general when you are changing media, this action is automatically performed.

Using this clearMedia by itself on the iOS iPhone or iPod Touch will corrupt the built n video pllayer if it is open at the time the command executes.
IE9 Beta is buggy and the attempt to cancel the download is not performed inside jPlayer when IE9 is detected.

Parameters

This method has no parameters.

Code Examples:

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

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

Description

This method is used to preload the media before the play command is given. There is no point using load if you are going to jPlayer("play", [time]) immediately afterwards, just play it. Likewise, with jPlayer("pause", [time]), if a time greater than zero is given.

This method allows you to selectively preload the files you choose after changing the file using setMedia. If you want all files to preload by default, use the jPlayer constructor option {preload:"auto"}.

This command is affected by browser and some ignore the command, or require a gesture to initiate it the 1st time.

Parameters

This method has no parameters.

Code Examples:

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

$(id).jPlayer( "play", [Number: time] ) : jQuery

Description

This method is used to play the media specified using jPlayer("setMedia", media).

If necessary, the file will begin downloading.

Without the time parameter, new media will play from the start. Open media will play from where the play-head was when previously paused using jPlayer("pause", [time]).

The optional time paramater will move the play-head position to the time given in seconds. jPlayer("play", 0) is useful for forcing play from the start of the track, but is redundant for new media, which always starts from the beginning. This can be used to jump immediately to a play time afer changing media. jPlayer will seek to the time given and play when able to.

If issued immediately after a setMedia command, with the time parameter, and when the browser is using the HTML5 solution, this command will initially fail and an internal timeout is setup to retry the command every 100ms until it succeeds.

Note that a bug has been found in jPlayer 2.0.0 with the play method, where giving the time parameter on broken links causes the url to be polled. jPlayer development patch 2.0.12 notes.

Parameters

time

[Optional] Number : Defines the new play-head position in seconds.

If used while downloading, play will begin once the media is seekable to that point.

To make media playback loop, add jPlayer("play") to the ended event. jPlayer deals with reseting the media to the start in the ended event, so the time equals zero is not required.

Code Examples:

$("#jpId").jPlayer( {
  ready: function() { // The $.jPlayer.event.ready event
    $(this).jPlayer("setMedia", { // Set the media
      m4v: "m4v/presentation.m4v"
    }).jPlayer("play"); // Attempt to auto play the media
  },
  ended: function() { // The $.jPlayer.event.ended event
    $(this).jPlayer("play"); // Repeat the media
  },
  supplied: "m4v"
);

$("#jumpToTime").click( function() {
  $("#jpId").jPlayer("play", 42); // Begins playing 42 seconds into the media.
});

$(id).jPlayer( "pause", [Number: time] ) : jQuery

Description

This method is used to pause the media.

The jPlayer("pause", time) can be used to jump immediately to a play-head time afer changing media. The media will begin downloading, and cue the media ready when able to.

Without the time parameter, new media that has not been loaded or played will ignore this command. This avoids downloading the new media when the redundant command is given. Open media will pause if it was playing, otherwise there will be no effect.

The optional time paramater will move the play-head position to the time given in seconds and if necessary, the file will begin downloading. jPlayer("pause", 0) is the same as jPlayer("stop"). New media will ignore the jPlayer("pause", 0) commmand until after the media has started loading. This avoids downloading the new media when the redundant command is given.

Note that a bug has been found in jPlayer 2.0.0 with the pause method, where giving the time parameter on broken links causes the url to be polled. jPlayer development patch 2.0.12 notes.

Parameters

time

[Optional] Number : Defines the new play-head position in seconds.

If used while downloading, the play-head will cue once the media is seekable to that point.

Using a jPlayer("pause", 0) in the ended event is redundant and should not be used.
This avoids a fatal bug on Chrome (Win/OSX), where the browser crashes if you were to follow the jPlayer("pause", 0) with a jPlayer("setMedia") in the ended event.

Code Examples:

$("#jpId").jPlayer("pause", 10); // Pauses and moves the play-head 10 seconds into the song.

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

Description

This method pauses all instances except the instance that invoked the command. This is useful in events such as the play event to pause all the other players on the page when an instance starts playng.

The play event handler can be defined in the constructor options.

Parameters

This method has no parameters.

Code Examples:

$(id).bind($.jPlayer.event.play, function() { // Bind an event handler to the instance's play event.
  $(this).jPlayer("pauseOthers"); // pause all players except this one.
});

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

Description

This method is used to stop the media and reset the play-head to the start of the media.

This command is the same as jPlayer("pause", 0). The method is available so that a stop button can be used in your interface, if you want one.

If issued immediately after a setMedia command, this command is ignored.

Parameters

This method has no parameters.

Using a jPlayer("stop") in the ended event is redundant and should not be used.
This avoids a fatal bug on Chrome (Win/OSX), where the browser crashes if you were to follow the jPlayer("stop") with a jPlayer("setMedia") in the ended event.

Code Examples:

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

$(id).jPlayer( "playHead", Number: percentOfSeekable ) : 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 seekBar and move the play-head to the new position.

Note that this only moves the play-head. Whether the media plays from that point depends on its current state. ie., If it was playing, play continues from the new play-head. If it was paused, the media is cued to the new play-head position.

If issued immediately after a setMedia command, the effect is the same as jPlayer("pause", 0), which is ignored.

Parameters

percentOfSeekable

Number (0 to 100) defining the percentage played when compared to the current percentage seekable.

Only when completely seekable does the percentage relate to the total length of the media.
Most HTML5 browsers have seeking enabled, so the seekable value jumps to 100% when the media starts downloading.

Code Examples:

$("#jpId").jPlayer("playHead", 0); // Move play-head to start.
$("#jpId").jPlayer("playHead", 10); // Move play-head to 10% of the seekable length.

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

Description

This method is used to control the volume of the media being played. Note that the initial volume is set through the constructor option: jPlayer({volume:0.4})

While muted you can change this value, but the media will remain muted.
Setting the volume to zero is not the same as using mute. The two systems are independent.

Parameters

ratio

Number (0 to 1) defining the ratio of maximum volume.

Silence: 0
Half: 0.5
Maximum: 1

Code Examples:

$("#jpId").jPlayer("volume", 0.75);

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

Description

This method mutes the media's sounds. Note that the initial muted state is set through the constructor option: jPlayer({muted:true})

Parameters

This method has no parameters.

Code Examples:

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

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

Description

This method unmutes the media's sounds. Note that the initial muted state is set through the constructor option: jPlayer({muted:false})

Parameters

This method has no parameters.

Code Examples:

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

$(id).jPlayer( "option", [String: key, [Variable: value]] ) : Variable

Description

This method is used to access configuration information inside jPlayer.

The jPlayer object itself may also be accessed through $(id).data("jPlayer"). However, since this gives full read/write access to all data and access to all the methods, even the internal methods, this is only recommended for advanced developers.

The options are defined in the constructor. Full get access is enabled, where a copy of the option is returned. However you may currently only set a limited number of options after instancing jPlayer. See the jPlayer Options.

This section will be updated early 2011.

Parameters

key

String defining the option property name. Supports dot notation.

The returned value can is either a Boolean, Number, String, or an Object, depending on the data requested.
Event handlers defined in the constructor are not included, since they can be removed using the ".jPlayer" namepspace.

value

The new value of the option.

Events

$.jPlayer.event.warning

Event Codes: $.jPlayer.warning.OPTION_KEY

Code Examples:

var solution = $("#jpId").jPlayer("option", "solution"); // Get the solution string, "html, flash" by default.
var cssSelector = $("#jpId").jPlayer("option", "cssSelector"); // Get the cssSelector object.

var playSelector = $("#jpId").jPlayer("option", "cssSelector.play"); // Get the cssSelector for the play method.
var playSelector = $("#jpId").jPlayer("option", "cssSelector").play; // Get the cssSelector for the play method.

$("#jpId").jPlayer("option", "cssSelector.play", ".my-new-class"); // Set the cssSelector for the play method.
$("#jpId").jPlayer("option", "cssSelector", {play:".my-new-class"}); // Set the cssSelector for the play method. (Can set multiple selectors in the object.)

$("#jpId").jPlayer("option", "cssSelectorAncestor", "#my-new-interface"); // Set the cssSelectorAncestor and refresh all associations.

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

Description

This method removes jPlayer. All event and interface bindings created by jPlayer are removed. After destroying the instance, a new jPlayer can be instanced on the node.

All event handlers with the .jPlayer namespace are removed by this method.

Note that a bug has been found in jPlayer 2.0.0 with the destroy method, where any empty or unfound cssSelector properties throw a JavaScript exception. jPlayer development patch 2.0.11 notes.

Note that a bug has been found in jPlayer 2.0.0 with the destroy method, where the jPlayer instance is not removed correctly from the instances object. This can cause errors with the $.jPlayer.pause() function and the jPlayer("pauseOthers") method. jPlayer development patch 2.0.23 notes.

Note that a bug has been found in jPlayer 2.0.0 with the destroy method, when using streams. This can cause some browsers to continue downloading the stream. Solve by issuing a clearMedia before destroy. jPlayer development patch 2.0.27 notes.

Parameters

This method has no parameters.

Code Examples:

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

jPlayer Options

jPlayer allows you to change the following options after instancing. All other options must be defined at creation through the constructor options.

$(id).jPlayer( "option", "cssSelector", String: method, String: selector ) : jQuery

Description

This option allows developers to change the cssSelector associations after jPlayer has been instanced on the page.

The cssSelector method is used with the jPlayer constructor option cssSelectorAncestor 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 cssSelectors, where all the css selectors are class selectors. The strings are added to the end of the cssSelectorAncestor string, with a space in between. The default cssSelectorAncestor is an id selector. By using a single id and a common class structure, multiple instances of jPlayer are easy to add to the page. The idea is that jPlayer is associated with a unique interface, hence the id, and then the rest of the structure is common, hence the classes.

The method may only have one selector associated with it through jPlayer. An existing association will be removed if a new association is given. An empty string clears exisiting associations.

jPlayer uses the ".jPlayer" event namespace for binding and unbinding methods to CSS entities.

Parameters

method: String containing the name of the method to associate with the selector.
See the predefined cssSelectors for the list of valid method names.
selector: String containing the CSS Selector to associate with the method.
Usually a class selector. Eg., ".jp-play"

Events

$.jPlayer.event.warning

Event Codes: $.jPlayer.warning.CSS_SELECTOR_COUNT
$.jPlayer.warning.CSS_SELECTOR_METHOD
$.jPlayer.warning.CSS_SELECTOR_STRING

Code Examples:

$(document).ready(function() {
  $("#jpId").jPlayer( {
    ready: function () {
      $(this).jPlayer("setMedia", {mp3: "mp3/elvis.mp3"});
    },
    cssSelectorAncestor: "", // Remove the ancestor css selector clause
    cssSelector: {
      play:"#myOldPlayButton" // Set a custom css selector for the play button
      // The other defaults remain unchanged
    }
  })

  // ... Some time later, otherwise you'd just set it in the constructor ...

  $("#jpId").jPlayer( "option", "cssSelector", "play", "#myNewPlayButton" );
});

$(id).jPlayer( "option", "cssSelectorAncestor", String: selector ) : jQuery

Description

This option allows the developers to change the associations after jPlayer has been instanced on the page.

Setting this option causes all the cssSelector associations to be refreshed with the new ancestor. Allowing you to switch between interfaces easily. I am not sure why you would want to do that, but it's here if you need it.

Parameters

selector: String containing the CSS Selector to associate with the cssSelector
Usually an id selector. Eg., "#jp_interface_1"

Events

$.jPlayer.event.warning

Event Codes: $.jPlayer.warning.CSS_SELECTOR_COUNT Event added in jPlayer development patch 2.0.4 notes.

Code Examples:

$(document).ready(function() {
  $("#jpId").jPlayer( {
    ready: function () {
      $(this).jPlayer("setMedia", {mp3: "mp3/elvis.mp3"});
    },
    cssSelectorAncestor: "#interface-on-the-left" // Define the ancestor css selector
  })

  // ... Some time later, otherwise you'd just set it in the constructor ...

  $("#jpId").jPlayer( "option", "cssSelectorAncestor", "#interface-on-the-right" );
});

jPlayer Events

jPlayer communicates with your code via events.

All jPlayer events can have a handler defined using the constructor option of the same name:
jPlayer({eventName:function(e){...}})
Event handlers created by constructor options have the ".jPlayer" namespace.

jPlayer Event Types

$.jPlayer.event.ready * †
$.jPlayer.event.resize * †
$.jPlayer.event.error * ‡
$.jPlayer.event.warning * †
$.jPlayer.event.loadstart *
$.jPlayer.event.progress *
$.jPlayer.event.suspend
$.jPlayer.event.abort
$.jPlayer.event.emptied
$.jPlayer.event.stalled
$.jPlayer.event.play *
$.jPlayer.event.pause *
$.jPlayer.event.loadedmetadata
$.jPlayer.event.loadeddata
$.jPlayer.event.waiting
$.jPlayer.event.playing
$.jPlayer.event.canplay
$.jPlayer.event.canplaythrough
$.jPlayer.event.seeking *
$.jPlayer.event.seeked *
$.jPlayer.event.timeupdate *
Note that a bug has been found in jPlayer 2.0.0 with the timeupdate event when using the Flash fallback. Using the pause command will always generate a timeupdate event from the Flash, whether playing or paused. This caused recursion loops leading to stack overflow errors. jPlayer development patch 2.0.26 notes.
$.jPlayer.event.ended *
$.jPlayer.event.ratechange
$.jPlayer.event.durationchange
$.jPlayer.event.volumechange *

* A robust jPlayer event supported by Flash and HTML5 browsers

† jPlayer event that is not part of the HTML5 Spec

‡ jPlayer event that differs from the html Spec. ie., There is more than 1 type of error.

We plan to expand the emulation of HTML5 Media events in the Flash.

jPlayer Event Object

eventHandler(event)

event: Object: Standard jQuery $.Event() properties.
event.jPlayer: Object : The jPlayer information object.
event.jPlayer.error: Object
event.jPlayer.error.type: String : The error event code
event.jPlayer.error.context: String : The cause of the error
event.jPlayer.error.message: String : Message describing the error
event.jPlayer.error.hint: String : A suggestion on how to fix the error
event.jPlayer.flash: Object : Info about the Flash solution
event.jPlayer.html: Object : Info about the HTML solution
event.jPlayer.status: Object
event.jPlayer.status.src: String : The URL being used by jPlayer.
event.jPlayer.status.file: Object : Pointer to the media object used in setMedia.
event.jPlayer.status.seekPercent: Number : Percent seekable
event.jPlayer.status.currentPercentRelative: Number : Current time as a percent of seekPercent
event.jPlayer.status.currentPercentAbsolute: Number : Current time as a percent of duration
event.jPlayer.status.currentTime: Number : The current time in seconds
event.jPlayer.status.duration: Number : The duration of the media
event.jPlayer.status.volume: Number
event.jPlayer.status.muted: Boolean
event.jPlayer.status.srcSet: Boolean
event.jPlayer.status.paused: Boolean
event.jPlayer.status.waitForPlay: Boolean
event.jPlayer.status.waitForLoad: Boolean
event.jPlayer.status.video: Boolean
event.jPlayer.status.width: String : The CSS style width of jPlayer.
event.jPlayer.status.height: String : The CSS style height of jPlayer.
event.jPlayer.version: Object
event.jPlayer.version.script: String : jPlayer's JavaScript version
event.jPlayer.version.flash: String : jPlayer's Flash version, or "unknown" if Flash is not being used
event.jPlayer.version.needFlash: String : The Flash version compatiable with the JavaScript
event.jPlayer.warning: Objec
event.jPlayer.warning.type: String : The warning event code
event.jPlayer.warning.context: String : The cause of the warning
event.jPlayer.warning.message: String : Message describing the warning
event.jPlayer.warning.hint: String : A suggestion on how to fix the warning

This list will be updated early 2011.

jPlayer Error Event Codes

event.jPlayer.error.type

$.jPlayer.error.FLASH: A problem with the Flash insertion on the page.
$.jPlayer.error.NO_SOLUTION: No media playback solution is available.
$.jPlayer.error.NO_SUPPORT: Not possible to play any media format provided in setMedia.
$.jPlayer.error.URL: Error with media URL. †
$.jPlayer.error.URL_NOT_SET: Media playback command not possible as no media is set.
$.jPlayer.error.VERSION: Mismatch in versions of JavaScript and Flash of jPlayer.

† Equivilent to the HTML5 Media error event.

jPlayer constructor option jPlayer({errorAlerts:true}) will create alerts when an error event occurs.

jPlayer Warning Event Codes

event.jPlayer.warning.type

$.jPlayer.warning.CSS_SELECTOR_COUNT: The number of jPlayer('cssSelector') found did not equal one.; Added in jPlayer development patch 2.0.4 notes. The number of jPlayer('cssSelectorAncestor') found did not equal one.
$.jPlayer.warning.CSS_SELECTOR_METHOD: The jPlayer('cssSelector') method is not valid.
$.jPlayer.warning.CSS_SELECTOR_STRING: The jPlayer('cssSelector') was not a valid string.
$.jPlayer.warning.OPTION_KEY: The option requested in jPlayer('option') is undefined.

jPlayer constructor option jPlayer({warningAlerts:true}) will create alerts when a warning event occurs.

Using jPlayer Events

Just like any other event in jQuery, jPlayer events are bound to handler functions using jQuery.bind(). To remove an event use jQuery.unbind().

Use the $.jPlayer.event object to access event type strings. All events have a jPlayer Event Object with easy access to information at the time the event occured.

All jPlayer events can have a handler defined using the constructor option of the same name.
jPlayer({eventType:handler})

Note that, the event type used in the constructor is the property name of the event, not the event string code. For example, the event type $.jPlayer.event.ready has the constructor option jPlayer({ready:handler}):

Event handlers created by constructor options have the ".jPlayer" namespace.

Code Examples:

$("#repeat-on").click( function() {
  $("#jpId").bind($.jPlayer.event.ended + ".jp-repeat", function(event) { // Using ".jp-repeat" namespace so we can easily remove this event
    $(this).jPlayer("play"); // Add a repeat behaviour so media replays when it ends. (Loops)
  });
  return false;
 });

$("#repeat-off").click( function() {
  $("#jpId").unbind($.jPlayer.event.ended + ".jp-repeat"); // Remove the ended events with the ".jp-repeat" namespace
  return false;
 });

$("#jpId").bind($.jPlayer.event.play, function(event) { // Add a listener to report the time play began
  $("#playBeganAtTime").text("Play began at time = " + event.jPlayer.status.currentTime);
});

$("#jpId").unbind($.jPlayer.event.play); // Remove all play event listeners


$("#jpId").bind($.jPlayer.event.error + ".myProject", function(event) { // Using ".myProject" namespace
  alert("Error Event: type = " + event.jPlayer.error.type); // The actual error code string. Eg., "e_url" for $.jPlayer.error.URL error.
  switch(event.jPlayer.error.type) {
    case $.jPlayer.error.URL:
      reportBrokenMedia(event.jPlayer.error); // A function you might create to report the broken link to a server log.
      getNextMedia(); // A function you might create to move on to the next media item when an error occurs.
      break;
    case $.jPlayer.error.NO_SOLUTION:
      // Do something
      break;
  }
});

$("#jpId").unbind(".myProject"); { // Remove ".myProject" namespace event listeners using standard jQuery method

jPlayer Functions

$.jPlayer.pause() : Void

Description

Pauses all instances of jPlayer on the current page. If using frames, then only the the frame the command is issued in is affected.

Parameters

This method has no parameters.

Code Examples:

$.jPlayer.pause(); // Pause all instances of jPlayer on the page

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

Description

This function is used to convert a time, in seconds, to a string formatted in hours, minutes and seconds. The format of the conversion is defined using the object $.jPlayer.timeFormat.

This function is used to format the text jPlayer writes to the css selectors for currentTime and duration.

Parameters

seconds: Number : The number of seconds to convert.

Returns

String : The formatted time.

Code Examples:

$("#myTime").text($.jPlayer.convertTime(60)); // One minute

jPlayer Objects

$.jPlayer.timeFormat : Object

Description

This object is used to format the time returned by the function:
$.jPlayer.convertTime( seconds )

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 minute if less than 10.
padSec: Boolean : (Default: true) : Zero pads the second if less than 10.
sepHour: String : (Default: ":") : String between hour and minute.
sepMin: String : (Default: ":") : String between minute and second.
sepSec: String : (Default: "") : String after second.

Code Example:

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

The following objects have been added in jPlayer development patches (available on GitHub) and are not available in jPlayer 2.0.0.

$.jPlayer.platform : Object

Description

The platform object was added in jPlayer development patch 2.0.14 notes.

This object is the result of a user agent sniffer and gives information for mobile and tablet platforms.
When detected, the properties are true:

Properties

mobile: Boolean : True when a smart phone is detected.
tablet: Boolean : True when a tablet device is detected.
ipad iphone ipod android blackberry playbook webos windows ce

webos and windows ce require testing on actual devices.
The "windows ce" property will probably be changed to windows_ce to enable dot notation.

Code Example:

if($.jPlayer.platform.tablet) {
	// Do something for all tablet devices
	if($.jPlayer.platform.ipad) {
	   // Do something on ipad devices
	}
	if($.jPlayer.platform.android) {
	   // Do something on android tablet devices
	}
}

jPlayer's Predefined CSS Selectors

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

To define custom CSS selectors use the constructor options:
jPlayer({cssSelectorAncestor: "#my-unique-id", cssSelector: {...}})

To change CSS selectors after instancing, use jPlayer("option", key, value):
jPlayer("option", "cssSelector", method, selector)
jPlayer("option", "cssSelectorAncestor", selector)

Default cssSelectorAncestor

cssSelectorAncestor : "#jp_interface_1"

Note that the cssSelectorAncestor option's default value was changed to "#jp_container_1" in jPlayer development patch 2.0.3 notes and details.

Default cssSelector

cssSelector : {
play : ".jp-play"
pause : ".jp-pause"
stop : ".jp-stop"
videoPlay : ".jp-video-play"
seekBar : ".jp-seek-bar"
playBar : ".jp-play-bar"
mute : ".jp-mute"
unmute : ".jp-unmute"
volumeBar : ".jp-volume-bar"
volumeBarValue : ".jp-volume-bar-value"
currentTime : ".jp-current-time"
duration : ".jp-duration"
restoreScreen : ".jp-restore-screen" Added in jPlayer development patch 2.0.3 notes
fullScreen : ".jp-full-screen" Added in jPlayer development patch 2.0.3 notes }

Actual CSS Selector String Coding

selector = cssSelectorAncestor + " " + cssSelector[method];

For example, the play method's default actual selector is: "#jp_interface_1 .jp-play"
In English, this means select the entity with class jp-play who has an ancestor with the id jp_interface_1.

Remember that ids are unique, while classes are common. An id is only ever used once.

jPlayer Graphical Skins

This section will be updated early 2011.

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 cssSelectors 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: Video Single

As used by this demo.

View the demo source... Will update this doc early 2011.

Standard skin structure: Audio Single

As used by this demo.

View the demo source... Will update this doc early 2011.

Standard skin structure: Video and Audio Playlist

As used by this demo.

View the demo source... Will update this doc early 2011.

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.

There is an anim GIF and a PNG file too in the skin folder for the latest 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.2

Browser

Compatibility verified with:

Firefox 3.6 (Win, OSX) †
Firefox 4 Beta (Win)
Safari 5 (Win, OSX) †
Mobile Safari (iOS 4.2: iPad / iPhone / iPod Touch) †
- iPhone / iPod Touch: Video plays in the QuickTime plugin.
- Play and load bar progress do not work well when using multiple instances of jPlayer. This browser enables one media element at a time, so playing 2 instances together is not possible.
Chrome 8 (Win, OSX) †
Opera 10.63 (Win, OSX) †
Internet Explorer 9 Beta (Win)
- The Flash is disabled in jPlayer by default due to bugs with Flash's ExternalInterface in this browser.
- The jPlayer("clearMedia") method resets the instance, but does not cancel the download due to a bug in media.load() throwing an exception on broken links... And then some time later raising an error event. The reset uses src="", which is a broken link, but IE9 seems to treat the impossible src="" as a possible url and tries to load the corrent into the media element, rather than rasing an error event immediately like every other browser does. The late error event would corrupt jPlayer, hence the media.load() is disabled when this browser is detected.
Internet Explorer 8 (Win)
Internet Explorer 7 (Win)
Internet Explorer 6 (Win)

† Tested using the latest browser release as of 17th December 2010.

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 gestures to trigger commands that effect media playback.

Mobile Safari
- The first time a media element is played must be initiated by a user gester. ie., The user must click the play button. This affects the operation of a jPlayer("play") in the ready event handler. The browser will ignore the command. jPlayer will simply wait until the user presses the play button.
  Once the first gesture has been received, JavaScript code is then allowed to do whatever you want with the media element. Note that a jPlayer media player instance uses a audio and a video element. Each require their own gesture.
  Also affect: jPlayer("load") and jPlayer("pause", time)

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.

This problem does not appear to affect jPlayer 2.0.0. We believe that the Firebug add-on has been fixed as this no longer affects Firefox 4 with the up to date Firebug add-on.

Reference: HTML5 Browser Audio and Video Support

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

Format names relate to the supplied and setMedia format property names used by jPlayer. For example: WEBMA is an audio WebM, OGV is a video OGG, and M4A is an audio MP4. For more details on the formats, see Media Encoding.

HTML5 Audio Format

An audio WebM file uses the same Vorbis codec as an OGG file.

HTML5 browsers and their supported audio file formats:

Firefox (OSX, Win): WEBMA, OGA
Safari (OSX, Win): MP3, M4A
Mobile Safari iOS4 (iPad, iPhone, iPod): MP3, M4A
Opera (OSX, Win): WEBMA, OGA
Chrome (OSX, Win): WEBMA, OGA, MP3, M4A
IE9 (Win): MP3, M4A (Can install the WebM codec.)

HTML5 Video Format

The video WebM (VP8) codec is superior to the video OGG (Theora) codec.

HTML5 browsers and their supported video file formats:

Firefox (OSX, Win): WEBMV, OGV
Safari (OSX, Win): M4V
Mobile Safari iOS4 (iPad, iPhone, iPod): M4V
Opera (OSX, Win): WEBMA, OGV
Chrome (OSX, Win): WEBMV, OGV, M4V. (Will drop support for M4V soon.)
IE9 (Win): M4V (Can install the WebM codec.)

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 (OSX, Win): OGA
Safari (OSX): MP3
Mobile Safari (iOS4 iPad/iPhone/iPod): MP3
Opera (OSX, Win): OGA
Chrome (OSX, Win): MP3, OGA
IE9 (Win): MP3

Audio streams fail on:

Safari (Win): MP3

External Resources

Some links to resources about HTML5 video and audio support:

diveintohtml5.org : Video on the Web.
html5test.com : HTML5 Test - Where you can test your browser's HTML5 support.
www.trygve-lie.com : HTML5 audio element and streaming

jPlayer 2.0.0 Developer Guide

Contents

Related Links

jPlayer Fundamentals

Essential jPlayer Media Formats

Setting the size of jPlayer

Flash Security Rules

Media Encoding

Encoders:

References:

Server Response

MIME Type

Do Not GZIP the Media

Byte-Range Requests

Protecting Your Media

How to kill jPlayer with CSS or jQuery

jPlayer Files

Plugin Files

Source Files

jPlayer Constructor

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

Description

Parameters

options

Object Properties

Object Properties

jPlayer Methods

$(id).jPlayer( "setMedia", Object: media ) : jQuery

Description

Parameters

media

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

Description

Parameters

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

Description

Parameters

$(id).jPlayer( "play", [Number: time] ) : jQuery

Description

Parameters

$(id).jPlayer( "pause", [Number: time] ) : jQuery

Description

Parameters

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

Description

Parameters

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

Description

Parameters

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

Description

Parameters

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

Description

Parameters

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

Description

Parameters

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

Description

Parameters

$(id).jPlayer( "option", [String: key, [Variable: value]] ) : Variable

Description

Parameters

Events

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

Description

Parameters

jPlayer Options

$(id).jPlayer( "option", "cssSelector", String: method, String: selector ) : jQuery

Description

Parameters

Events

$(id).jPlayer( "option", "cssSelectorAncestor", String: selector ) : jQuery

Description

Parameters

Events

jPlayer Events

jPlayer Event Types

jPlayer Event Object