Demo : The jPlayerPlaylist Object

The jPlayer Playlist Add-on (jPlayerPlaylist)

This page contains a demo of and documentation for the new jPlayer Playlist add-on, jPlayerPlaylist and is intended to complement other playlist demos. jPlayerPlaylist requires jPlayer and jQuery.

The demonstration

Use the commands below the media player type instance of jPlayer to change the playlist, add tracks and change options. Details of the options and methods are given further down on this page. The commands here are pseudo-code to save space.
For example, add({Tempered Song}) is the command:

myPlaylist.add({
  title:"Tempered Song",
  artist:"Miaow",
  mp3:"http://www.jplayer.org/audio/mp3/Miaow-01-Tempered-song.mp3",
  oga:"http://www.jplayer.org/audio/ogg/Miaow-01-Tempered-song.ogg",
  poster: "http://www.jplayer.org/audio/poster/Miaow_640x360.png"
});

Update Required To play the media you will need to either update your browser to a recent version or update your Flash plugin.

setPlaylist( [Audio Mix] | [Video Mix] | [Media Mix] )
Miaow audio: add( {Bubble} | {Hidden} | {Tempered Song} | {Lentement} )
The Stark Palace audio: add( {Cro Magnon Man} | {Your Face} | {Cyber Sonnet} )
Various video: add( {Big Buck Bunny} | {Incredibles} | {Finding Nemo} )
remove( -2 | -1 | 0 | 1 | 2 ) | shuffle( false | true )
select( -2 | -1 | 0 | 1 | 2 ) | next() | previous()
play( -2 | -1 | 0 | 1 | 2 ) | pause()
option( "autoPlay", false | true ) Default: false
option( "enableRemoveControls", false | true ) Default: false
option( "displayTime", 0 | 'fast' | 'slow' | 2000 ) Default: 'slow'
option( "addTime", 0 | 'fast' | 'slow' | 2000 ) Default: 'fast'
option( "removeTime", 0 | 'fast' | 'slow' | 2000 ) Default: 'fast'
option( "shuffleTime", 0 | 'fast' | 'slow' | 2000 ) Default: 'slow'

Equivalent Effect: add(Your Face, true) == add(Your Face) then play(-1)

Avoid code like: remove(2) then remove(3)
Because the second command will only work if the remove animation time, removeTime, is zero. Even then, it will look like it removes the 3rd and 5th items from the original playlist before both commands executed. This is because the remove(2) removes the 3rd item and then remove(3) removes the 4th item, which was the 5th item before the 3rd item was removed. To remove the 3rd and 4th items, you'd use remove(2) and then remove(2) again. The remove() method returns a true when successful, a false when ignored, which allows you to know whether it worked or not.

Media used in demo:
© 2009 The Stark Palace - sharkbatter.com
© 2003 Miaow / Arnaud Laflaquiere - MiaowMusic.net
© 2008 Blender Foundation - bigbuckbunny.org
© 2003-2004 Disney / Pixar - pixar.com

The constructor

The playlist in this demo is instanced with 1 item in it and uses the {supplied:"ogv,m4v,oga,mp3"} option to enable a media player that accepts audio and video.

var myPlaylist = new jPlayerPlaylist({
  jPlayer: "#jquery_jplayer_N",
  cssSelectorAncestor: "#jp_container_N"
}, [
  {
    title:"Cro Magnon Man",
    artist:"The Stark Palace",
    mp3:"http://www.jplayer.org/audio/mp3/TSP-01-Cro_magnon_man.mp3",
    oga:"http://www.jplayer.org/audio/ogg/TSP-01-Cro_magnon_man.ogg",
    poster: "http://www.jplayer.org/audio/poster/The_Stark_Palace_640x360.png"
  }
], {
  playlistOptions: {
    enableRemoveControls: true
  },
  swfPath: "/js",
  supplied: "ogv, m4v, oga, mp3",
  smoothPlayBar: true,
  keyEnabled: true,
  audioFullScreen: true // Allows the audio poster to go full screen via keyboard
});

The constructor might look scary to JavaScript newcomers, but it is really just 1 line of JavaScript, laid out in an easy to read manner. JSON (JavaScript Object Notation) is used in this demo to create the objects and arrays passed to the constructor. The parameters are an object, an array and an object:

// This is pseudo-code.
var myPlaylist = new jPlayerPlaylist({cssSelector}, [playlist], {options});

The parameters can be created outside the constructor to suit your goal. In particular, the options may be common to all your instances on a page. The playlist could be generated through an AJAX call to a JSON or XML url.

var cssSelector = { jPlayer: "#jquery_jplayer_N", cssSelectorAncestor: "#jp_container_N" };
var playlist = []; // Empty playlist
var options = { swfPath: "/js", supplied: "ogv, m4v, oga, mp3" };
var myPlaylist = new jPlayerPlaylist(cssSelector, playlist, options);

Defining the css selectors

The first parameter is an object used to define the css selectors that point at the jPlayer and container HTML elements. The jPlayer element is where the video output is displayed and the container, cssSelectorAncestor, is the outter divider of the player skin HTML.

To use the default values, use an empty object, {}. The defaults are:

{
  jPlayer: "#jquery_jplayer_1",
  cssSelectorAncestor: "#jp_container_1"
}

Defining the playlist content

The second parameter is an Array of Objects used to define the playlist. The object elements are used by the jPlayer setMedia command, so follow the rules for suppling the formats defined in the supplied option. The title, artist and free properties are used by jPlayerPlaylist to display each item. To start with an empty playlist, use an empty array, []. A playlist with a single audio item looks like:

[
  {
    title:"The Title",
    artist:"The Artist", // Optional
    free: Boolean, // Optional - Generates links to the media
    mp3:"MP3 URL", // Dependant on supplied option
    oga:"OGA URL", // Dependant on supplied option
    poster: "Poster URL" // Optional
  }
]

Defining the jPlayer and playlist options

The third parameter is an object to define the jPlayer options and jPlayerPlaylist options. This object is passed to jPlayer, and is used to setup the basic jPlayer options, such as solution, supplied and the all important swfPath. You can define all options, except for the cssSelectorAncestor and the repeat event handler, which are overridden by the jPlayerPlaylist code. Remember that event handlers are not really options. The playlist code binds event handlers to jPlayer events, such as ready and ended, which might interact with your event handlers in unexpected ways. Example options are:

{
  playlistOptions: {
    autoPlay: true,
    enableRemoveControls: true
  },
  swfPath: "/js",
  supplied: "mp3, oga"
}

Default playlist options:

playlistOptions: {
  autoPlay: false,
  loopOnPrevious: false,
  shuffleOnLoop: true,
  enableRemoveControls: false,
  displayTime: 'slow',
  addTime: 'fast',
  removeTime: 'fast',
  shuffleTime: 'slow'
}

Control flag descriptions:

autoPlay : Boolean : Will auto-play when instanced on the page, and when a new playlist is given using setPlaylist(). Remember that mobile devices require a gesture before anything will play. Recommend leaving this as false initially... And change it later if you want when changing the playlist through a user gesture. eg., They clicked on a link to change the playlist and your click handler changes autoPlay to true before you setPlaylist().
loopOnPrevious : Boolean : If loop is active, the playlist will loop back to the end when executing previous().
shuffleOnLoop : Boolean : If loop and shuffle are active, the playlist will shuffle when executing next() on the last item.
enableRemoveControls : Boolean : Displays the remove controls for each item.

Animation timing controls:

These options use jQuery animation timings, where the time is in milliseconds and also the strings 'slow' and 'fast' can be used. To make changes instant, set the time to zero, which removes the animation effect.

displayTime : Number/String : The period of the slide-up and slide-down animations when a new playlist is displayed.
addTime : Number/String : The period of the slide-down animation when a new item is added.
removeTime : Number/String : The period of the slide-up animation when a item is removed.
shuffleTime : Number/String : The period of the slide-up and slide-down animations when a playlist is shuffled.

jPlayerPlaylist methods:

setPlaylist(playlist:Array) : Void
Change the playlist. (See playlistOptions.autoPlay to cause it to play automatically.)

myPlaylist.setPlaylist([
  {
    title:"Cro Magnon Man",
    artist:"The Stark Palace",
    mp3:"http://www.jplayer.org/audio/mp3/TSP-01-Cro_magnon_man.mp3",
    oga:"http://www.jplayer.org/audio/ogg/TSP-01-Cro_magnon_man.ogg",
    poster: "http://www.jplayer.org/audio/poster/The_Stark_Palace_640x360.png"
  },
  {
    title:"Hidden",
    artist:"Miaow",
    free: true,
    mp3:"http://www.jplayer.org/audio/mp3/Miaow-02-Hidden.mp3",
    oga:"http://www.jplayer.org/audio/ogg/Miaow-02-Hidden.ogg",
    poster: "http://www.jplayer.org/audio/poster/Miaow_640x360.png"
  }
]);

add(media:Object, [playNow:Boolean]) : Void
Add a media item to the end of the playlist. Optional playNow param to start it playing after adding it.

myPlaylist.add({
  title:"Your Face",
  artist:"The Stark Palace",
  mp3:"http://www.jplayer.org/audio/mp3/TSP-05-Your_face.mp3",
  oga:"http://www.jplayer.org/audio/ogg/TSP-05-Your_face.ogg",
  poster: "http://www.jplayer.org/audio/poster/The_Stark_Palace_640x360.png"
});

remove([index:Number]) : Boolean
Removes the item from the playlist. Removes all items if no param is given. A positive index removes items from the start of the playlist while a negative index removes items from the end.

// Examples of usage:
myPlaylist.remove(); // Removes all items
myPlaylist.remove(0); // Removes the 1st item
myPlaylist.remove(1); // Removes the 2nd item
myPlaylist.remove(-1); // Removes the last item

if( myPlaylist.remove(0) ) {
  alert("1st item removed successfully!");
} else {
  alert("Failed to remove 1st item!"); // A remove operation is being animated.
}

select(index:Number) : Void
Selects the item in the playlist. A positive index selects items from the start of the playlist while a negative index selects items from the end.

// Examples of usage:
myPlaylist.select(0); // Selects the 1st item
myPlaylist.select(1); // Selects the 2nd item
myPlaylist.select(-1); // Selects the last item

play([index:Number]) : Void
Plays the item in the playlist. Plays the current item if no param is given. A positive index plays items from the start of the playlist while a negative index plays items from the end.

// Examples of usage:
myPlaylist.play(); // Plays the currently selected item
myPlaylist.play(0); // Plays the 1st item
myPlaylist.play(1); // Plays the 2nd item
myPlaylist.play(-1); // Plays the last item

shuffle([shuffled:Boolean], [playNow:Boolean]) : Void
Shuffle the playlist. Toggles shuffled setting if no param is given. True always shuffles the playlist. False will un-shuffle if it was shuffled. The playNow param will cause the first item to play automatically. (playNow can only be used if the first param is given. Use shuffle(undefined,true) to toggle and play.)

// Examples of usage:
myPlaylist.shuffle(); // Toggles shuffle state
myPlaylist.shuffle(true); // Shuffle the playlist
myPlaylist.shuffle(false); // Un-shuffle the playlist
myPlaylist.shuffle(true, true); //  Shuffle the playlist and plays

next() : Void
Move to and play the next item in the playlist. The behaviour for the last item depends on the loop state, the shuffle state and the playlistOptions.shuffleOnLoop option.

myPlaylist.next();

previous() : Void
Move to and play the previous item in the playlist. The behaviour for the first item depends on the loop state and the playlistOptions.loopOnPrevious option. (The playlist is never shuffled when looping back to the last item.)

myPlaylist.previous();

pause() : Void
Pause the current item.

myPlaylist.pause();

option(option:String, [value:Mixed]) : Void
Set or get the playlist option.

// Examples of usage:
var controls = myPlaylist.option("enableRemoveControls"); // Get option
myPlaylist.option("enableRemoveControls", true); // Set option

The HTML Structure

The playlist looks for the class jp-playlist within the cssSelectorAncestor element. A <ul> element is expected here, which is used to generate the item list.

<div id="jp_container_N">
  <div class="jp-playlist">
    <ul>
      <li></li> <!-- Empty <li> so your HTML conforms with the W3C spec -->
    </ul>
  </div>
</div>

The playlist is automatically added as <li> elements to the <ul> element. The jp-free-media span is only generated when the playlist item has its free property set.

<li>
  <div>
    <a class="jp-playlist-item-remove" href="javascript:;">&times;</a>
    <span class="jp-free-media">
      (<a tabindex="1" href="http://www.jplayer.org/audio/mp3/Miaow-02-Hidden.mp3" class="jp-playlist-item-free">mp3</a> )
    </span>
    <a tabindex="1" class="jp-playlist-item" href="javascript:;">Cro Magnon Man <span class="jp-artist">by The Stark Palace</span></a>
  </div>
</li>

The Techie Bit

The jPlayerPlaylist code is enclosed in a self-executing function that protects the jQuery variable within its scope, thus allowing the $ shortcut to be used within its code without conflicting with other JavaScript libraries. jPlayer does this too of course, which allows jQuery.noConflict() to be used.

The jPlayerPlaylist is an add-on to jPlayer. It is not a jQuery plugin, but a JavaScript object definition. You instance it like any other object, using the new operator.

jPlayerPlaylist is the only variable added to Javascript's global namespace.

When using jPlayerPlaylist with the animations and issuing comands from JavaScript, be aware that the animations take time to complete. Bombarding the playlist with many JavaScript commands may well give unexpected results unless you set all the animation timings to zero.

While this demo gives a poster image for all videos, in practice the video poster is only displayed if the Video item is first and autoPlay is false.