Installation and usage

Installation:

You will need to load a jQuery UI CSS theme as well as the player specific css into the head of the document:

<link type="text/css" rel="stylesheet" media="screen, projection" href="http://ajax.googleapis.com/ajax/libs/jqueryui/1.8/themes/black-tie/jquery-ui.css" />
<link type="text/css" rel="stylesheet" media="screen, projection" href="css/youtube-player.css" />

Then load dependancy scripts and the plugin itself.

<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js"></script>
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/swfobject/2.2/swfobject.js"></script>
<script type="text/javascript" src="js/jquery.youtube.player.js"></script>

Insert the required player HTML into your document:

<div class="player">
        <div class="youtube-player-video">
                <div class="youtube-player-object">
                        You need Flash player 8+ and JavaScript enabled.
                </div>  
        </div>  
</div>

Usage

The following code is used to instantiate a new player instance with a set of options. There are many options available allowing you to change/extend the default behavior of the plugin. (See below for list of config options.)

<script type="text/javascript">

        var config =  {
                playlist: {
                        playlist: '71B8152559FA2805'
                }
        };

        $(".player").player(config)
</script>

h2 Setting the playlist

The plugin accepts 3 types of playlists:

Custom playlist (you define the tracks by youtube video id’s)
Youtube playlist (uses youtube playlist id)
Youtube latest videos by user (uses a youtube username)

<script type="text/javascript">

        // Custom playlist
        var config1 =  {
                playlist: {
                        title: 'Random videos',
                        videos: [
                                { id: 'wDowSzVgjXI', title: 'The All Seeing I - Beat Goes On HQ' },
                                { id: 'hPzNl6NKAG0', title: 'Maru the cat' }
                        ]
                }
        };

        // Youtube playlist
        var config2 =  {
                playlist: {
                        playlist: 'playlistID'
                }
        };

        // Latest user videos
        var config3 =  {
                playlist: {
                        user: 'YoutubeUserName'
                }
        };

        $(".player").player(config1)
</script>

Public methods

An event API is available for you to use. The following code demonstrates how to use the public event API:

<script type="text/javascript">

        var config =  {
                playlist: {
                        playlist: '71B8152559FA2805'
                }
        };

        var player = $("#player").player(config);

        player.player('fullscreen');

        player.player('randomVideo');

        // etc
</script>

All but one API method will return the jQuery object, allowing you to keep the default jQuery chaining functionality. This is a bit of a problem if you are trying to get the return value of a method, so you’ll need to do it a different way. There is an API method called ‘plugin’ which will return the player object instance, which you can then control to your liking. The following demonstrates this:

<script type="text/javascript">

        var config =  {
                playlist: {
                        title: 'Random videos',
                        videos: [ { id: 'Kv6Ewqx3PMs', title: 'Mr. Oizo Flat Beat' } ]
                }
        };

        var player = $('.youtube-player').player(config);
        
        var playerObject = player.player('plugin');

        var playerState = playerObject.state();

        // etc
        // console.debug(playerObject);
</script>

Events:

loadPlaylist(playlist, play, show, successCallback)
loadVideo(video, cue) // ‘video’ argument is an object literal with ‘id’ and ‘title’ attributes. ‘cue’ argument is for cueing the video to playlist
pauseVideo
shufflePlaylist()
muteVideo()
repeat()
playVideo()
cueVideo(videoID)
randomVideo()
prevVideo()
nextVideo()
destroy()

View an example of how to use the public methods.

The plugin will execute callback events if they exist in the config object:

<script type="text/javascript">

        var config =  {
                playlist: {
                        playlist: '71B8152559FA2805'
                },
                onReady: function(){
                        
                        console.debug('The player has been constructed and is ready to be used.');
                }
        };

        $(".player").player(config);
</script>

Event callbacks

var eventCallbacks = {
        onReady: function(){},  // after player and toolbar have been constructed and animated, and after first video has been cued
        onPlayerReady: function(){},  // after flash player has been constructed and ready to use, before loading any video
        onVideoPlay: function(video){}, // when video is playing
        onVideoPaused: function(video){}, // when video is paused
        onBuffer: function(video){}, // when video starts buffers
        onError: function(errorMsg){} ,  // error loading a video
        onBeforePlaylistLoaded: function(){},  // before the playlist has started loading (ajax event)
        onAfterPlaylistLoaded: function(){},  // after the playlist has finished loading (ajax event) (will execute on error)
        onVideoLoad: function(videoID){},  // when a video is loaded into the player, regardless if successful or not
        onVideoCue: function(videoID){},   // after a video has been cued 
       onYoutubeStateChange: function(stateID){} // youtube event handler event
};

View an example of how to use the events.

Options

var defaultConfig = {
        width: 425,                     // player width (integer or string)
        height: 356,                    // player height (integer or string)
        swfobject: window.swfobject,    // swfobject object
        playlist: {},                   // playlist object (object literal)
        showPlaylist: 1,                // show playlist on plugin init (boolean)
        showTime: 1,                    // show current time and duration in toolbar (boolean)
        showTitleOverlay: 1,            // show video title overlay text (boolean)
        videoThumbs: 0,                 // show videos as thumbnails in the playlist area (boolean) (experimental)
        randomStart: 0,                 // show random video on plugin init (boolean)
        autoStart: 0,                   // auto play the video after the player as been built (boolean)
        autoPlay: 0,                    // auto play the video when loading it via the playlist or toolbar controls (boolean)
        repeat: 1,                      // repeat videos (boolean)
        repeatPlaylist: 0,              // repeat the playlist (boolean) 
        shuffle: 0,                     // shuffle the play list (boolean)
        chromeless: 1,                  // chromeless player (boolean)
        updateHash: 0,                  // update the location hash on video play (boolean)
        highDef: 0,                     // high definition quality or normal quality (boolean)
        playlistHeight: 5,              // height of the playlist (integer) (N * playlist item height)
        playlistBuilder: null,          // custom playlist builder function (null or function) see http://github.com/badsyntax/jquery-youtube-player/wiki/Installation-and-usage
        playlistBuilderClickHandler: null, // custom playlist video click event handler, useful if you want to prevent default click event (null or function)
        playlistSpeed: 550,             // speed of playlist show/hide animate
        toolbarAppendTo: null,          // element to append the toolbar to (selector or null)
        playlistAppendTo: null,         // element to append the playlist to (selector or null)
        timeAppendTo: null,             // elemend to append to time to (selector or null)
        videoParams: {                  // video <object> params (object literal)
                allowfullscreen: 'true', 
                allowScriptAccess: 'always',
                wmode:  'transparent'
        },      
        showToolbar: 1,                 // show or hide the custom toolbar (boolean)
        toolbarButtons: {},             // custom toolbar buttons
        toolbar: 'play,prev,next,shuffle,repeat,mute,playlistToggle' // comma separated list of toolbar buttons
};

Custom playlist area

You can use the playlistBuilder() method to build your own custom playlist area. The function needs to return an object literal containing a jQuery container object (the playlist container), and a jQuery result set (the playlist videos).
For example

var playerConfig = {

        playlistBuilder: function(videos){

                return {
                        container: $('.my-playlist-container'),
                        items: $('.my-playlist-container li')
                };
        }
};

The ‘videos’ variable argument is an array of video objects. You use this array to build your playlist. You need to attach the video objects to the HTML elements using the data key ‘video’ in order for this to work.
For example:

var playerConfig = {

        playlistBuilder: function(videos){

                var list = $('<ul></ul>');
                
                $.each(videos, function(key, video){

                        $('<li></li>')
                                .data('video', this) // NB: this is required
                                .html('<img src="http://img.youtube.com/vi/' + this.id + '/2.jpg" alt="' + this.title + '" />')
                                .appendTo( list );
                });

                return {
                        container: list,
                        items: list.find('li')
                };
        }
};

View an example of using the playlist builder.

Toolbar customization

You can specify which buttons to display by pssing in a comma seprated list of button names. The following lists all the availalble buttons:

var config = {
        toolbar: 'play,pause,prev,next,shuffle,repeat,mute,playlistToggle' 
};

Custom toolbar buttons

You can add or override toolbar buttons by passing in an object literal set of buttons, using the ‘toolbarButtons’ option.
For example:

var config =  {

        toolbarButtons: { 
        
                // if you name a button used by the player, your button will be used,
                // allowing you to override the default buttons

                play: {
                        text: 'Play',
                        icon: 'ui-icon-play',
                        action: function(){

                                alert('This is a custom button action');

                                // 'this' is the player object
                                // console.debug(this) to get list of methods to use

                                this.playVideo();
                        }
                },
                
                // custom buttons need to have a unique name, and remember to 
                // add this name to the toolbar button list

                customButton: {
                        text: 'Power',
                        icon: 'ui-icon-power',
                        action: function(){
                
                                alert('Power off!');
                        }
                }       
        },

        toolbar: 'play,customButton',

        playlist: {
                playlist: '71B8152559FA2805'
        }
};

$('.youtube-player').player(config);

View an example of using custom toolbar buttons.

Example setup

View an example html file
View all examples

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!