Awesome Video Background Plugin with HTML5 and Youtube API - YTPlayer

File Size: 10.4 MB
Views Total: 109963
Last Update:
Publish Date:
Official Website: Go to website
License: MIT
Awesome Video Background Plugin with HTML5 and Youtube API - YTPlayer

YTPlayer is a jQuery plugin that allows you to use a youtube video as the background of your web page using html5 data-* attributes and youtube API.

You can also use this plugin as a normal video player (with playlist support) for your web page. 

See also:


$ npm install jquery.mb.ytplayer

# Bower
$ bower install jquery.mb.ytplayer

Basic Usage:

1. Include jQuery framework and jQuery YTPlayer on the page

<script src="/path/to/cdn/jquery.min.js"></script>
<script src="/path/to/dist/jquery.mb.YTPlayer.min.js"></script>

2. Include jQuery YTPlayer CSS to style your player

<link href="/path/to/dist/css/jquery.mb.YTPlayer.min.css" rel="stylesheet" />

3. Call the plugin and we're ready to go.


4. Initialize a YTPlayer as a background. You're able to pass the options using the data-property attribute:

<a class="player" 
   data-property="{videoURL:'YW2Aa4CJEgY',containment:'body',autoPlay:true, mute:true, startAt:0,opacity:1}">
   My video

5. Initialize the plugin as a simple Youtube player.

<a class="player" 
   data-property="{videoURL:'YW2Aa4CJEgY',containment:'self',autoPlay:true, mute:true, startAt:0,opacity:1}">
   My video

6. You can also play a list of Youtube videos using the YTPlaylist methods.

// videos: an array of video objects
// shuffle: set to true you can have a random sequence of videos
// callback: callback function
var videos = [
    {videoURL:"VIDEO ID or VIDEO URL here",containment:'body',autoPlay:true, mute:false, startAt:0,opacity:1, loop:false, ratio:"4/3", addRaster:true},
    {videoURL: "VIDEO ID or VIDEO URL here",containment:'body',autoPlay:true, mute:true, startAt:0,opacity:1, loop:false, ratio:"4/3", addRaster:false},
    {videoURL: "VIDEO ID or VIDEO URL here",containment:'body',autoPlay:true, mute:false, startAt:0,opacity:1, loop:false, ratio:"4/3", addRaster:true}
jQuery(".player").YTPlaylist(videos, false, function(video){

7. All possible options to customize the player. These options can also be passed via data-* attributes.

   videoURL (string)
   the complete Youtube video URL or the short url or the videoID
  videoURL: null,

   containment (string)
   default containment for the player
  containment: 'body',

   ratio (string or number)
   "auto", "16/9", "4/3" or number: 4/3, 16/9
  ratio: 'auto',

   fadeOnStartTime (int)
   fade in timing at video start
  fadeOnStartTime: 1000,

   startAt (int)
   start second
  startAt: 0,

   stopAt (int)
   stop second
  stopAt: 0,

   autoPlay (bool)
   on page load video should start or pause
  autoPlay: true,

   coverImage (string)
   The path to the image to be used as cover if the autoPlay option is set to false
  coverImage: false,

   loop (bool or int)
   video should loop or not; if number it will loop for the specified times
  loop: true,

   addRaster (bool)
   shows a raster image over the video (added via CSS)
   You can change the raster image via CSS:
   .YTPOverlay.raster { background: url(images/raster.png)}
  addRaster: false,

   mask (bool or object) the key is the second and the value is the path to the image
   Ex: mask:{ 0:'assets/mask-1.png', 5:'assets/mask-2.png', 30: false, 50:'assets/mask-3.png'}
  mask: false,

   opacity (int)
   0 to 1
  opacity: 1,

   quality (string)

   setPlaybackQuality has been deprecated on the YT API and doesn't work anymore
   “small”, “medium”, “large”, “hd720”, “hd1080”, “highres”, "default"
  quality: 'default',

   vol (int)
   0 to 100
  vol: 50,

   mute (bool)
   mute the video at start
  mute: false,

   showControls (bool)
   shows the control bar at the bottom of the containment
  showControls: true,

   anchor (string)
   center,top,bottom,left,right combined in pair
  anchor: 'center,center',

   showAnnotations (bool)
   display the annotations on video
  showAnnotations: false,

   cc_load_policy (bool)
   display the subtitles
  cc_load_policy: false,

   showYTLogo (bool)
   display the Youtube logotype inside the button bar
  showYTLogo: true,

   useOnMobile (bool)
   activate the player also on mobile
  useOnMobile: true,

   playOnlyIfVisible (bool)
   play the video only if the containment is on screen
  playOnlyIfVisible: false,

   onScreenPercentage (bool)
   percentage of the player height the video should stop or start when visible
  onScreenPercentage: 30,

   * goFullScreenOnPlay (bool)
   * if the player containment is set to "self" this allow the video to go fullscreen when played
  goFullScreenOnPlay: false,

   stopMovieOnBlur (bool)
   stop the video if the window loose the focus
  stopMovieOnBlur: true,

   realfullscreen (bool)
   the video when in full screen covers all the display
  realFullscreen: true,

   optimizeDisplay (bool)
   The video always fit the containment without displaying the black strips
  optimizeDisplay: true,

   abundance (bool)
   the abudance of the video size
  abundance: 0.3,

   gaTrack (bool)
   track the video plays on GA
  gaTrack: true,

   remember_last_time (bool)
   when the page is reloaded the video will start from the last position
  remember_last_time: false,

   addFilters (bool or string)
   add one or more CSS filters as object to the video
   Ex: {sepia: 50, hue_rotate : 220}
  addFilters: false,

   useNoCookie (bool)
   use host to serve the video
  useNoCookie: true,

   onReady (function)
   a callback function fired once the player is ready
  onReady: function (player) {

   onReady (function)
   a callback function fired if there's an error
  onError: function (player, err) {

   onEnd (function)
   a callback function fired when the video ends
  onEnd: function () {

8. More API methods.

// change the video of the specified player

// play the video

// pause the video

// stop the video

// seek to 20s

// Manage video speed

// switch video from background to front

// change the video volume

// mute the audio

// unmute the audio

// switch from mute to unmute

// retrive the original player returned by the YouTube API

// return the info data of the current video as JSON.

// available only if you are playing a video list; 
// goes to the next video in the play list.

// available only if you are playing a video list; 
// goes to the previous video in the play list.

// available only if you are playing a video list; goes to a specific video in the play list based on the index.

// return the actual video time.

// return the total video time.

// return the actual anchor point for the video.

// define how the video will behave once the window is resized
// possible value are: ‘top,bottom,left,right,center’
// it accepts a pair of value comma separated (ex: ‘top,right’ or ‘bottom,left’)

// apply a CSS filter to the player:
// grayscale : 1-100,
// hue_rotate: 1-360,
// invert : 1-100,
// opacity : 1-100,
// saturate : 1-400,
// sepia : 1-100,
// brightness: 1-400,
// contrast : 1-400,
// blur : 1-100
jQuery(".player").YTPApplyFilter('sepia', 50);

// apply multiple CSS filters to the player

// toggle the filter from the passed value to 0 and vice-versa
jQuery(".player").YTPtoggleFilter(filter, value);

// toggle all the filters

// remove a filter
jQuery(".player").YTPRemoveFilter(filter, callback);

// disable all filters

// enable filters

// add a mask to the target video player

// remove the mask

// toggle the mask

// Change the cover image

9. Event hanlders.

// properties:

  // do something here

  // do something here

  // do something here

  // do something here

  // do something here

  // do something here

  // do something here

  // do something here

  // do something here

  // do something here

  // do something here

  // do something here

  // do something here

More examples:


v3.3.9 stable (2022-05-29)

  • Renamed the jQuery.browser to jQuery.mbBrowser to prevent deprecated alert in Wordpress
  • Updated package

v3.3.8 stable (2021-01-10)

  • Introduced "noCookie" as an option. By default is set to true

v3.3.7 (2020-12-04)

  • The mb.YTPlayer is now using to serve videos.
  • Feature: If the video is set to "autoplay"  and is not muted, instead of pausing it bevore the first user interaction it starts muted and turn on the audio with the first interaction.

v3.3.6 (2020-11-27)

  • Bugfix: With the latest macOS Big Sur system update the User-Agent has been changed and the OS detection was failing on Safari causing a blocking error.

v3.3.5 (2020-11-11)

  • Bugfixes

v3.3.4 (2020-11-01)

  • New feature: If you set the player as inline (via the short-code editor) you can now activate the "Go Full Screen on Play" feature.
  • Bug fix: The inline Player "Play" icon was not working properly.
  • Adding an option to start playing the video fullscreen if not in autoplay
  • removed the "quality" parameter as it has been deprecated and nevermore used by the Youtube API

v3.3.3 (2020-06-07)

  • Get data with YT API key bugfix

v3.3.2 (2020-05-21)

  • Removed the isTouchSupported function duplication

v3.3.1 (2020-04-17)

  • Added a new method to change the cover image: jQuery.fn.changeCoverImage

v3.3.1 (2020-04-10)

  • Optimize display on orientation change for Chrome mobile

v3.3.1 (2020-03-18)

  • Re-build

v3.3.1 (2020-01-13)

  • Wrong video ID endless loop bug fix
  • Bugfix: endless loop if a wrong video ID was set

v3.2.11 (2019-12-16)

  • Added two methods to manage video speed: jQuery.fn.YTPGetPlaybackRate and jQuery.fn.YTPSetPlaybackRate

v3.2.10 (2019-06-21)

  • Bug fix: the YTPlayer container background image was removed by the plugin

v3.2.9 (2019-02-25)

  • Fixed an issue that prevented the optimize display to set the anchor point correctly

v3.2.8 (2018-12-03)

  • Better Optimize display management

v3.2.7 (2018-10-10)

  • Mute didn't work anymore

v3.2.6 (2018-10-05)

  • Fixed the Safari freeze bug due to the new autoplay policy.

v3.2.5 (2018-09-24)

  • working on background-image bug
  • Fixed: The YTPlaylist method didn't work as aspected due to a bug introduced on the YTPGetPlayer() method.

v3.2.5 (2018-09-07)

  • Bug fix

v3.2.4 (2018-07-13)

  • Bug fix: Once ended the first YTPPlay event was not fired
  • Added a play button for inline players when paused.
  • Changed jQuery.browser method name to jQuery.mbBrowser to prevent conflicts.
  • changed the autoplay behavior if audio is active and browser is Chrome

v3.2.3 (2018-06-21)

  • Release v3.2.3 stable
  • DOC update

v3.2.2 (2018-06-20)

  • Release v3.2.2 stable

v3.2.1 (2018-05-30)

  • Release v3.2.1 stable
  • Fixed Unified handling of options (javascript parameters) and properties (html attribute)
  • Added comments to options
  • Working on playOnlyIfVisible property
  • Bug fix: options where redefined cross video
  • Bug fix: if there were more then one player the options where inconsistent
  • Bug fix: the coverImage were not displayed correctly

v3.1.13 (2018-04-07)

  • Added "cc_load_policy" to activate subtitles
  • Change property name from "backgroundImage" to "coverImage"
  • bugfix: cover image path
  • working on: playOnlyIfVisible

v3.1.12 (2018-01-31)

  • Release v3.1.12 stable

v3.1.11 (2018-01-28)

  • Release v3.1.11 stable
  • Bug fix: options were overwritten by last player initialized

v3.1.9 (2018-01-24)

  • Bug fix: if the place holder was the target video was not displayed
  • Bug fix: Fixed a bug that was preventing the correct behavior if the "Remember last video time position" was checked.
  • fixing a bug if multiple player are initialized on the page the properties are of the last player initialized

v3.1.8 (2018-01-19)

  • Release v3.1.8 stable

v3.1.6 (2018-01-17)

  • Release v3.1.6 stable

v3.1.5 (2018-01-16)

  • the optimizeADisplay function evaluate the "abundance" as a percentage of the iframe height instead of a fixed value
  • Code refactor and start working on playlist compatibility
  • Improvements: working on applying filter easily from the options
  • Layout changes for demo pages

v3.1.2 (2017-11-17)

  • Added the playOnlyIfVisible option that make the video play only if it is on screen
  • Better performance on video start up
  • Bug fix: on Android devices the 'playsInline' property test return false preventing the video player to run

v3.1.1 (2017-10-08)

  • fix a terrible bug that was preventing controls to work as aspected
  • bug fix: controls didn't work anymore
  • various fix for mobile compatibility
  • various updates for the demos and playOnlyIfVisible

v3.1.0 (2017-09-27)

  • Working on mobile compatibility
  • checking the 'playsInline' property of the video element to manage the mobile background video if allowed
  • fixed the poster image resolution for inline players

v3.0.20 (2017-08-19)

  • iOs fix
  • YTPlayer.start_from_last: set cookie time to 0 to clear cookie on session close
  • Working on mobile compatibility

v3.0.19 (2017-05-12)

  • OS detection for mobile fix

v3.0.18 (2017-05-11)

  • Various fix

v3.0.17 (2017-05-06)

  • Various fix

v3.0.16 (2017-04-26)

  • Various fix

v3.0.15 (2017-04-24)

  • Various fix

v3.0.14 (2017-04-19)

  • Various fix

v3.0.12 (2017-04-05)

  • the stop event is .5 sec before the real (before was 1.5)

v3.0.12 (2017-03-02)

  • Various fix

v3.0.11 (2017-02-22)

  • Various fix

v3.0.10 (2017-01-08)

  • Various fix

v3.0.8 (2016-07-26)

  • Various fix

v3.0.6 (2016-07-07)

  • Various fix
  • added YTPPlayIndex method to play a specific video in a playlist using YTPPlaylist
  • update and fix for jQuery 3.0.0

v3.0.3 (2016-06-10)

  • Various fix
  • added several new methods to get video state

v3.0.1 (2016-05-20)

  • worked on filters methods

v3.0.0 (2016-03-27)

  • Various fix

v2.9.5 (2016-03-11)

  • added mask methods and demo page

v2.9.13 (2016-02-06)

  • minor bug fix

v2.9.11 (2016-01-21)

  • minor bug fix

v2.9.10 (2016-01-09)

  • minor bug fix

v2.9.9 (2016-01-07)

  • Working on speed up st start

v2.9.8 (2015-12-08)

  • new feature: loop videos in playList

v2.9.5 (2015-10-25)

  • bugfix on dropdown action event

v2.9.4 (2015-10-08)

  • update + various fix

v2.9.3 (2015-06-28)

  • update + various fix
  • Changes on: getDataFromAPI method

v2.9.0 (2015-05-09)

  • updating to YT API 3 for video DATA. - set the apikey private (not available in the package)
  • Better control to check if the video is ready to play


  • v2.8.5


  • various code refactor


  • added blur filters


  • added volume control and filters

v2.8.0 (2015-01-31)

  • various fix

v2.7.9 (2015-01-12)

  • various fix

v2.7.8 (2014-12-14)

  • various changes

v2.7.5 (2014-11-16)

  • various fix

v2.7.2 (2014-08-23)

  • various fix

v2.7.0 (2014-08-19)

  • major update,

v2.6.9 (2014-06-23)

  • mute / unmute bug fix

v2.6.8 (2014-06-23)

  • various fix

v2.6.7 (2014-05-13)

  • various fix

v2.6.6 (2014-03-31)

  • various fix

v2.6.3 (2014-03-19)

  • various fix

v2.6.2 (2014-01-28)

  • various fix

v2.6.0 (2013-11-24)

  • updated to the latest version

v2.5.9 (2013-11-21)

  • updated to the latest version

v2.5.8 (2013-11-13)

  • various fix

v2.5.7 (2013-08-31)

  • Added real fullscreen
  • various fix

v2.5.4 (2013-05-31)

  • fixed a bug for IE that prevented the changeMovie to work

v2.5.2 (2013-05-31)

  • various fix

This awesome jQuery plugin is developed by pupunzi. For more Advanced Usages, please check the demo page or visit the official website.