探客时代 | 知识就是力量
Plyr A simple HTML5, YouTube and Vimeo player
README | :-: | :---------------------------------------------------------------------------: | :-- |
Plyr is a simple, lightweight, accessible and customizable HTML5, YouTube and Vimeo media player that supports
_modern_ browsers.
Features
- 📼 HTML Video & Audio, YouTube & Vimeo - support for the major formats
- 💪 Accessible - full support for VTT captions and screen readers
- 🔧
Customizable - make the player look how you want with the markup you want
- 😎 **Clean HTML** - uses the _right_ elements. `
` for volume and `
` for progress and well, ``s for buttons. There's no `` or `` button hacks- 📱 Responsive - works with any screen size
- 📹
Streaming - support for hls.js, Shaka and dash.js streaming playback
- 🎛
API - toggle playback, volume, seeking, and more through a standardized API
- 🎤
Events - no messing around with Vimeo and YouTube APIs, all events are standardized across formats
- 🔎
Fullscreen - supports native fullscreen with fallback to "full window" modes
- 🖥 Picture-in-Picture - supports picture-in-picture mode
- 📱 Playsinline - supports the playsinline attribute
- 🏎 Speed controls - adjust speed on the fly
- 📖 Multiple captions - support for multiple caption tracks
- 🌎 i18n support - support for internationalization of controls
- 🤟 No frameworks - written in "vanilla" ES6 JavaScript, no jQuery required
- 💁♀️ Sass - to include in your build processes
Demos
Quick setup
HTML
Plyr extends upon the standard
HTML5 media element markup so that's all you need for those types.
HTML5 Video
``` html <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" /> <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
``` html <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 ` ` tag and then in your JS create a new instance of Plyr as below.
``` html <script src = "path/to/plyr.js" > </script > <script > const player = new Plyr('#player'); </script > ```
You can use our CDN (provided by
Fastly ) 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.
``` html <script src = "https://cdn.plyr.io/3.7.3/plyr.js" > </script > ```
...or...
``` html <script src = "https://cdn.plyr.io/3.7.3/plyr.polyfilled.js" > </script > ```
CSS
Include the `plyr.css` stylesheet into your `
`.
``` html <link rel = "stylesheet" href = "path/to/plyr.css" /> ```
If you want to use our CDN (provided by
Fastly ) for the default CSS, you can use the following:
``` html <link rel = "stylesheet" href = "https://cdn.plyr.io/3.7.3/plyr.css" /> ```
SVG Sprite
The SVG sprite is loaded automatically from our CDN (provided by
Fastly ). To change this, see the
options below. For
reference, the CDN hosted SVG sprite can be found at https://cdn.plyr.io/3.7.3/plyr.svg .
Ads
Plyr has partnered up with
vi.ai to offer monetization options for your videos. Getting setup is easy:
- Grab your publisher ID from the code snippet
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 ---------------------------------------------- ------------------------------------------------------------------------------------------------------- --------------------------------------------------------------------- `--plyr-color-main` The ![#f03c15](https://place-hold.it/15/00b3ff/000000?text=+) `--plyr-video-background` The `rgba(0, `--plyr-tab-focus-color` The `--plyr-color-main` `--plyr-badge-background` The ![#4a5464](https://place-hold.it/15/4a5464/000000?text=+) `--plyr-badge-text-color` The ![#ffffff](https://place-hold.it/15/ffffff/000000?text=+) `--plyr-badge-border-radius` The `2px` `--plyr-tab-focus-color` The `--plyr-color-main` `--plyr-captions-background` The `rgba(0, `--plyr-captions-text-color` The ![#ffffff](https://place-hold.it/15/ffffff/000000?text=+) `--plyr-control-icon-size` The `18px` `--plyr-control-spacing` The `10px` `--plyr-control-padding` The `--plyr-control-spacing `--plyr-control-radius` The `3px` `--plyr-control-toggle-checked-background` The `--plyr-color-main` `--plyr-video-controls-background` The `linear-gradient(rgba(0, `--plyr-video-control-color` The ![#ffffff](https://place-hold.it/15/ffffff/000000?text=+) `--plyr-video-control-color-hover` The ![#ffffff](https://place-hold.it/15/ffffff/000000?text=+) `--plyr-video-control-background-hover` The `--plyr-color-main` `--plyr-audio-controls-background` The ![#ffffff](https://place-hold.it/15/ffffff/000000?text=+) `--plyr-audio-control-color` The ![#4a5464](https://place-hold.it/15/4a5464/000000?text=+) `--plyr-audio-control-color-hover` The ![#ffffff](https://place-hold.it/15/ffffff/000000?text=+) `--plyr-audio-control-background-hover` The `--plyr-color-main` `--plyr-menu-background` The `rgba(255, `--plyr-menu-color` The ![#4a5464](https://place-hold.it/15/4a5464/000000?text=+) `--plyr-menu-shadow` The `0 `--plyr-menu-radius` The `4px` `--plyr-menu-arrow-size` The `6px` `--plyr-menu-item-arrow-color` The ![#728197](https://place-hold.it/15/728197/000000?text=+) `--plyr-menu-item-arrow-size` The `4px` `--plyr-menu-border-color` The ![#dcdfe5](https://place-hold.it/15/dcdfe5/000000?text=+) `--plyr-menu-border-shadow-color` The ![#ffffff](https://place-hold.it/15/ffffff/000000?text=+) `--plyr-progress-loading-size` The `25px` `--plyr-progress-loading-background` The `rgba(35, `--plyr-video-progress-buffered-background` The `rgba(255, `--plyr-audio-progress-buffered-background` The `rgba(193, `--plyr-range-thumb-height` The `13px` `--plyr-range-thumb-background` The ![#ffffff](https://place-hold.it/15/ffffff/000000?text=+) `--plyr-range-thumb-shadow` The `0 `--plyr-range-thumb-active-shadow-width` The `3px` `--plyr-range-track-height` The `5px` `--plyr-range-fill-background` The `--plyr-color-main` `--plyr-video-range-track-background` The `--plyr-video-progress-buffered-background` `--plyr-video-range-thumb-active-shadow-color` The `rgba(255, `--plyr-audio-range-track-background` The `--plyr-video-progress-buffered-background` `--plyr-audio-range-thumb-active-shadow-color` The `rgba(215, `--plyr-tooltip-background` The `rgba(255, `--plyr-tooltip-color` The ![#4a5464](https://place-hold.it/15/4a5464/000000?text=+) `--plyr-tooltip-padding` The `calc(var(--plyr-control-spacing) `--plyr-tooltip-arrow-size` The `4px` `--plyr-tooltip-radius` The `3px` `--plyr-tooltip-shadow` The `0 `--plyr-font-family` The | `--plyr-font-size-base` The `15px` `--plyr-font-size-small` The `13px` `--plyr-font-size-large` The `18px` `--plyr-font-size-xlarge` The `21px` `--plyr-font-size-time` The `--plyr-font-size-small` `--plyr-font-size-menu` The `--plyr-font-size-small` `--plyr-font-size-badge` The `9px` `--plyr-font-weight-regular` The `400` `--plyr-font-weight-bold` The `600` `--plyr-line-height` The `1.7` `--plyr-font-smoothing` Whether `false`
You can set them in your CSS for all players:
```css : --plyr-color-main : #1ac266; } ```
...or for a specific class name:
```css .player { --plyr-color-main : #1ac266; } ```
...or in your HTML:
``` html <video class = "player" style = "--plyr-color-main: #1ac266;" > ... </video > ```
Sass
You can use plyr.scss file included in /src/sass as part of your build and change variables to suit your design. The Sass requires you to
use
autoprefixer (you should be already!) as all declarations use the W3C definitions.
The HTML markup uses the BEM methodology with plyr as the block, e.g. .plyr__controls . You can change the class hooks in the options to match any custom CSS
you write. Check out the JavaScript source for more on this.
SVG
The icons used in the Plyr controls are loaded in an SVG sprite. The sprite is automatically loaded from our CDN by default. If you already have an icon build
system in place, you can include the source plyr icons (see /src/sprite for source icons).
Using the iconUrl option
You can however specify your own iconUrl option and Plyr will determine if the url is absolute and requires loading by AJAX/CORS due to current browser
limitations or if it's a relative path, just use the path directly.
If you're using the ` ` tag on your site, you may need to use something like this: [svgfixer.js](https://gist.github.com/leonderijke/c5cf7c5b2e424c0061d2)
Cross Origin (CORS)
You'll notice the `crossorigin` attribute on the example `` elements. This is because the TextTrack captions are loaded from another domain. If yourTextTrack captions are also hosted on another domain, you will need to add this attribute and make sure your host has the correct headers setup. For more info
on CORS checkout the MDN docs:
Captions
WebVTT captions are supported. To add a caption track, check the HTML example above and look for the `` element. Be sure to
JavaScript
Initialising
You can specify a range of arguments for the constructor to use:
- A [HTMLElement ](https://developer.mozilla.org/en/docs/Web/API/HTMLElement)
_Note_: If a
NodeList ,
Array , or jQuery object are passed, the first element will be used for setup. To setup multiple players, see
multiple players below.
Single player
Passing a CSS string selector that's compatible with [querySelector ](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector):
` ` ` js const player = new Plyr ( '#player' ) ; ` ` `
` ` ` js const player = new Plyr ( document .getElementById ( 'player' ) ) ; ` ` `
` ` ` js const player = new Plyr ( document .querySelector ( '.js-player' ) ) ; ` ` `
The HTMLElement or string selector can be the target ``, ``, or `` wrapper for embeds.
Multiple players
You have two choices here. You can either use a simple array loop to map the constructor:
` ` ` js const players = Array .from ( document .querySelectorAll ( '.js-player' ) ) .map ( ( p ) => new Plyr ( p ) ) ; ` ` `
` ` ` js const players = Plyr .setup ( '.js-player' ) ; ` ` `
Both options will also return an array of instances in the order of they were in the DOM for the string selector or the source NodeList or Array.
Options
The second argument for the constructor is the
options object:
` ` ` js const player = new Plyr ( '#player' , { title : 'Example Title' , } ) ; ` ` `
Options can be passed as an object to the constructor as above or as JSON in data-plyr-config attribute on each of your target elements:
``` html <video src = "/path/to/video.mp4" id = "player" controls data-plyr-config = '{ " title ": " Example Title " }' > </video > ```
Note the single quotes encapsulating the JSON and double quotes on the object keys. Only string values need double quotes.
Option Type Default Description -------------------- -------------------------- ------------------------------------------------------------------------------------------------------------------------------ ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- `enabled` Boolean `true` Completely `debug` Boolean `false` Display `controls` Array, `['play-large', If `settings` Array `['captions', If `i18n` Object See Used `loadSprite` Boolean `true` Load `iconUrl` String `null` Specify `iconPrefix` String `plyr` Specify `blankVideo` String `https://cdn.plyr.io/static/blank.mp4` Specify `autoplay`² Boolean `false` Autoplay `autopause`¹ Boolean `true` Only `seekTime` Number `10` The `volume` Number `1` A `muted` Boolean `false` Whether `clickToPlay` Boolean `true` Click `disableContextMenu` Boolean `true` Disable `hideControls` Boolean `true` Hide `resetOnEnd` Boolean false Reset `keyboard` Object `{ Enable `tooltips` Object `{ `controls`: `duration` Number `null` Specify `displayDuration` Boolean `true` Displays `invertTime` Boolean `true` Display `toggleInvert` Boolean `true` Allow `listeners` Object `null` Allows `captions` Object `{ `active`: `fullscreen` Object `{ `enabled`: `ratio` String `null` Force `storage` Object `{ `enabled`: `speed` Object `{ `selected`: `quality` Object `{ `default` `loop` Object `{ `active`: `ads` Object `{ `enabled`: `urls` Object See If `vimeo` Object `{ See `youtube` Object `{ See `previewThumbnails` Object `{ `enabled`: `mediaMetadata` Object `{ The `markers` Object `{ `enabled`:
1. Vimeo only
2. Autoplay is generally not recommended as it is seen as a negative user experience. It is also disabled in many browsers. Before raising issues, do your homework. More info can be found here:
- https://webkit.org/blog/6784/new-video-policies-for-ios/
- https://developers.google.com/web/updates/2017/09/autoplay-policy-changes
- https://hacks.mozilla.org/2019/02/firefox-66-to-block-automatically-playing-audible-video-and-audio/
API
There are methods, setters and getters on a Plyr object.
Object
The easiest way to access the Plyr object is to set the return value from your call to the constructor to a variable. For example:
` ` ` js const player = new Plyr ( '#player' , { /* options */ } ) ; ` ` `
You can also access the object through any events:
` ` ` js element .addEventListener ( 'ready' , ( event ) => { const player = event .detail .plyr ; } ) ; ` ` `
Methods
Example method use:
` ` ` js player .play ( ) ; // Start playback player .fullscreen .enter ( ) ; // Enter fullscreen ` ` `
Method Parameters Description -------------------------------------------------------- ---------------- ---------------------------------------------------------------------------------------------------------- `play()`¹ - Start `pause()` - Pause `togglePlay(toggle)`¹ Boolean Toggle `stop()` - Stop `restart()` - Restart `rewind(seekTime)` Number Rewind `forward(seekTime)` Number Fast `increaseVolume(step)` Number Increase `decreaseVolume(step)` Number Increase `toggleCaptions(toggle)` Boolean Toggle `fullscreen.enter()` - Enter `fullscreen.exit()` - Exit `fullscreen.toggle()` - Toggle `airplay()` - Trigger `setPreviewThumbnails(source: - Sets `toggleControls(toggle)` Boolean Toggle `on(event, String, Add `once(event, String, Add `off(event, String, Remove `supports(type)` String Check `destroy()` - Destroy
1. For HTML5 players,
play() will return a [
Promise ](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) for most browsers - e.g. Chrome, Firefox, Opera, Safari and Edge
according to MDN at time of writing.
Getters and Setters
Example setters:
` ` ` js player .volume = 0 .5 ; // Sets volume at 50% player .currentTime = 10 ; // Seeks to 10 seconds ` ` `
Example getters:
` ` ` js player .volume ; // 0.5; player .currentTime ; // 10 player .fullscreen .active ; // false; ` ` `
Property Getter Setter Description -------------------- ------ ------ -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- `isHTML5` ✓ - Returns `isEmbed` ✓ - Returns `playing` ✓ - Returns `paused` ✓ - Returns