plyr README

The project's README from github.com/sampotts/plyr. As one markdown file: README.md.

Plyr is a simple, lightweight, accessible and customizable HTML5, YouTube and Vimeo media player that supports modern browsers.

Checkout the demo - Donate - Slack - Video hosting

npm version Gitpod Ready-to-Code Financial Contributors on Open Collective

Screenshot of Plyr

Features

Demos

You can try Plyr in Codepen using our minimal templates: HTML5 video, HTML5 audio, YouTube, Vimeo. For Streaming we also have example integrations with: Dash.js, Hls.js and Shaka Player

Quick setup

HTML

Plyr extends upon the standard HTML5 media element markup so that's all you need for those types.

HTML5 Video

<video id="player" playsinline controls data-poster="/path/to/poster.jpg">
  <source src="/path/to/video.mp4" type="video/mp4" />
  <source src="/path/to/video.webm" type="video/webm" />

  <!-- Captions are optional -->
  <track kind="captions" label="English captions" src="/path/to/captions.vtt" srclang="en" default />
</video>

Note: The poster image should be specified using data-poster. This is to prevent it being downloaded twice. If you're sure the image will be cached, you can still use the poster attribute for true progressive enhancement.

HTML5 Audio

<audio id="player" controls>
  <source src="/path/to/audio.mp3" type="audio/mp3" />
  <source src="/path/to/audio.ogg" type="audio/ogg" />
</audio>

For YouTube and Vimeo players, Plyr uses progressive enhancement to enhance the default <iframe> embeds. Below are some examples. The plyr__video-embed classname will make the embed responsive. You can add the autoplay, loop, hl (YouTube only) and playsinline (YouTube only) query parameters to the URL and they will be set as config options automatically. For YouTube, the origin should be updated to reflect the domain you're hosting the embed on, or you can opt to omit it.

YouTube

We recommend progressive enhancement with the embedded players. You can elect to use an <iframe> as the source element (which Plyr will progressively enhance) or a bog standard <div> with two essential data attributes - data-plyr-provider and data-plyr-embed-id.

<div class="plyr__video-embed" id="player">
  <iframe
    src="https://www.youtube.com/embed/bTqVqk7FSmY?origin=https://plyr.io&amp;iv_load_policy=3&amp;modestbranding=1&amp;playsinline=1&amp;showinfo=0&amp;rel=0&amp;enablejsapi=1"
    allowfullscreen
    allowtransparency
    allow="autoplay"
  ></iframe>
</div>

Note: The plyr__video-embed classname will make the player a responsive 16:9 (most common) iframe embed. When plyr itself kicks in, your custom ratio config option will be used.

Or the <div> non progressively enhanced method:

<div id="player" data-plyr-provider="youtube" data-plyr-embed-id="bTqVqk7FSmY"></div>

Note: The data-plyr-embed-id can either be the video ID or URL for the media.

Vimeo

Much the same as YouTube above.

<div class="plyr__video-embed" id="player">
  <iframe
    src="https://player.vimeo.com/video/76979871?loop=false&amp;byline=false&amp;portrait=false&amp;title=false&amp;speed=true&amp;transparent=0&amp;gesture=media"
    allowfullscreen
    allowtransparency
    allow="autoplay"
  ></iframe>
</div>

Or the <div> non progressively enhanced method:

<div id="player" data-plyr-provider="vimeo" data-plyr-embed-id="76979871"></div>

JavaScript

You can use Plyr as an ES6 module as follows:

import Plyr from 'plyr';

const player = new Plyr('#player');

Alternatively you can include the plyr.js script before the closing </body> tag and then in your JS create a new instance of Plyr as below.

<script src="path/to/plyr.js"></script>
<script>
  const player = new Plyr('#player');
</script>

See initialising for more information on advanced setups.

You can use our CDN (provided by Cloudflare) for the JavaScript. There's 2 versions; one with and one without polyfills. My recommendation would be to manage polyfills separately as part of your application but to make life easier you can use the polyfilled build.

<script src="https://cdn.plyr.io/3.8.4/plyr.js"></script>

...or...

<script src="https://cdn.plyr.io/3.8.4/plyr.polyfilled.js"></script>

CSS

Include the plyr.css stylesheet into your <head>.

<link rel="stylesheet" href="path/to/plyr.css" />

If you want to use our CDN (provided by Cloudflare) for the default CSS, you can use the following:

<link rel="stylesheet" href="https://cdn.plyr.io/3.8.4/plyr.css" />

SVG Sprite

The SVG sprite is loaded automatically from our CDN (provided by Cloudflare). To change this, see the options below. For reference, the CDN hosted SVG sprite can be found at https://cdn.plyr.io/3.8.4/plyr.svg.

Self hosting

If you don't want to create a build system to include Plyr as an npm module, you can use the pre-built files. You have a few options:

Ads

Plyr has partnered up with vi.ai to offer monetization options for your videos. Getting setup is easy:

Any questions regarding the ads can be sent straight to vi.ai and any issues with rendering raised through GitHub issues.

If you do not wish to use Vi, you can set your own ads.tagUrl option.

Advanced

Customizing the CSS

If you want to change any design tokens used for the rendering of the player, you can do so using CSS Custom Properties.

Here's a list of the properties and what they are used for:

Name Description Default / Fallback
--plyr-color-main The primary UI color. #f03c15 #00b3ff
--plyr-video-background The background color of video and poster wrappers for using alpha channel videos and poster images. rgba(0, 0, 0, 1)
--plyr-focus-visible-color The color used for the focus styles when an element is :focus-visible (keyboard focused). --plyr-color-main
--plyr-badge-background The background color for badges in the menu. #4a5464 #4a5464
--plyr-badge-text-color The text color for badges. #ffffff #ffffff
--plyr-badge-border-radius The border radius used for badges. 2px
--plyr-captions-background The color for the background of captions. rgba(0, 0, 0, 0.8)
--plyr-captions-text-color The color used for the captions text. #ffffff #ffffff
--plyr-control-icon-size The size of the icons used in the controls. 18px
--plyr-control-spacing The space between controls (sometimes used in a multiple - e.g. 10px / 2 = 5px). 10px
--plyr-control-padding The padding inside controls. --plyr-control-spacing * 0.7 (7px)
--plyr-control-radius The border radius used on controls. 3px
--plyr-control-toggle-checked-background The background color used for checked menu items. --plyr-color-main
--plyr-video-controls-background The background for the video controls. linear-gradient(rgba(0, 0, 0, 0), rgba(0, 0, 0, 0.75))
--plyr-video-control-color The text/icon color for video controls. #ffffff #ffffff
--plyr-video-control-color-hover The text/icon color used when video controls are :hover, :focus and :focus-visible (equivalent). #ffffff #ffffff
--plyr-video-control-background-hover The background color used when video controls are :hover, :focus and :focus-visible (equivalent). --plyr-color-main
--plyr-audio-controls-background The background for the audio controls. #ffffff #ffffff
--plyr-audio-control-color The text/icon color for audio controls. #4a5464 #4a5464
--plyr-audio-control-color-hover The text/icon color used when audio controls are :hover, :focus and :focus-visible (equivalent). #ffffff #ffffff
--plyr-audio-control-background-hover The background color used when video controls are :hover, :focus and :focus-visible (equivalent). --plyr-color-main
--plyr-menu-background The background color for menus. rgba(255, 255, 255, 0.9)
--plyr-menu-color The text/icon color for menu items. #4a5464 #4a5464
--plyr-menu-shadow The shadow used on menus. 0 1px 2px rgba(0, 0, 0, 0.15)
--plyr-menu-radius The border radius on the menu. 4px
--plyr-menu-arrow-size The size of the arrow on the bottom of the menu. 6px
--plyr-menu-item-arrow-color The color of the arrows in the menu. #728197 #728197
--plyr-menu-item-arrow-size The size of the arrows in the menu. 4px
--plyr-menu-border-color The border color for the bottom of the back button in the top of the sub menu pages. #dcdfe5 #dcdfe5
--plyr-menu-border-shadow-color The shadow below the border of the back button in the top of the sub menu pages. #ffffff #ffffff
--plyr-progress-loading-size The size of the stripes in the loading state in the scrubber. 25px
--plyr-progress-loading-background The background color on the loading state in the scrubber. rgba(35, 40, 47, 0.6)
--plyr-video-progress-buffered-background The fill color for the buffer indication in the scrubber for video. rgba(255, 255, 255, 0.25)
--plyr-audio-progress-buffered-background The fill color for the buffer indication in the scrubber for audio. rgba(193, 200, 209, 0.6)
--plyr-range-thumb-height The height of the scrubber handle/thumb. 13px
--plyr-range-thumb-background The background of the scrubber handle/thumb. #ffffff #ffffff
--plyr-range-thumb-shadow The shadow of the scrubber handle/thumb. 0 1px 1px rgba(215, 26, 18, 0.15), 0 0 0 1px rgba(215, 26, 18, 0.2)
--plyr-range-thumb-active-shadow-width The width of the shadow when the scrubber handle/thumb is :active (pressed). 3px
--plyr-range-track-height The height of the scrubber/progress track. 5px
--plyr-range-fill-background The fill color of the scrubber/progress. --plyr-color-main
--plyr-video-range-track-background The background of the scrubber/progress. --plyr-video-progress-buffered-background
--plyr-video-range-thumb-active-shadow-color The color of the shadow when the video scrubber handle/thumb is :active (pressed). rgba(255, 255, 255, 0.5)
--plyr-audio-range-track-background The background of the scrubber/progress. --plyr-video-progress-buffered-background
--plyr-audio-range-thumb-active-shadow-color The color of the shadow when the audio scrubber handle/thumb is :active (pressed). rgba(215, 26, 18, 0.1)
--plyr-tooltip-background The background color for tooltips. rgba(255, 255, 255, 0.9)
--plyr-tooltip-color The text color for tooltips. #4a5464 #4a5464
--plyr-tooltip-padding The padding for tooltips. `calc(

plyr (sampotts/plyr)

Searching Database…

30K ·GitHub
Plyr
What is this?Plyr is a simple, lightweight, accessible and customizable HTML5, YouTube and Vimeo media player that supports modern browsers.
Is it a library I add to my own web page, or a hosted service?A JavaScript library: you include plyr.css and plyr.js — via an npm module, a plain script tag or the Cloudflare-hosted CDN — and initialize Plyr over your media elements.
How do I add a player to a page?For HTML5 video and audio just write the standard media markup — Plyr extends it (use data-poster for the poster image). For YouTube and Vimeo, let Plyr progressively enhance the default embed or set the data-plyr-provider and data-plyr-embed-id attributes.
Does it need jQuery or a framework?No — Plyr is written in vanilla ES6 JavaScript with no jQuery or framework required, and a polyfilled CDN build exists if you need older browser support.
Is it still actively maintained?No — Plyr is deprecated in favor of Video.js 10 and receives security updates only, so weigh that before building something new on it.
Which media sources can it play?HTML5 video and audio in the major formats, YouTube and Vimeo embeds, plus adaptive streaming through hls.js, Shaka Player and dash.js — the README includes example integrations for each.
Can I control playback and events from my own code?Yes — a standardized API covers toggling playback, volume, seeking and more, and events are normalized across HTML5, YouTube and Vimeo, so you never touch their separate player APIs.
Can I make the player match my site's design?Yes — everything is styled with CSS Custom Properties (accent color, control spacing, caption colors, menus and more), you can use your own markup, and Sass source is provided for build processes.
What player features are built in?Fullscreen with a full-window fallback, keyboard shortcuts, picture-in-picture, playsinline, on-the-fly speed controls, multiple VTT caption tracks with screen-reader support, preview thumbnails and i18n of the controls.
What are similar projects?video.js, react-player, material, sweetalert2, bootstrap-table, shoelace, fathom, draft-js
Which topics is it in?media-player, video-player, subtitles, youtube, accessibility, i18n, javascript-library, audio, streaming, customization, deprecated, css
Creator
sampotts
Size
65.1 MB
Stars
30K
Updated
CommitOct 07Releasev3.8.5Oct 06
Age
11y
Commits · 90 Days