Awesome Video Background Plugin with HTML5 and Youtube API - YTPlayer

File Size: 10.4 MB
Views Total: 109523
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:

Installation:

# NPM
$ 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.

jQuery(function(){
  jQuery(".player").YTPlayer();
});

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

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

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){
  jQuery("#videoID").html(video.videoData.id);
  jQuery("#videoTitle").html(video.videoData.title);
  jQuery("#videoDesc").html(video.videoData.description);
});

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

jQuery(".player").YTPlayer({
  /**
   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)
   @deprecated

   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 https://www.youtube-nocookie.com 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
jQuery(".player").YTPChangeMovie(opt);

// play the video
jQuery(".player").YTPPlay();

// pause the video
jQuery(".player").YTPPause();

// stop the video
jQuery(".player").YTPStop();

// seek to 20s
jQuery('#[playerID]').YTPSeekTo(20);

// Manage video speed
jQuery(".player").YTPSetPlaybackRate()
jQuery(".player").YTPGetPlaybackRate()

// switch video from background to front
jQuery(".player").YTPFullscreen();

// change the video volume
jQuery(".player").YTPSetVolume(val);

// mute the audio
jQuery(".player").YTPMute();

// unmute the audio
jQuery(".player").YTPUnmute();

// switch from mute to unmute
jQuery(".player").YTPToggleVolume();

// retrive the original player returned by the YouTube API
jQuery(".player").YTPGetPlayer();

// return the info data of the current video as JSON.
jQuery(".player").YTPGetVideoData();

// available only if you are playing a video list; 
// goes to the next video in the play list.
jQuery(".player").YTPPlayNext();

// available only if you are playing a video list; 
// goes to the previous video in the play list.
jQuery(".player").YTPPlayPrev();

// available only if you are playing a video list; goes to a specific video in the play list based on the index.
jQuery(".player").YTPPlayIndex(idx);

// return the actual video time.
jQuery(".player").YTPGetTime();

// return the total video time.
jQuery(".player").YTPGetTotalTime();

// return the actual anchor point for the video.
jQuery(".player").YTPGetAnchor();

// 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’)
jQuery(".player").YTPSetAnchor(posX,posY);

// 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
jQuery(".player").YTPApplyFilters(filters);

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

// toggle all the filters
jQuery(".player").YTPToggleFilters(callback);

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

// disable all filters
jQuery(".player").YTPDisableFilters();

// enable filters
jQuery(".player").YTPEnableFilters();

// add a mask to the target video player
jQuery(".player").YTPAddMask("path/to/mask.jpg");

// remove the mask
jQuery(".player").YTPRemoveMask();

// toggle the mask
jQuery(".player").YTPToggleMask();

// Change the cover image
jQuery(".player").changeCoverImage(img);

9. Event hanlders.

// properties:
videoData.id
videoData.channelTitle
videoData.title
videoData.description
videoData.thumb_max
videoData.thumb_high
videoData.thumb_medium

jQuery(".player").on("YTPUnstarted",function(e){
  // do something here
});

jQuery(".player").on("YTPBuffering",function(e){
  // do something here
});

jQuery(".player").on("YTPReady",function(e){
  // do something here
});

jQuery(".player").on("YTPStart",function(e){
  // do something here
});

jQuery(".player").on("YTPPlay",function(e){
  // do something here
});

jQuery(".player").on("YTPPause",function(e){
  // do something here
});

jQuery(".player").on("YTPEnd",function(e){
  // do something here
});

jQuery(".player").on("YTPFullScreenStart",function(e){
  // do something here
});

jQuery(".player").on("YTPFullScreenEnd",function(e){
  // do something here
});

jQuery(".player").on("YTPMuted",function(e){
  // do something here
});

jQuery(".player").on("YTPUnmuted",function(e){
  // do something here
});

jQuery(".player").on("YTPTime",function(e){
  // do something here
});

jQuery(".player").on("YTPData",function(e){
  // do something here
});

More examples:

Changelog:

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 youtube-nocookie.com 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

2015-04-26

  • v2.8.5

2015-04-23

  • various code refactor

2015-04-21

  • added blur filters

2015-04-20

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