Awesome Video Background Plugin with HTML5 and Youtube API - YTPlayer

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

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=""></script>
<script src="inc/jquery.mb.YTPlayer.js"></script>

2. Include jQuery YTPlayer CSS to style your player

<link href="css/YTPlayer.css" media="all" rel="stylesheet">

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


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

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

5. 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
jQuery.fn.YTPlaylist(videos, shuffle, callback)

6 All of the options can be simply set by using 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: 1500,

   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)
   “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,

   showControls (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,

   mobileFallbackImage (bool)
   mobile fallback image if useOnMobile is set to false
  mobileFallbackImage: null,

   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,

   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.2,

   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,

   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) {}

7. API methods.

// change the video of the specified player

// play the video

// pause the video

// stop the video

// 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

// Returns 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.

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

// Return the alignment of the actual video.

8. Event hanlders.

  // 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.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.