Overview

The jQuery TubePlayer Plugin was originally created in July 2010. The plugin is a jQuery wrapper around the YouTube Player API. It has evolved over time and is still the simplest interface to control and manage YouTube Player(s).

The plugin allows developers to focus on functionality as opposed to infrastructure around the YouTube player. The plugin exposes meaningful methods that are triggered based on state changes from the player API. The plugin also provides events that can be triggered on it allowing developers to create a customized player remote, programmatically control videos, gain access for analytics purposes and much more.

Getting Started

Download the production version or the development version.

In your web page:

API

The plugin offers four main interfaces:

  1. Player Customization
  2. Custom Actions and Event Callbacks
  3. Player Initiated Events
  4. TubePlayer management

See each section below to find the particular information you’re looking for.

1. Player Initialization and Customization

When initializing a YouTube player using TubePlayer, you will provide various properties that can be used to customize the behavior and UX of the player. For more details about the properties, and their possible values, check out the YouTube’s official documentation.

Here are the properties, their default values, a description and the expected type(s) of data:

Purpose Property Type Default Value
Player Width width Number 480
Player Height height Number 270
Allow Full Screen allowFullScreen Boolean "true"
Initial Video ID initialVideo String "DkoeNLuMbcI"
Start Time (seconds) start Number 0
Preferred Quality preferredQuality String "default"
Show Player Controls controls Number 1
Show Related Videos showRelated Boolean false
Play inline (for Mobile) playsinline Boolean false
Auto Play Video autoPlay Boolean false
Color color String "red"
Show Video Information showinfo boolean false
Modest Branding modestbranding Boolean true
Show Closed Caption Annotations annotations Boolean true
Loop playback continuously loop Number 0
Protocol protocol String window.location.protocol

2. Custom Actions and Event Callbacks

When you explicitly invoke the TubePlayer to execute a particular action – e.g. “mute” – there are certain callbacks that can be defined to globally handle such actions. In the case of the “mute” action, for example, there is an “onMute” function.

Here are the custom actions:

Purpose Action Arguments Response
Get the options used to create the player object. opts None Object
Cue a video cue “<VideoId>” None
Cue a list of video’s using IDs cuePlaylist {playlist: [“<VideoID1>”], index:0, startSeconds:0} None
Load the player with a video and/or play. play 1. None
2. “<VideoID>”
3. {id: “<VideoID>”, time: <StartSecs>}
None
Load the player with a list of videos and play. playPlaylist 1. [“<VideoID>”]
2. {playlist: [“<VideoID>”], time:0, index:0}
None
Play the next video if a playlist has been defined. next None None
Play the previous video if a playlist has been defined. previous None None
Play a video at a particular index in the playlist. playVideoAt <Index e.g. 0> None
Pause the player. pause None None
Stop the player. stop None None
Seek within the video loaded. Seconds or “hh:mm:ss”. seek 1 (GET). <Seconds e.g. 30>
2 (SET). “00:30”
None
Kill the audio. Mute the player. mute None None
Re-enable audio. Unmute the player. unmute None None
Check to see if the player is actively muted. isMuted None Boolean
Get the volume of the player. volume 1 (GET). None
2 (SET). <Volume between 0-100>
1. Number
2. None
Read and tune the video quality. quality 1 (GET). None
2 (SET). “<QualityLevel>”
1. String
2. None
Read and adjust the rate of playback for the video. playbackRate 1 (GET). None
2 (SET). <Rate between 0-2>
1. Number
2. None
Obtain information about the video and the player. data None Object
Get the video ID for the actively playing video. videoId None String
Set the size of the video player. size {width: <Pixels>, height: <Pixels>} None
Destroy the video player. destroy None Null
Return the actual YTPlayer object player String YTPlayer Object

Each callback listener’s context (e.g. this) is the tubeplayer object. For example, within the callback, you could ask for the players data by invoking this.tubeplayer("data").

Here are the event callbacks, to be specified when initializing the player:

Purpose Property Argument
Play request. When tubeplayer("play") has been called onPlay videoID:string
Pause request. When tubeplayer("pause") has been called onPause
Stop request. When tubeplayer("stop") has been called onStop
Seek request. When tubeplayer("seek", <val>) has been called onSeek time:int
Mute request. When tubeplayer("mute") has been called onMute
UnMute request. When tubeplayer("unmute") has been called onUnMute

3. Player Initiated Events

There are events that are initiated from the player itself, for example – when the actual player starts playing, or pauses, or perhaps begins buffering. Moreover, the player can throw errors, like when a video couldn’t be loaded, or it’s not allowed to be embedded in websites.

Here are the non-error based events, to be specified when initializing the player:

Purpose Property Argument
Player has cued a video, or playlist and has yet to be played. onPlayerUnstarted
Player has ended video play. onPlayerEnded
Player has started playing. onPlayerPlaying
Player has been paused. onPlayerPaused
Player is in buffering mode; get data for more info. onPlayerBuffering
Player has cued a video. onPlayerCued
Player has loaded and is attached to the DOM. onPlayerLoaded
Player video quality has changed. onQualityChange quality:string
Player playback rate has changed. onRateChange rate:int

Here are the error based events, to be specified when initializing the player:

Purpose Property
Video cannot be found. onErrorNotFound
Video owner does not permit the embedding of this video in other websites. onErrorNotEmbeddable
Something bad happened: the player found an invalid input. onErrorInvalidParameter

4. TubePlayer Management

Lastly, it is worth noting that there are a few methods available at a global level, to interact with the players during various stages in their lifecycle.

Here are the global methods:

Purpose Function to execute or override
Get all the instantiated YouTube players through TubePlayer. $.tubeplayer.getPlayers()
Interact with the player once it has been attached to the DOM. $.tubeplayer.defaults.afterReady = function($player){}
Alter the tubeplayer internally defined defaults. $.tubeplayer.defaults.settings
Constants for YouTube Player States. $.tubeplayer.TubePlayer.State
Constants for YouTube Error States. $.tubeplayer.TubePlayer.Error

 

Changelog

v2.1.0 – Dec 2, 2016

  • New Player event: “onPlayerLoaded”, is called once player is ready
  • Exposed the internal defaults: “$.tubeplayer.defaults.settings”

v2.0.0 – Dec 2, 2016

  • Removed code to handle flash player (due to deprecation); instead – uses iframe player exclusively
  • Added playlist support with “playPlaylist”, “cuePlaylist”, “next”, “previous”, “playVideoAt” commands
  • Added support for rate change events “onRateChange”
  • Improved support for multiple tubeplayer instances
  • Support providing a list of Video IDs in the playlist property
  • Property showControls is no longer a boolean – the property is controls now: 0=none, 1=immediate, 2=lazy
  • Property autoHide has been deprecated and is no longer used
  • Property theme has been deprecated; players always use the dark theme
  • Improved security by adding origin (window.location.origin)
  • Revamped the test console + Updated tests to ensure successful execution

v1.1.7 – Sept 24, 2013

  • Use object syntax instead of argument syntax for loadVideoById method call

v1.1.6 – May 2, 2013

  • Updates to object returned by ‘data’ method
    • Added ‘videoLoadedFraction’ – bytesLoaded, bytesTotal and startBytes are technically deprecated.
    • Added ‘availablePlaybackRates’ – array of available playback rates
    • Changed ‘getVideoEmbedCode’ property -> ‘videoEmbedCode’
  • Added a new method for iframe player: ‘playbackRate’. Getter returns number. Setter applies to current video only. Video must support altering playbackRate in order to work. Check availablePlaybackRates in ‘data’.
  • Added more unit tests including flag for testing functionality in HTML5 trial mode

v1.1.5 – Apr 29, 2013

  • Added unit tests – 85 assertions
  • Added grunt configuration
  • Uses uglify via grunt for minification process now
  • Refactored plugin code
  • Exposed meaningful states: $.tubeplayer.TubePlayer.State, $.tubeplayer.TubePlayer.Error
  • Renamed ‘tubeplayer’ folder to ‘test_console’
  • ‘this’ in onPlayer[X] and onError[X] methods, is the player with the tubeplayer interface
  • Exposed an ‘opts’ function to retrieve the players options
  • Added ‘playsinline’ option which can be used to play video inline on iPad

v1.1.0 – Oct 1, 2012

  • Enabled ES5 ‘strict’ mode
  • Stricter equality checks / improve code
  • Multiple player support – appropriate randomization by use of GUIDs
  • Fix event handler binding on the player objects (both flash based and html5 enabled) – jQuery.tubeplayer.events
  • Perform appropriate cleanup when destroying tubeplayer

v1.0.4 – Nov 12, 2011

  • Bug fixes for parsing videoID
  • Support added for ‘loop’ parameter and annotations (iv_load_policy)

v1.0.3 – Aug 14th, 2011

  • Added theme and color support – dark/light with red/white
  • Added ‘start’ attribute – default 0
  • Added ‘showinfo’ attribute – default false
  • Added ‘modestbranding’ attribute – default true
  • Updated showControls, showRelated, autoPlay and autoHide to boolean from int

v1.0.2 – Aug 3rd, 2011

  • Add support for ‘autoHide’ parameter
  • ‘loadSWFObject’ attribute allows user to specify their swfobject inclusion

v1.0.1 – May 14th, 2011

  • IE 7 and 8 fixes
  • Simplify dependency by utilizing Google CDN for swfobject instead of requiring additional include
  • Added videoEmbedURL and videoID to “data” object
  • Added “videoId” convenience method
  • New onErrorInvalidParameters method to handle final error case
  • Added support for ‘showControls’ and ‘showRelated’ player attributes
  • Enhanced multiple player support for iframe/html5 player
  • New public method to get all players jQuery.tubeplayer.getPlayers()
  • Fixed unmute – uses volume before muted now

Special thanks to @Branden Smith for the first few fixes

v1.0.0 – Feb 13th, 2011

  • Note: This update is completely backwards compatible
  • Support for HTML5 – IFRAME embedded player
  • HTML5 by default now, if not supported will degrade to Flash player
  • Added ‘autoplay’ and ‘controls’ properties for player init

v0.9.4 – Sept 5th, 2010

  • New event: ‘size’; Now you can modify the player’s size
  • Add player ‘wmode’ default as transparent, to prevent z-index issues in IE (thanks @Daniel Brouse)

v0.9.3 – Aug 20, 2010

  • Fixed onError Handlers

v0.9.2 – Aug 10, 2010

  • Added ‘player’ method, to get direct access to the youtube player

v0.9.1 – July 30, 2010

  • Multiple player support
  • Added ‘onQualityChange’ callback to defaults

v0.9.0 – July 24, 2010

  • Embed the API driven Flash YouTube Video Player – init/destroy
  • Control the player – cue, play, pause, stop, seek, volume control, quality control and data retrieval
  • Give developer controls after each event is triggered
  • Provide developer with state change friendly events (i.e. instead of state == -1, onPlayerUnstarted)
  • Hooks for ‘afterReady’, ‘stateChange’, ‘onError’ and ‘qualityChange’ for the player
  • Convenience methods for errors – onErrorNotFound, onErrorNotEmbeddable
  • Browser support tested: Firefox 3.5+, Chrome 5, Opera 10, Safari 5, IE6+