diff options
Diffstat (limited to 'readme.md')
| -rw-r--r-- | readme.md | 306 |
1 files changed, 253 insertions, 53 deletions
@@ -1,12 +1,12 @@ # Plyr -A simple, accessible HTML5 media player. +A simple, accessible HTML5 media player. Checkout the [demo](http://plyr.io). [](http://plyr.io) ## Why? -We wanted a lightweight, accessible and customisable media player that just supports [*modern*](#browser-support) browsers. Sure, there are many other players out there but we wanted to keep things simple, using the right elements for the job. +We wanted a lightweight, accessible and customizable media player that just supports [*modern*](#browser-support) browsers. Sure, there are many other players out there but we wanted to keep things simple, using the right elements for the job. ## Features - **Accessible** - full support for VTT captions and screen readers. @@ -15,19 +15,18 @@ We wanted a lightweight, accessible and customisable media player that just supp - **Semantic** - uses the *right* elements. `<input type="range">` for volume and `<progress>` for progress and well, `<button>`s for buttons. There's no `<span>` or `<a href="#">` button hacks. - **Responsive** - as you'd expect these days. - **Audio & Video** - support for both formats. -- **[Embedded Video](#embeds)** - support for YouTube (Vimeo soon). +- **[Embedded Video](#embeds)** - support for YouTube and Vimeo (beta). - **[API](#api)** - toggle playback, volume, seeking, and more. - **[Fullscreen](#fullscreen)** - supports native fullscreen with fallback to "full window" modes. - **i18n support** - support for internationalization of controls. -- **No dependencies** - written in vanilla JavaScript, no jQuery required. +- **No dependencies** - written in vanilla JavaScript, no jQuery required. -Oh and yes, it works with Bootstrap. +Oh and yes, it works with Bootstrap. ## Changelog -Check out the [changelog](changelog.md). +Check out the [changelog](changelog.md) to see what's been new with Plyr. ## Planned Development -- Vimeo support - Playback speed - Playlists - Multiple language captions (with selection) @@ -38,7 +37,7 @@ If you have any cool ideas or features, please let me know by [creating an issue ## Implementation -Check `docs/index.html` and `docs/dist/docs.js` for an example setup. +Check `docs/index.html` and `docs/dist/docs.js` for an example setup. **Heads up:** the example `index.html` file needs to be served from a webserver (such as Apache, Nginx, IIS or similar) unless you change the file sources to include http or https. e.g. change `//cdn.plyr.io/1.3.7/plyr.js` to `https://cdn.plyr.io/1.3.7/plyr.js` @@ -56,7 +55,7 @@ ember addon:install ember-cli-plyr ``` More info is on [npm](https://www.npmjs.com/package/ember-cli-plyr) and [GitHub](https://github.com/louisrudner/ember-cli-plyr) -### CDN +### CDN If you want to use our CDN, you can use the following: ```html @@ -66,13 +65,15 @@ If you want to use our CDN, you can use the following: You can also access the `sprite.svg` file at `https://cdn.plyr.io/1.3.7/sprite.svg`. -### CSS -If you want to use the default css, add the `plyr.css` file from `/dist` into your head, or even better use `plyr.less` or `plyr.sass` file included in `/src` in your build to save a request. +### CSS & Styling +If you want to use the default css, add the `plyr.css` file from `/dist` into your head, or even better use `plyr.less` or `plyr.sass` file included in `/src` in your build to save a request. ```html <link rel="stylesheet" href="dist/plyr.css"> ``` +The default setup uses the BEM methodology with `plyr` as the block, e.g. `.plyr__controls`. You can change the class hooks in the options. Check out the source for more on this. + ### SVG The SVG sprite for the controls icons is loaded in by AJAX to help with performance. This is best added before the closing `</body>`, before any other scripts. @@ -92,68 +93,99 @@ The SVG sprite for the controls icons is loaded in by AJAX to help with performa })(document, "dist/sprite.svg"); </script> ``` + +If you're using the `<base>` tag on your site, you may need to use something like this: +[https://gist.github.com/leonderijke/c5cf7c5b2e424c0061d2](svgfixer.js) + More info on SVG sprites here: -[http://css-tricks.com/svg-sprites-use-better-icon-fonts/](http://css-tricks.com/svg-sprites-use-better-icon-fonts/) -and the AJAX technique here: +[http://css-tricks.com/svg-sprites-use-better-icon-fonts/](http://css-tricks.com/svg-sprites-use-better-icon-fonts/) +and the AJAX technique here: [http://css-tricks.com/ajaxing-svg-sprite/](http://css-tricks.com/ajaxing-svg-sprite/) ### HTML The only extra markup that's needed to use plyr is a `<div>` wrapper. Replace the source, poster and captions with urls for your media. ```html -<div class="player"> - <video poster="https://cdn.selz.com/plyr/1.0/poster.jpg" controls crossorigin> +<div class="plyr"> + <video poster="/path/to/poster.jpg" controls> <!-- Video files --> - <source src="https://cdn.selz.com/plyr/1.0/movie.mp4" type="video/mp4"> - <source src="https://cdn.selz.com/plyr/1.0/movie.webm" type="video/webm"> - + <source src="/path/to/video.mp4" type="video/mp4"> + <source src="/path/to/video.webm" type="video/webm"> + <!-- Text track file --> - <track kind="captions" label="English captions" src="https://cdn.selz.com/plyr/1.0/movie_captions_en.vtt" srclang="en" default> - + <track kind="captions" label="English captions" src="/path/to/captions.vtt" srclang="en" default> + <!-- Fallback for browsers that don't support the <video> element --> - <a href="https://cdn.selz.com/plyr/1.0/movie.mp4">Download</a> + <a href="/path/to/movie.mp4">Download</a> </video> </div> ``` And the same for `<audio>` ```html -<div class="player"> +<div class="plyr"> <audio controls> <!-- Audio files --> - <source src="https://cdn.selz.com/plyr/1.0/logistics-96-sample.mp3" type="audio/mp3"> - <source src="https://cdn.selz.com/plyr/1.0/logistics-96-sample.ogg" type="audio/ogg"> - + <source src="/path/to/audio.mp3" type="audio/mp3"> + <source src="/path/to/audio.ogg" type="audio/ogg"> + <!-- Fallback for browsers that don't support the <audio> element --> - <a href="https://cdn.selz.com/plyr/1.0/logistics-96-sample.mp3">Download</a> + <a href="/path/to/audio.mp3">Download</a> </audio> </div> -``` +``` For YouTube, Plyr uses the standard YouTube API markup (an empty `<div>`): ```html -<div class="player"> +<div class="plyr"> <div data-video-id="L1h9xxCU20g" data-type="youtube"></div> </div> ``` #### Cross Origin (CORS) -You'll notice the `crossorigin` attribute on the example `<video>` and `<audio>` elements. This is because the media is loaded from another domain. If your media is hosted on another domain, you may need to add this attribute. +You'll notice the `crossorigin` attribute on the example `<video>` and `<audio>` elements. This is because the media is loaded from another domain. If your media is hosted on another domain, you may need to add this attribute. More info on CORS here: [https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS) ### JavaScript -Much of the behaviour of the player is configurable when initialising the library. Here's an example of a default setup: + +#### Quick setup + +Here's an example of a default setup: ```html -<script src="dist/plyr.js"></script> +<script src="https://cdn.plyr.io/1.3.5/plyr.js"></script> <script>plyr.setup();</script> ``` +This will look for all elements with the specified container classname (default is `plyr`) and setup plyr on each element found. You can specify other options, including a different selector hook below. The container classname will be added to the specified element(s) if it is not already present (for the CSS). + +You can initialize the player a few other ways: + +Passing a [NodeList](https://developer.mozilla.org/en-US/docs/Web/API/NodeList): +```javascript +plyr.setup(document.querySelectorAll('.js-plyr'), options); +``` + +Passing a [HTMLElement](https://developer.mozilla.org/en/docs/Web/API/HTMLElement): +```javascript +plyr.setup(document.querySelector('.js-plyr'), options); +``` + +Passing a [string selector](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelectorAll): +```javascript +plyr.setup('.js-plyr', options); +``` + +Passing just the options object: +```javascript +plyr.setup(options); +``` + #### Options -You can pass the following options to the setup method using `plyr.setup({...})`. +Options must be passed as an object to the `setup()` method as above. <table class="table" width="100%"> <thead> @@ -169,7 +201,7 @@ You can pass the following options to the setup method using `plyr.setup({...})` <td><code>enabled</code></td> <td>Boolean</td> <td><code>true</code></td> - <td>Completely disable Plyr. This would allow you to do a User Agent check or similar to programatically enable or disable Plyr for a certain UA. Example below.</td> + <td>Completely disable Plyr. This would allow you to do a User Agent check or similar to programmatically enable or disable Plyr for a certain UA. Example below.</td> </tr> <tr> <td><code>html</code></td> @@ -187,7 +219,7 @@ You can pass the following options to the setup method using `plyr.setup({...})` <td><code>i18n</code></td> <td>Object</td> <td><code><a href="controls.md">See controls.md</a></code></td> - <td>Used for internationalisation (i18n) of the tooltips/labels within the buttons.</td> + <td>Used for internationalization (i18n) of the tooltips/labels within the buttons.</td> </tr> <tr> <td><code>iconPrefix</code></td> @@ -235,7 +267,7 @@ You can pass the following options to the setup method using `plyr.setup({...})` <td><code>selectors</code></td> <td>Object</td> <td>—</td> - <td>See <code>plyr.js</code> in <code>/src</code> for more info. The only option you might want to change is <code>player</code> which is the hook used for Plyr, the default is <code>.player</code>.</td> + <td>See <code>plyr.js</code> in <code>/src</code> for more info. You probably don't need to change any of these.</td> </tr> <tr> <td><code>classes</code></td> @@ -253,7 +285,7 @@ You can pass the following options to the setup method using `plyr.setup({...})` <td><code>fullscreen</code></td> <td>Object</td> <td>—</td> - <td>Three properties; <code>enabled</code> which toggles if fullscreen should be enabled (if the browser supports it). The default value is <code>true</code>. A <code>fallback</code> property which will enable a full window view for older browsers. The default value is <code>true</code>. A <code>hideControls</code> property which will hide the controls when fullscreen is active and the video is playing, after 1s. The controls reappear on hover of the progress bar (mouse), focusing a child control or pausing the video (by tap/click of video if `click` is `true`). The default value is <code>true</code>.</td> + <td>See <a href="#fullscreen-options">below</a></td> </tr> <tr> <td><code>storage</code></td> @@ -270,12 +302,68 @@ You can pass the following options to the setup method using `plyr.setup({...})` </tbody> </table> +#### Fullscreen options + +<table class="table" width="100%" id="fullscreen-options"> +<thead> + <tr> + <th width="20%">Option</th> + <th width="15%">Type</th> + <th width="15%">Default</th> + <th width="50%">Description</th> + </tr> + </thead> + <tbody> + <tr> + <td><code>enabled</code></td> + <td>Boolean</td> + <td><code>true</code></td> + <td>Toggles if fullscreen should be enabled (if the browser supports it).</td> + </tr> + <tr> + <td><code>fallback</code></td> + <td>Boolean</td> + <td><code>true</code></td> + <td>Enable a full viewport view for older browsers.</td> + </tr> + <tr> + <td><code>hideControls</code></td> + <td>Boolean</td> + <td><code>true</code></td> + <td>Hide the controls when fullscreen is active and the video is playing, after 1s. The controls reappear on hover of the progress bar (mouse), focusing a child control or pausing the video (by tap/click of video if `click` is `true`).</td> + </tr> + <tr> + <td><code>allowAudio</code></td> + <td>Boolean</td> + <td><code>false</code></td> + <td>Allow audio play to toggle fullscreen. This will be more useful later when posters are supported.</td> + </tr> + </tbody> +</table> + ## API -A `plyr` object is added to any element that Plyr is initialised on. You can then control the player by accessing methods in the `plyr` object. For example if you wanted to pause Plyr: +#### Fetching the plyr instance +A `plyr` object is added to any element that Plyr is initialized on. You can then control the player by accessing methods in the `plyr` object. + +There are two ways to access the instance, firstly you re-query the element container you used for setup (e.g. `.js-plyr`) like so: + +```javascript +var player = document.querySelector('.js-plyr'); +``` + +Or you can use the returned object from your call to the setup method: + +```javascript +var player = plyr.setup('.js-plyr')[0]; +``` + +This will return an array of plyr instances setup, so you need to specify the index of the instance you want. This is less useful if you are setting up mutliple instances. You can also use the `onSetup` callback documented below which will return each instance one by one, as they are setup. + +Once you have your instance, you can use the API methods below on it. For example to pause it: ```javascript -document.querySelectorAll(".player")[0].plyr.pause(); +player.pause(); ``` Here's a list of the methods supported: @@ -287,8 +375,8 @@ Here's a list of the methods supported: <th width="15%">Parameters</th> <th width="65%">Description</th> </tr> - </thead> - <tbody> +</thead> +<tbody> <tr> <td><code>play()</code></td> <td>—</td> @@ -356,7 +444,7 @@ Here's a list of the methods supported: </tr> <tr> <td><code>source(...)</code></td> - <td>String or Array or (null|undefined)</td> + <td>Array or (null|undefined)</td> <td> Get/Set the media source. <br><br> @@ -366,7 +454,7 @@ Here's a list of the methods supported: <br><br> <strong>array</strong><br> <code>.source([{ src: "/path/to/video.webm", type: "video/webm", ...more attributes... }, { src: "/path/to/video.mp4", type: "video/mp4", ...more attributes... }])`</code><br> - This will inject a child `source` element for every element in the array with the specified attributes. `src` is the only required attribute although adding `type` is recommended as it helps the browser decide which file to download and play. + This will inject a child `source` element for every element in the array with the specified attributes. `src` is the only required attribute although adding `type` is recommended as it helps the browser decide which file to download and play. <br><br> <strong>YouTube</strong><br> Currently this API method only accepts a YouTube ID when used with a YouTube player. I will add URL support soon, along with being able to swap between types (e.g. YouTube to Audio or Video and vice versa.) @@ -393,14 +481,126 @@ Here's a list of the methods supported: </tbody> </table> +#### .source() method + +This allows changing the plyr source and type on the fly. + +Video example: + +```javascript +player.source({ + type: 'video', + title: 'Example title', + sources: [{ + src: '/path/to/movie.mp4', + type: 'video/mp4' + }, + { + src: '/path/to/movie.webm', + type: 'video/webm' + }], + poster: '/path/to/poster.jpg', + tracks: [{ + kind: 'captions', + label: 'English', + srclang:'en', + src: '/path/to/captions.vtt', + default: true + }] +}); +``` + +Audio example: + +```javascript +player.source({ + type: 'audio', + title: 'Example title', + sources: [{ + src: '/path/to/audio.mp3', + type: 'audio/mp3' + }, + { + src: '/path/to/audio.ogg', + type: 'audio/ogg' + }] +}); +``` + +YouTube example: + +```javascript +player.source({ + type: 'video', + title: 'Example title', + sources: [{ + src: 'bTqVqk7FSmY', + type: 'youtube' + }] +}); +``` + +Vimeo example + +```javascript +player.source({ + type: 'video', + title: 'Example title', + sources: [{ + src: '143418951', + type: 'vimeo' + }] +}); +``` + +Some more details on the object parameters + +<table class="table" width="100%"> + <thead> + <tr> + <th width="20%">Key</th> + <th width="15%">Type</th> + <th width="65%">Description</th> + </tr> + </thead> + <tbody> + <tr> + <td><code>type</code></td> + <td>String</td> + <td>Options are <code>video</code>, <code>audio</code>, <code>youtube</code> and <code>vimeo</code></td> + </tr> + <tr> + <td><code>title</code></td> + <td>String</td> + <td>Title of the new media. Used for the aria labelling.</td> + </tr> + <tr> + <td><code>sources</code></td> + <td>Array or String</td> + <td>This is an array of sources or optionally a string for embedded players (YouTube and Vimeo). `type` is also optional for YouTube and Vimeo when specifying an array. For YouTube and Vimeo media, only the video ID must be passed as the source as shown above. The keys of this object are mapped directly to HTML attributes so more can be added to the object if required.</td> + </tr> + <tr> + <td><code>poster</code></td> + <td>String</td> + <td>URL for the poster image (video only).</td> + </tr> + <tr> + <td><code>tracks</code></td> + <td>Array</td> + <td>An array of track objects. Each element in the array is mapped directly to a track element and any keys mapped directly to HTML attributes so as in the example above, it will render as `<track kind="captions" label="English" srclang="en" src="https://cdn.selz.com/plyr/1.0/example_captions_en.vtt" default>`. Booleans are converted to HTML5 value-less attributes.</td> + </tr> + </tbody> +</table> + + ## Events/Callbacks The `plyr` object on the player element also contains a `media` property which is a reference to the `<audio>` or `<video>` element within the player which you can use to listen for events. Here's an example: ```javascript -var media = document.querySelectorAll(".player")[0].plyr.media; +var media = document.querySelector(".plyr").plyr.media; -media.addEventListener("playing", function() { +media.addEventListener("playing", function() { console.log("playing"); }); ``` @@ -418,18 +618,18 @@ Currently only YouTube is supported. Vimeo will be coming soon. Some HTML5 media Due to the way the YouTube API works, the `timeupdate` and `progress` events are triggered by polling every 200ms so the event may trigger without an actual value change. Buffering progress is `media.buffered` in the `plyr` object. It is a a number between 0 and 1 that specifies the percentage of the video that the player shows as buffered. ```javascript -document.querySelector(".player").plyr.media.addEventListener("play", function() { +document.querySelector(".plyr").plyr.media.addEventListener("play", function() { console.log("play"); }); -``` +``` -The `.source()` API method can also be used but the video id must be passed as the argument. +The `.source()` API method can also be used but the video id must be passed as the argument. -Currently caption control is not supported but I will work on this. +Currently caption control is not supported but I will work on this. ## Fullscreen -Fullscreen in Plyr is supported for all browsers that [currently support it](http://caniuse.com/#feat=fullscreen). If you're using the default CSS, you can also use a "full browser" mode which will use the full browser window by adding the `player-fullscreen` class to your container. +Fullscreen in Plyr is supported for all browsers that [currently support it](http://caniuse.com/#feat=fullscreen). If you're using the default CSS, you can also use a "full browser" mode which will use the full browser window by adding the `plyr-fullscreen` class to your container. ## Browser support @@ -462,7 +662,7 @@ Fullscreen in Plyr is supported for all browsers that [currently support it](htt ³ IE10 has no native fullscreen support, fallback can be used (see options) -The `enabled` option can be used to disable certain User Agents. For example, if you don't want to use Plyr for smartphones, you could use: +The `enabled` option can be used to disable certain User Agents. For example, if you don't want to use Plyr for smartphones, you could use: ```javascript enabled: /Android|webOS|iPhone|iPad|iPod|BlackBerry/i.test(navigator.userAgent) @@ -472,13 +672,13 @@ If a User Agent is disabled but supports `<video>` and `<audio>` natively, it wi Any unsupported browsers will display links to download the media if the correct html is used. ### Checking for support -There's an API method for checking support. You can call `plyr.supported()` and optionally pass a type to it, e.g. `plyr.supported("video")`. It will return an object with two keys; `basic` meaning there's basic support for that media type (or both if no type is passed) and `full` meaning there's full support for plyr. +There's an API method for checking support. You can call `plyr.supported()` and optionally pass a type to it, e.g. `plyr.supported("video")`. It will return an object with two keys; `basic` meaning there's basic support for that media type (or both if no type is passed) and `full` meaning there's full support for plyr. ## Issues If you find anything weird with Plyr, please let us know using the GitHub issues tracker. ## Author -Plyr is developed by [@sam_potts](https://twitter.com/sam_potts) / [sampotts.me](http://sampotts.me) with help from the awesome [contributors](https://github.com/Selz/plyr/graphs/contributors) +Plyr is developed by [@sam_potts](https://twitter.com/sam_potts) / [sampotts.me](http://sampotts.me) with help from the awesome [contributors](https://github.com/Selz/plyr/graphs/contributors) ## Mentions - [The Changelog](http://thechangelog.com/plyr-simple-html5-media-player-custom-controls-webvtt-captions/) @@ -493,7 +693,7 @@ Plyr is developed by [@sam_potts](https://twitter.com/sam_potts) / [sampotts.me] ## Used by - [Selz.com](https://selz.com) -Let me know on [Twitter](https://twitter.com/sam_potts) I can add you to the above list. It'd be awesome to see how you're using Plyr :-) +Let me know on [Twitter](https://twitter.com/sam_potts) I can add you to the above list. It'd be awesome to see how you're using Plyr :-) ## Useful links and credits Credit to the PayPal HTML5 Video player from which Plyr's caption functionality is ported from: |