The jPlayer constructor is applied to the given jQuery selector (normally an ID css 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.
Event handlers that may be created through the jPlayer constructor options, are not really options. They are event handlers bound to the jPlayer element, with the ".jPlayer" jQuery event namespace, and are included in the options as an easy way to bind a handler to an event. Event handlers that are listed here in the options are indicated by the ? symbol.
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.
- 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.
The swfPath option may be a path or a URL to the SWF file with extension .swf. For example, jPlayer({swfPath:"/scripts/banana.swf"}) where you renamed the Jplayer.swf file to "banana.swf". Do not rename the .swf extension, or a path will be assumed.
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.
- 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: webma, webmv, oga, ogv, wav, fla, flv.
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.
- size ?
-
object : Sets the size of the restored screen mode. The defaults depend on whether audio or video formats are supplied. The video defaults are used when both media types are supplied.
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. The defaults depend on whether audio or video formats are supplied. The video defaults are used when both media types are supplied.
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.
- 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.
- autohide ?
-
object : Sets the auto-hide options for the GUI in the screen display states.
Object Properties:
- restored
- Boolean : (Default: false) : Auto-hide the GUI when in the restored screen display state.
- full
- Boolean : (Default: true) : Auto-hide the GUI when in the full screen display state.
- fadeIn
- Number : (Default: 200) : The period of the fadeIn animation in milliseconds.
- fadeOut
- Number : (Default: 600) : The period of the fadeOut animation in milliseconds.
- hold
- Number : (Default: 1000) : The period of the pause before autohide begins in milliseconds.
- 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.
- muted ?
-
Boolean : (Default: false) : Defines the initial muted state.
- verticalVolume
-
Boolean : (Default: false) : By default, clicks on the volume bar are calculated from the left. Setting this option to true, causes the calculation to be from the bottom.
If this option is used, then the following CSS styles are required on the volume bar elements to make them display vertically:
- <style>
- .jp-volume-bar {
- position:relative;
- }
- .jp-volume-bar-value {
- position:absolute;
- bottom: 0;
- }
- </style>
- 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_container_1") : Defines the cssSelector of an ancestor of all cssSelectors. Usually an id selector, which is the outer divider wrapper of the skin HTML.
- 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.
- 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.
- wmode
-
String : (Default: "opaque") : Allows the wmode of the Flash fallback to be set.
Valid wmode values: window, transparent, opaque, direct, gpu
Note that audio players in Firefox 3.6 using the Flash solution will require that the {wmode:"window"} option is set. Otherwise, the browser does not put the Flash in the page properly. This problem does not effect Firefox 4+, nor does it affect video players in Firefox 3.6.
For example, if you used the option setting {supplied:"mp3"}, then you must set the {wmode:"window"} option to ensure Firefox 3.6 instances the Flash solution correctly.
For example, if you used the option setting {solution:"flash,html"}, then you must set the {wmode:"window"} option to ensure Firefox 3.6 instances the Flash solution correctly.
For example, if you used the option setting {supplied:"mp3,oga"}, then the wmode option does not matter, as the HTML solution will be used to play the OGA format in Firefox 3.6.
This problem will be addressed in the future, where supplying only audio formats will change the default wmode value to "window".
- loop ?
-
Boolean : (Default: false) : Sets the initial loop state.
The loop option works in tandem with the default repeat event handler. Clicks on the GUI repeat/repeat-off buttons, toggles the loop option and then generates a repeat event.
- repeat ?
-
Function : (Default: event handler) : Handler function for the repeat event.
The default repeat event handler works in tandem with the loop option. Clicks on the GUI repeat/repeat-off buttons, toggles the loop option and then generates a repeat event.
Unlike other events, the repeat event has a default handler. The default handler is shown below:
- repeat: function(event) {
- if(event.jPlayer.options.loop) {
- $(this).unbind(".jPlayerRepeat").bind($.jPlayer.event.ended + ".jPlayer.jPlayerRepeat", function() {
- $(this).jPlayer("play");
- });
- } else {
- $(this).unbind(".jPlayerRepeat");
- }
- }
To change the repeat event handler after instancing jPlayer, unbind the handler and then bind a new handler to the event. Note that the jPlayer namespace is used to only unbind the repeat handler added by jPlayer.
- $("#my-jplayer").unbind($.jPlayer.event.repeat + ".jPlayer");
- $("#my-jplayer").bind($.jPlayer.event.repeat + ".jPlayer", function() {
- // Your new repeat handler code
- });
Remember that you may need to clean up the old handler's actions too. There may still be that ended event handler that the repeat handler generates.
- $("#my-jplayer").unbind(".jPlayerRepeat");
The author cannot think of an example where you would want to change the repeat handler after instancing jPlayer, but it has been documented here just in case.
- 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.
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 {
- // Enable and use the HTML bridge with the Flash fallback
- $(this).jPlayer("option","emulateHtml",true);
- p = Popcorn('#' + $(this).attr("id"));
- }
- }
- nativeVideoControls ?
-
Object : Defines the user agent blocklist, which contains regular expressions, which cause the native controls to be used if a match is found.
Native video controls are disabled when audio media is supplied and jPlayer({noFullScreen}) is set if nativeVideoControls found a matched.
The default object is empty:
- nativeVideoControls: {
- // Works well on standard browsers.
- // Phone and tablet browsers can have problems with the controls disappearing.
- }
- noFullScreen ?
-
Object : Defines the user agent blocklist, which contains regular expressions, which cause the full-screen and restore-screen buttons to be hidden if a match is found.
The default object is:
- noFullScreen: {
- msie: /msie [0-6]/,
- ipad: /ipad.*?os [0-4]/,
- iphone: /iphone/,
- ipod: /ipod/,
- android_pad: /android [0-3](?!.*?mobile)/,
- android_phone: /android.*?mobile/,
- blackberry: /blackberry/,
- windows_ce: /windows ce/,
- webos: /webos/
- }
- noVolume ?
-
Object : Defines the user agent blocklist, which contains regular expressions, which cause the volume controls to be hidden if a match is found.
The default object is:
- noVolume: {
- ipad: /ipad/,
- iphone: /iphone/,
- ipod: /ipod/,
- android_pad: /android(?!.*?mobile)/,
- android_phone: /android.*?mobile/,
- blackberry: /blackberry/,
- windows_ce: /windows ce/,
- webos: /webos/,
- playbook: /playbook/
- }
- 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.
- warningAlerts
-
Boolean : (Default: false) : Enables warning reporting through alerts. Warnings are useful for the developer and will inform you of css selectors that are not found, and some other warning types. Often warnings can be ignored, such as the videoPlay selector not being found with an audio player.
Enable this option to help debug your jPlayer application.
- 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 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.
jPlayer Methods
jPlayer is controlled by sending the method name through the $(id).jPlayer() plugin method.
Methods that are an option alias
Methods that are a shortcut/alias to change options using the jPlayer("option", key, value) method, are indicated by the ? symbol.
$(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 video and audio 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 supplied that can work in the solution, will work, be that video or audio.
The point at which jPlayer begins downloading the media is complicated by changes in the by changes in the W3C HTML5 media spec for the media.load() method and the media.src property. In order for older HTML5 browsers to work with jPlayer, the media.load() command is still used, where really it should be removed as it is no longer required.
The jPlayer constructor option jPlayer({preload) is used to control when jPlayer begins downloading new media. Some browsers will begin the download for the whole media when the preload option is "metadata". Others will require that "auto" is used. The only way to ensure download does not begin automatically is to use the preload option "none". Remember that, 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. The the download may not be cancelled as it depends on whether the browser follows the recent W3C HTML media spec. In practice, except for the first time setMedia is used in the ready event, the setMedia command is followed by a play command which stops the old download. The exception is with the media player, where the old media of different type (audio or video), will continue downloading. 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.
The URLs given must conform to standard URL Encoding Rules.
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 mp4 audio format (MP4: AAC)
- m4v
- String : Defines the URL of the mp4 video format (MP4: H.264/AAC)
- webma
- String : Defines the URL of the webm audio format (WebM: Vorbis)
- webmv
- String : Defines the URL of the webm video format (WebM: VP8/Vorbis)
- oga
- String : Defines the URL of the ogg audio format (OGG: Vorbis)
- ogv
- String : Defines the URL of the ogg video format (OGG: Theora/Vorbis)
- fla
- String : Defines the URL of the flv audio format (FLV: Flash)
- flv
- String : Defines the URL of the flv video format (FLV: Flash)
- wav
- String : Defines the URL of the wav audio format
- poster
- String : Defines the URL of the poster image.
The poster image should have the same aspect ratio as the jPlayer size, or the image will be distorted when it is resized to fit the area.
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 in video player if it is open at the time the command executes.
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.
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.
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 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( "option", [String: key, [Mixed: value]] ) : Mixed
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.
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 element.
All event handlers with the .jPlayer namespace are removed by this method.
Parameters
This method has no parameters.
Code Examples:
- $("#jpId").jPlayer("destroy");
$(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}:ratio). The volume can be changed through the option method: jPlayer({option}, "volume", ratio).
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", [Boolean:mute] ) : jQuery ?
Description
This method mutes the media's sounds. Note that the initial muted state is set through the constructor option: jPlayer({muted}:Boolean). The mute state can be changed through the option method: jPlayer({option}, "muted", Boolean).
Parameters
- mute
-
Boolean : (Default: true) : The muted state.
Code Examples:
- $("#jpId").jPlayer("mute");
$(id).jPlayer( "unmute", [Boolean: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}) The mute state can be changed through the option method: jPlayer({option}, "muted", Boolean).
Parameters
- unmute
-
Boolean : (Default: true) : The oposite of the muted state.
Code Examples:
- $("#jpId").jPlayer("unmute");
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 cssSelectorAncestor
Usually an id selector. Eg., "#jp_container_1"
Events
- $.jPlayer.event.warning
-
- Event Codes
- $.jPlayer.warning.CSS_SELECTOR_COUNT
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 * ? Occurs when jPlayer is ready to receive commands.
- $.jPlayer.event.flashreset * ? Occurs when the Flash solution generates another ready event.
- $.jPlayer.event.resize * ? Occurs when the screen state changes and when the size/sizeFull options are changed.
- $.jPlayer.event.repeat * ? Occurs when the loop state is changed and before the ready event.
- $.jPlayer.event.click * ? Occurs when the user clicks on the poster or video. NB: The GUI skin can interfere with this.
- $.jPlayer.event.error * ?
- $.jPlayer.event.warning * ?
- $.jPlayer.event.loadstart *
- $.jPlayer.event.progress * Occurs while the media is being downloaded.
- $.jPlayer.event.suspend
- $.jPlayer.event.abort
- $.jPlayer.event.emptied
- $.jPlayer.event.stalled
- $.jPlayer.event.play * Occurs when the media is played.
- $.jPlayer.event.pause * Occurs when the media is paused.
- $.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 * Occurs when the currentTime is changed. (~250ms between events during playback.)
- $.jPlayer.event.ended * Occurs when the media ends.
- $.jPlayer.event.ratechange
- $.jPlayer.event.durationchange
- $.jPlayer.event.volumechange * Occurs when volume or muted change.
- * A jPlayer event supported by both the Flash fallback 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.options
- Object : The jPlayer options
- event.jPlayer.status
- Object
- event.jPlayer.status.src
- String : The URL being used by jPlayer.
- event.jPlayer.status.media
- 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.FLASH_DISABLED
- A ready event was registered from the Flash, but commands are no longer working. The Flash has been disabled by the browser because it, or a parent, has been hidden using
display:none
- $.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. (Not exactly true... The HTML error event can occur due to decoding errors too.)
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') or 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";
$.jPlayer.platform : Object
Description
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
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_container_1"
Default cssSelector
method: "selector"
- cssSelector: {
- videoPlay: ".jp-video-play",
- play: ".jp-play",
- pause: ".jp-pause",
- stop: ".jp-stop",
- seekBar: ".jp-seek-bar",
- playBar: ".jp-play-bar",
- mute: ".jp-mute",
- unmute: ".jp-unmute",
- volumeBar: ".jp-volume-bar",
- volumeBarValue: ".jp-volume-bar-value",
- volumeMax: ".jp-volume-max",
- currentTime: ".jp-current-time",
- duration: ".jp-duration",
- fullScreen: ".jp-full-screen",
- restoreScreen: ".jp-restore-screen",
- repeat: ".jp-repeat",
- repeatOff: ".jp-repeat-off",
- gui: ".jp-gui",
- noSolution: ".jp-no-solution"
- }
Actual CSS Selector String Coding
selector = cssSelectorAncestor + " " + cssSelector[method];
For example, the play method's default actual selector is: "#jp_container_1 .jp-play"
In English, this means select the entity with class jp-play that has an ancestor with the id jp_container_1.
Remember that ids are unique, while classes are common. An id should only ever be used once in the HTML.
jPlayer Graphical Skins
The HTML and CSS/Artwork varies from skin to skin. The CSS/Artwork is a designed to work with all of that skin's HTML structures. You should get the HTML structure from the demo ZIP, available on the download page. The PSD files are also available for each 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:
External Resources
Some links to resources about HTML5 video and audio support:
