aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--readme.md104
1 files changed, 45 insertions, 59 deletions
diff --git a/readme.md b/readme.md
index 03b3f53e..9210de10 100644
--- a/readme.md
+++ b/readme.md
@@ -1,4 +1,6 @@
-# This branch is not production ready. There will be bugs.
+<aside class="notice">
+This branch is currently in beta and not production-ready.
+</aside>
# Plyr
A simple, accessible and customizable HTML5, YouTube and Vimeo media player.
@@ -7,26 +9,26 @@ A simple, accessible and customizable HTML5, YouTube and Vimeo media player.
[Checkout the demo](https://plyr.io)
-[![Image of Plyr](https://cdn.selz.com/plyr/plyr_v1.8.9.png)](https://plyr.io)
+[![Image of Plyr](https://cdn.plyr.io/static/demo/screenshot.png)](https://plyr.io)
## Why?
We wanted a lightweight, accessible and customizable media player that 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
-- **Lightweight** - under 10KB minified and gzipped
+- **Lightweight** - just 18KB minified and gzipped
- **[Customisable](#html)** - 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** - works with any screen size
- **HTML Video & Audio** - support for both formats
- **[Embedded Video](#embeds)** - support for YouTube and Vimeo video playback
- **[Streaming](#streaming)** - support for hls.js, Shaka and dash.js streaming playback
-- **[API](#api)** - toggle playback, volume, seeking, and more
+- **[API](#api)** - toggle playback, volume, seeking, and more through a standardized API
- **[Events](#events)** - no messing around with Vimeo and YouTube APIs, all events are standardized across formats
- **[Fullscreen](#fullscreen)** - supports native fullscreen with fallback to "full window" modes
- **[Shortcuts](#shortcuts)** - supports keyboard shortcuts
- **i18n support** - support for internationalization of controls
-- **No dependencies** - written in "vanilla" JavaScript, no jQuery required
+- **No dependencies** - written in "vanilla" ES6 JavaScript, no jQuery required
- **SASS and LESS** - to include in your build processes
Oh and yes, it works with Bootstrap.
@@ -35,17 +37,12 @@ Oh and yes, it works with Bootstrap.
Check out the [changelog](changelog.md) to see what's new with Plyr.
## Features currently being developed
-- Playback speed selection
-- Quality selection
-- Caption language selection
-- AirPlay
-- Picture in Picture (MacOS Sierra + Safari)
-
-[more info](https://github.com/sampotts/plyr/issues?q=is%3Aissue+is%3Aopen+label%3A%22In+Development%22)
+- Support for VAST and VPAID ads
+- ...[and more](https://github.com/sampotts/plyr/issues?q=is%3Aissue+is%3Aopen+label%3A%22In+Development%22)
## Planned features
- Playlists
-- Google cast
+- Google cast support
- Facebook video support
- Wistia video support
- YouTube and Vimeo audio support
@@ -97,7 +94,7 @@ Plyr extends upon the standard HTML5 markup so that's all you need for those typ
#### HTML5 Video
```html
-<video poster="/path/to/poster.jpg" controls>
+<video poster="/path/to/poster.jpg" id="player" controls>
<source src="/path/to/video.mp4" type="video/mp4">
<source src="/path/to/video.webm" type="video/webm">
<!-- Captions are optional -->
@@ -107,7 +104,7 @@ Plyr extends upon the standard HTML5 markup so that's all you need for those typ
#### HTML5 Audio
```html
-<audio controls>
+<audio id="player" controls>
<source src="/path/to/audio.mp3" type="audio/mp3">
<source src="/path/to/audio.ogg" type="audio/ogg">
</audio>
@@ -117,14 +114,14 @@ For YouTube and Vimeo, Plyr uses the standard YouTube API markup (an empty `<div
#### YouTube embed
```html
-<div data-type="youtube" data-video-id="bTqVqk7FSmY"></div>
+<div id="player" data-type="youtube" data-video-id="bTqVqk7FSmY"></div>
```
Note: `data-video-id` value can now be the ID or URL for the video. This attribute name will change in a future release to reflect this change.
#### Vimeo embed
```html
-<div data-type="vimeo" data-video-id="143418951"></div>
+<div id="player" data-type="vimeo" data-video-id="143418951"></div>
```
Note: `data-video-id` value can now be the ID or URL for the video. This attribute name will change in a future release to reflect this change.
@@ -133,7 +130,7 @@ Include the `plyr.js` script before the closing `</body>` tag and then call `ply
```html
<script src="path/to/plyr.js"></script>
-<script>plyr.setup();</script>
+<script>var player = new Plyr('#player')</script>
```
If you want to use our CDN (provided by [Fastly](https://www.fastly.com/)) for the JavaScript, you can use the following:
@@ -190,51 +187,51 @@ WebVTT captions are supported. To add a caption track, check the HTML example ab
#### Initialising
-By default, `setup()` will find all `<video>`, `<audio>` and `[data-type]` elements with the document and initialises on any found. Each target media element found will be wrapped in a `<div>` for styling and setup individually. You can specify a variety of arguments to `setup()` to use, including a different NodeList, HTMLElement, Array of HTMLElements or string selector as below:
+You can specify a range of arguments for the constructor to use:
+
+- A CSS string selector that's compatible with [`querySelector`](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector)
+- A [HTMLElement](https://developer.mozilla.org/en/docs/Web/API/HTMLElement)
+- A [NodeList](https://developer.mozilla.org/en-US/docs/Web/API/NodeList) or Array of [HTMLElement](https://developer.mozilla.org/en/docs/Web/API/HTMLElement) - the first element will be used
+- A [jQuery](https://jquery.com) object - if multiple are passed, the first element will be used
+
+Here's some examples
+
+Passing a [string selector](https://developer.mozilla.org/en-US/docs/Web/API/NodeList):
-Passing a [NodeList](https://developer.mozilla.org/en-US/docs/Web/API/NodeList):
```javascript
-plyr.setup(document.querySelectorAll('.js-player'), options);
+const player = new Plyr('#player');
```
Passing a [HTMLElement](https://developer.mozilla.org/en/docs/Web/API/HTMLElement):
-```javascript
-plyr.setup(document.querySelector('.js-player'), options);
-```
-Passing an [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) of [HTMLElement](https://developer.mozilla.org/en/docs/Web/API/HTMLElement)s:
```javascript
-plyr.setup([
- document.querySelector('.js-player-1'),
- document.querySelector('.js-player-2')
-], options);
+const player = new Plyr(document.getElementById('player'));
```
-Passing a [string selector](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelectorAll):
+Passing a [NodeList](https://developer.mozilla.org/en-US/docs/Web/API/NodeList):
+
```javascript
-plyr.setup('.js-player', options);
+const player = new Plyr(document.querySelectorAll('.js-player'));
```
The NodeList, HTMLElement or string selector can be the target `<video>`, `<audio>` or `[data-type]` (for embeds) element itself or a container element.
-Passing just the options object:
+The second argument for the constructor is the [#options](options) object:
+
```javascript
-plyr.setup(options);
+const player = new Plyr('#player', { /* options */ });
```
-`setup()` will return an array of *instances* that can be used with the [API](#api) methods. See the [API](#api) section for more info.
-
-#### RangeTouch
-Some touch browsers (particularly Mobile Safari on iOS) seem to have issues with `<input type="range">` elements whereby touching the track to set the value doesn't work and sliding the thumb can be tricky. To combat this, I've created [RangeTouch](https://rangetouch.com) which I'd recommend including in your solution. It's a tiny script with a nice benefit for users on touch devices.
+The constructor will return a Plyr object that can be used with the [API](#api) methods. See the [API](#api) section for more info.
#### Options
-Options must be passed as an object to the `setup()` method as above or as JSON in `data-plyr` attribute on each of your target elements:
+Options can be passed as an object to the constructor as above or as JSON in `data-plyr` attribute on each of your target elements:
```html
-<video data-plyr='{ title: "testing" }'></video>
+<video data-plyr='{ "title": "This is an example" }'></video>
```
-Note the single quotes encapsulating the JSON and double quotes on the object keys.
+Note the single quotes encapsulating the JSON and double quotes on the object keys. Only string values need double quotes.
<table class="table" width="100%">
<thead>
@@ -433,12 +430,6 @@ Note the single quotes encapsulating the JSON and double quotes on the object ke
<td><code>true</code></td>
<td>Enable a full viewport view for older browsers.</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>
@@ -446,25 +437,17 @@ Note the single quotes encapsulating the JSON and double quotes on the object ke
### Instance
-The easiest way to access the plyr instances is to store the return value from your call to `setup()`:
-
-```javascript
-var players = plyr.setup('.js-player');
-```
-
-This will return an array of all instances that were setup. Another way is to use `plyr.get()` to get all instances within a given container, for example:
+The easiest way to access the plyr instances is to store the return value from your call to the constructor. For example:
```javascript
-var players = plyr.get('.js-player');
+const player = new Plyr('#player', { /* options */ });
```
-If no argument is passed, it will find all instances in the current document. This will return an array of all instances that were found in the given selector.
-
-A final option is to access the instance through the event handlers:
+You can also access the instance through the event handlers:
```javascript
-instance.on('ready', function(event) {
- var instance = event.detail.plyr;
+instance.on('ready', event => {
+ const instance = event.detail.plyr;
});
```
@@ -1054,6 +1037,9 @@ 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.
+## RangeTouch
+Some touch browsers (particularly Mobile Safari on iOS) seem to have issues with `<input type="range">` elements whereby touching the track to set the value doesn't work and sliding the thumb can be tricky. To combat this, I've created [RangeTouch](https://rangetouch.com) which I'd recommend including in your solution. It's a tiny script with a nice benefit for users on touch devices.
+
## Issues
If you find anything weird with Plyr, please let us know using the GitHub issues tracker.