diff options
Diffstat (limited to 'readme.md')
| -rw-r--r-- | readme.md | 88 |
1 files changed, 62 insertions, 26 deletions
@@ -3,14 +3,14 @@ A simple, accessible HTML5 media player. [Checkout the demo](http://plyr.io) -[](http://plyr.io) +[](http://plyr.io) ## Why? We wanted a lightweight, accessible and customisable media player that just supports *modern* 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 captions and screen readers. -- **Lightweight** - just 5.7KB minified and gzipped. +- **Lightweight** - just 6.4KB minified and gzipped. - **Customisable** - make the player look how you want with the markup you want. - **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. @@ -25,11 +25,10 @@ Oh and yes, it works with Bootstrap. Check out [the changelog](changelog.md) ## Planned development -- Accept a string selector, a node, or a nodelist for the `container` property of `selectors`. -- Multiple language captions (with selection) - Playlists (audio and video) -- Set source by API -- Tooltip option (for seeking and controls) +- YouTube and Vimeo support +- Playback speed +- Multiple language captions (with selection) ... and whatever else has been raised in [issues](https://github.com/Selz/plyr/issues) If you have any cool ideas or features, please let me know by [creating an issue](https://github.com/Selz/plyr/issues/new) or of course, forking and sending a pull request. @@ -38,7 +37,7 @@ If you have any cool ideas or features, please let me know by [creating an issue 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.0.24/plyr.js` to `https://cdn.plyr.io/1.0.24/plyr.js` +**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.1.5/plyr.js` to `https://cdn.plyr.io/1.1.5/plyr.js` ### Bower If bower is your thang, you can grab Plyr using: @@ -47,15 +46,22 @@ bower install plyr ``` More info on setting up dependencies can be found in the [Bower Docs](http://bower.io/docs/creating-packages/#maintaining-dependencies) +### Ember +The awesome [@louisrudner](https://twitter.com/louisrudner) has created an ember component, available by running: +``` +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 If you want to use our CDN, you can use the following. HTTPS (SSL) is supported. ```html -<link rel="stylesheet" href="//cdn.plyr.io/1.0.24/plyr.css"> -<script src="//cdn.plyr.io/1.0.24/plyr.js"></script> +<link rel="stylesheet" href="//cdn.plyr.io/1.1.5/plyr.css"> +<script src="//cdn.plyr.io/1.1.5/plyr.js"></script> ``` -You can also access the `sprite.svg` file at `//cdn.plyr.io/1.0.24/sprite.svg`. +You can also access the `sprite.svg` file at `//cdn.plyr.io/1.1.5/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. @@ -130,21 +136,17 @@ You'll notice the `crossorigin` attribute on the example `<video>` and `<audio>` 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. Below is an example of a default instance. +### JavaScript +Much of the behaviour of the player is configurable when initialising the library. Here's an example of a default setup: ```html <script src="dist/plyr.js"></script> -<script> -plyr.setup({ - *options* -}); -</script> +<script>plyr.setup();</script> ``` #### Options -You can pass the following options to the setup method. +You can pass the following options to the setup method using `plyr.setup({...})`. <table class="table" width="100%"> <thead> @@ -169,6 +171,12 @@ You can pass the following options to the setup method. <td>See <a href="controls.md">controls.md</a> for more info on how the html needs to be structured.</td> </tr> <tr> + <td><code>controls</code></td> + <td>Array</td> + <td><code>["restart", "rewind", "play", "fast-forward", "current-time", "duration", "mute", "volume", "captions", "fullscreen"]</code></td> + <td>Toggle which control elements you would like to display when using the default controls html. If you specify a <code>html</code> option, this is redundant. The default value is to display everything.</td> + </tr> + <tr> <td><code>debug</code></td> <td>Boolean</td> <td><code>false</code></td> @@ -198,6 +206,12 @@ You can pass the following options to the setup method. <td><code>false</code></td> <td>Display control labels as tooltips on :hover & :focus (by default, the labels are screen reader only).</td> </tr> + <tr> + <td><code>displayDuration</code></td> + <td>Boolean</td> + <td><code>true</code></td> + <td>Displays the duration of the media on the "metadataloaded" event (on startup) in the current time display. This will only work if the `preload` attribute is not set to `none` (or is not set at all) and you choose not to display the duration (see <code>controls</code> option).</td> + </tr> <tr> <td><code>selectors</code></td> <td>Object</td> @@ -220,7 +234,7 @@ You can pass the following options to the setup method. <td><code>fullscreen</code></td> <td>Object</td> <td>—</td> - <td>Two properties; <code>enabled</code> which toggles if fullscreen should be enabled (if the browser supports it). The default value is <code>true</code>. Also an extra property called <code>fallback</code> which will enable a full window view for older browsers. The default value is <code>true</code>.</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> </tr> <tr> <td><code>storage</code></td> @@ -228,6 +242,12 @@ You can pass the following options to the setup method. <td>—</td> <td>Two properties; <code>enabled</code> which toggles if local storage should be enabled (if the browser supports it). The default value is `true`. This enables storing user settings, currently it only stores volume but more will be added later. The second property <code>key</code> is the key used for the local storage. The default is <code>plyr_volume</code> until more settings are stored.</td> </tr> + <tr> + <td><code>onSetup</code></td> + <td>Function</td> + <td>—</td> + <td>This callback function is called on every new plyr instance created. The context (<code>this</code>) is the plyr instance itself.</td> + </tr> </tbody> </table> @@ -296,6 +316,16 @@ Here's a list of the methods supported: <td>Toggles whether captions are enabled.</td> </tr> <tr> + <td><code>toggleFullscreen()</code></td> + <td>Event</td> + <td>Toggles fullscreen. This can only be initiated by a user gesture due to browser security, i.e. a user event such as click.</td> + </tr> + <tr> + <td><code>isFullscreen()</code></td> + <td>—</td> + <td>Boolean returned if the player is in fullscreen.</td> + </tr> + <tr> <td><code>support(...)</code></td> <td>String</td> <td>Determine if a player supports a certain MIME type.</td> @@ -315,7 +345,7 @@ Here's a list of the methods supported: 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. </td> </tr> - <tr> + <tr> <td><code>poster(...)</code></td> <td>String</td> <td>Set the poster url. This is supported for the <code>video</code> element only.</td> @@ -338,11 +368,12 @@ A complete list of events can be found here: [Media Events - W3.org](http://www.w3.org/2010/05/video/mediaevents.html) ## 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. ## Browser support -<table width="100%" style="text-align: center;"> +<table width="100%" style="text-align: center"> <thead> <tr> <td>Safari</td> @@ -359,15 +390,15 @@ Fullscreen in Plyr is supported for all browsers that [currently support it](htt <td>✔</td> <td>✔</td> <td>✔</td> - <td>✖²</td> + <td>API²</td> <td>✔³</td> </tr> </tbody> </table> -¹ iPhone forces the native player for `<video>` so no customisation possible +¹ Mobile Safari on the iPhone forces the native player for `<video>` so no useful customisation is possible. `<audio>` elements have volume controls disabled. -² Native player used (no support for `<progress>` or `<input type="range">`) +² Native player used (no support for `<progress>` or `<input type="range">`) but the API is supported (v1.0.28+) ³ IE10 has no native fullscreen support, fallback can be used (see options) @@ -380,19 +411,24 @@ 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. + ## Issues If you find anything weird with Plyr, please let us know using the GitHub issues tracker. ## Author -Plyr is developed by Sam Potts ([@sam_potts](https://twitter.com/sam_potts)) ([sampotts.me](http://sampotts.me)) +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/) - [HTML5 Weekly #177](http://html5weekly.com/issues/177) +- [Responsive Design #149](http://us4.campaign-archive2.com/?u=559bc631fe5294fc66f5f7f89&id=451a61490f) - [Web Design Weekly #174](https://web-design-weekly.com/2015/02/24/web-design-weekly-174/) - [Hacker News](https://news.ycombinator.com/item?id=9136774) - [Web Platform Daily](http://webplatformdaily.org/releases/2015-03-04) - [LayerVault Designer News](https://news.layervault.com/stories/45394-plyr--a-simple-html5-media-player) +- [The Treehouse Show #131](https://teamtreehouse.com/library/episode-131-origami-react-responsive-hero-images) ## Used by - [Selz.com](https://selz.com) @@ -410,4 +446,4 @@ Also these links helped created Plyr: - [Styling the `<progress>` element - hongkiat.com](http://www.hongkiat.com/blog/html5-progress-bar/) ## Copyright and License -[The MIT license](license.md).
\ No newline at end of file +[The MIT license](license.md). |