README

An open source component to easily build your custom Youtube® player or to use a Youtube® video as background for your page.

Since 4.0 the player is written in plain JavaScript and does not need jQuery. When jQuery is on the page, the historical jQuery API ($(el).YTPlayer(), $(el).YTPPlay(), jQuery.mbYTPlayer, …) is registered automatically, so existing sites keep working without any change.

Original project by Matteo Bicocchi (pupunzi): https://github.com/pupunzi/jquery.mb.YTPlayer — documentation.

Installation

<link rel="stylesheet" href="dist/css/jquery.mb.YTPlayer.min.css">
<script src="dist/jquery.mb.YTPlayer.min.js"></script>

The file names did not change: sites that already include dist/jquery.mb.YTPlayer.min.js just get the new version. An ES module build is also available: dist/jquery.mb.YTPlayer.esm.js.

Native API (no jQuery)

<section id="hero">
  <div id="heroVideo"></div>
  <h1>My page</h1>
</section>

<script>
  const player = new YTPlayer('#heroVideo', {
    videoURL   : 'https://youtu.be/M7lc1UVf-VE',
    containment: '#hero',
    autoPlay   : true,
    mute       : true
  });

  player.on('YTPStart', e => console.log('started at', e.time));
  player.on('YTPData', e => console.log(e.prop.title));

  document.querySelector('#pause').addEventListener('click', () => player.pause());
</script>

new YTPlayer(elementOrSelector, options) – creates (or returns the existing) player of the element.
YTPlayer.create(selectorOrNodeList, options) – creates a player for every matching element, returns an array.
YTPlayer.getInstance(elementOrSelector) – returns the player of an element or null.
YTPlayer.playlist(element, videos, shuffle, callback) – builds a player from a list of videos.
YTPlayer.defaults, YTPlayer.controls, YTPlayer.apiKey – global configuration.
Options can also be set with the data-property attribute, as before.

Instance methods

Native	jQuery
`play()`, `pause()`, `stop()`, `togglePlay(cb)`	`YTPPlay`, `YTPPause`, `YTPStop`, `YTPTogglePlay`
`seekTo(sec)`	`YTPSeekTo`
`mute()`, `unmute()`, `toggleVolume()`, `setVolume(v)`, `getVolume()`	`YTPMute`, `YTPUnmute`, `YTPToggleVolume`, `YTPSetVolume`, `YTPGetVolume`
`getPlaybackRate()`, `setPlaybackRate(r)`	`YTPGetPlaybackRate`, `YTPSetPlaybackRate`
`changeVideo(opt)`	`YTPChangeVideo` / `YTPChangeMovie`
`playlist(videos, shuffle, cb)`, `playNext()`, `playPrev()`, `playIndex(i)`	`YTPlaylist`, `YTPPlayNext`, `YTPPlayPrev`, `YTPPlayIndex`
`fullscreen(real)`, `toggleLoops()`	`YTPFullscreen`, `YTPToggleLoops`
`applyFilter(f, v)`, `applyFilters(obj)`, `toggleFilter(f, v)`, `toggleFilters(cb)`, `removeFilter(f, cb)`, `enableFilters()`, `disableFilters()`, `getFilters()`	`YTPApplyFilter`, `YTPApplyFilters`, `YTPToggleFilter`, `YTPToggleFilters`, `YTPRemoveFilter`, `YTPEnableFilters`, `YTPDisableFilters`, `YTPGetFilters`
`addMask(path)`, `removeMask()`, `toggleMask()`	`YTPAddMask`, `YTPRemoveMask`, `YTPToggleMask`
`setAnchor(a)`, `getAnchor()`, `setAbundance(v, update)`, `getAbundance()`	`YTPSetAnchor`, `YTPGetAnchor`, `YTPSetAbundance`, `YTPGetAbundance`
`getPlayer()`, `getVideoID()`, `getPlaylistID()`, `getVideoData()`	`YTPGetPlayer`, `YTPGetVideoID`, `YTPGetPlaylistID`, `YTPGetVideoData`
`getTime()`, `getTotalTime()`	`YTPGetTime`, `YTPGetTotalTime`
`setOption(name, value)`, `changeCoverImage(url)`	`YTPSetOption`, `changeCoverImage`
`playerDestroy()` / `destroy()`	`YTPPlayerDestroy`
`on(type, fn)`, `off(type, fn)`	`.on()`, `.off()`

Events

Events are dispatched on the player element and bubble: YTPReady, YTPStart, YTPPlay, YTPPause, YTPBuffering, YTPEnd, YTPRealEnd, YTPUnstarted, YTPCued, YTPTime, YTPChanged, YTPChangeVideo, YTPData, YTPMuted, YTPUnmuted, YTPQualityChange, YTPFiltersApplied, YTPEnableFilters, YTPDisableFilters, YTPFullScreenStart, YTPFullScreenEnd. YTAPIReady is dispatched on document.

Extra data is available on the event itself (e.time, e.prop, e.quality, e.videoId) and in e.detail. With jQuery handlers e.time, e.prop… keep working as before.

jQuery API (legacy, still supported)

jQuery(function () {
  jQuery('#bgndVideo').YTPlayer({videoURL: 'M7lc1UVf-VE'});
  jQuery('#bgndVideo').on('YTPStart', function (e) { console.log(e.time); });
  jQuery('#bgndVideo').YTPPause();
});

What the compatibility layer keeps:

every $.fn.YTP* method, $.fn.YTPlayer / $.fn.mb_YTPlayer, $.fn.optimizeDisplay, $.fn.changeCoverImage, $.fn.unselectable;
jQuery.mbYTPlayer (apiKey, defaults, controls, version, removeStoredData(), …), kept in sync with YTPlayer;
the properties stored on the element (el.opt, el.player, el.filters, el.videoData, el.isReady, el.wrapper…); DOM properties are returned as jQuery objects for players created with jQuery;
the bundled helpers, unless already defined by the page: jQuery.mbBrowser, jQuery.mbCookie, jQuery.mbStorage, jQuery.isMobile, jQuery.isTablet, jQuery.shuffle, $.fn.CSSAnimate, $.fn.simpleSlider, $.fn.updateSliderVal.

If jQuery is loaded after the player script, the layer is installed on DOMContentLoaded; it can also be installed manually with YTPlayer.installJQuery(jQuery).

Changes in 4.0

jQuery is no longer required; internals use native DOM APIs, fetch and CSS transitions.
The YouTube IFrame API is injected only once and an existing window.onYouTubeIframeAPIReady handler is preserved.
Players created in the same millisecond get unique IDs (several background videos on one page).
jQuery.mbYTPlayer.removeStoredData() only removes YTPlayer data instead of clearing the whole localStorage.
Time based masks (mask: {0: 'a.png', 10: 'b.png'}) now switch at the configured second.
remember_last_time saves the position on pagehide (unload is deprecated in browsers).
No more console.time output; the delayAtStart option is no longer needed.
jQuery.CSS, jQuery.normalizeCss, $.fn.css3 and jQuery.support.CSStransition (internals of the old CSSAnimate plugin) are not provided anymore.

Build

npm install
npm run build   # or: npm run watch

Sources are in src/ (src/core/* native player, src/jquery/adapter.js jQuery layer), the build uses esbuild.

levmyshkin / jquery-mb-ytplayer

Package info

Security

Statistics