jquery.tube.js

Play YouTube Videos with jQuery

jquery.tube.js is a jQuery plugin to access YouTube's player and data APIs transparently. The basic approach is centered around 'tube' objects: a tube is an abstract container filled with videos based on a YouTube playlist, user's feed or a search query; a tube offers the basic control and event handling interfaces you would expect from a playlist (play, pause, next, etc.) and is associated with a player instance. A player is a thin wrapper around YouTube's iFrame or (if window.pushMessage is unavailable) JavaScript player API; thus, the player is intended to work transparently on legacy browsers (IE7) and HTML5 capable devices without Flash support.

This plugin contains no stylesheets; tube instances create simple HTML lists of their contents (the structure can be adjusted for each instance through a simple template system).

Installation

Simply grab jquery.tube.js or jquery.tube.min.js from the project's root directory. For bower users simply run:

$ bower install jquery.tube

Or add "jquery.tube" as a dependency to your component.json file.

Documentation

If all you want to do is play a video, you can create a new player instance with a YouTube video ID:

$('#player-container').player({
  video: 'ylLzyHk54Z0',
  width: 500
});

You can pass more options to set up event handlers or specific YouTube configuration options; you can retrieve the player object using jQuery's data method, like this:

$('#player-container').data('player');

Additionally, the player object is exposed as 'this' to every event handler you register. To gain access to the original YouTube player object use the property 'p' of the player object. To illustrate this, the following example prints the current time to the console twice a second while the video is playing.

function onPlay(event) {
 var player = this;

 timeout = setInterval(function () {
   console.log(player.p.getCurrentTime());
 }, 500);
}

function onPause(event) {
  clearInterval(timeout);
}

$('#player-container').player({
  video: 'ylLzyHk54Z0'
  events: {
    play: onPlay,
    pause: onPause,
    end: onPause
  }
});

You can register event handlers for these events:

unstarted
play
pause
end
buffer
cue

More interesting than the player object, however, are tube objects. A tube is basically a bunch of videos based on either a user's feed, a specific playlist, or a search query on YouTube. For example:

$('#playlist-container-1').tube({
  player: 'player-container',
  query: 'Alan Turing',
  limit: 4
});

This will display four videos about Alan Turing in the 'playlist-container-1'; if you click on any of the videos the video will start playing in a new player instance created inside the 'player-container'.

Next, you could add a second playlist whose videos will play back in the same player instance:

$('#playlist-container-2').tube({
  player: 'player-container',
  user: 'GoogleDevelopers',
  limit: 4
});

This will add the latest two videos uploaded by the user GoogleDevelopers. In this way you can add multiple playlists that share a single video player.

You can also create arbitrary playlists on the fly by passing a list of YouTube IDs. The next example will reuse the same player again:

$('#playlist-container-3').tube({
  player: 'player-container',
  list: ['sOEAD-gfJ_M', 'u1zgFlCw8Aw']
});

As you can see the tube plugin generates simple playlists that are easy to style with custom CSS. If you want to adapt the HTML of the generated tubes, you can do so by defining it in a template configuration that you pass to the tube function. The default configuration looks like this:

templates = {
  thumbnail: '<img src="{url}" title="{title}" />',
  title: '<h1>{title} ({duration})</h1>',
  author: '<a href="{author_url}">{author}</a>',
  description: '<p>{description}</p>',
  statistics: '<span class="statistics">{views} / {favorites} / {uploaded}</span>',
  video: '<a href="#{id}" rel="{index}">{title}{thumbnail}{description}<p>{author} – {statistics}</p></a>'
};

For more examples, consult the examples in the demo and test directories.

Configuration

For the default configuration of the player and tube plugins you can take a look at '$.tube.defaults' and '$.player.defaults':

$.tube.defaults = {
  player: 'player',
  autoload: false, // load the player automatically?
  autoplay: false,
  start: 0, // start video at offset
  order: 'relevance', // 'published', 'rating', 'viewCount'
  author: false,
  hide: 2, // 0 = always visible, 1 = hide progress bar and controls, 2 = hide progress bar
  controls: 1,
  version: 2,
  format: 5,
  limit: 10,
  key: false,
  render: true,
  truncate: false,
  at: '\n', // pattern (truncate)
  max: 140, // max length (truncate)
  omission: '…', // omission string (truncate)
  load: false, // plugin callback when the playlist data has been loaded
  complete: false, // plugin callback when the playlist html has been rendered
  click: false // plugin callback
};

$.player.defaults = {
  id: 'player',
   width: 640,
   height: 390,
   wmode: 'opaque'
};

Development

This plugin uses the awesome mocha framework for testing; in order to run the tests you need to install a few libraries through npm:

$ npm install
$ npm test

If you customize any of Tube's components, you can build a new version of the plugin as follows:

$ bundle install
$ rake build minify

License

(The MIT License)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.