# Plyr
A simple, accessible HTML5 media player. 

[Checkout the demo](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 4KB minified and gzipped.
- **Customisable** - make the player look how you want with the markup you want.
- **Semantic** - uses HTML5 form inputs for volume (range) and progress element for playback progress.
- **No dependencies** - written in native JS.
- **API** - easy to use API.
- **Fallback** - if there's no support, the native players are used.
- **Fullscreen** - options to run the player full browser or the user can toggle fullscreen.

## Planned development
- Accept a string selector, a node, or a nodelist for the `container` property of `selectors`.
- Accept a selector for the `html` template property.

## Implementation

### CSS
If you want to use the default css, add the css file from /dist into your head, or even better use the less file included in /assets in your build to save a request. 

```html
<link rel="stylesheet" href="/css/plyr.css" />
```

### 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>`

```html
<script>
(function(d,p){
	var a=new XMLHttpRequest(),
		b=d.body;
	a.open("GET",p,!0);
	a.send();
	a.onload=function(){
		var c=d.createElement("div");
		c.style.display="none";
		c.innerHTML=a.responseText;
		b.insertBefore(c,b.childNodes[0])
	}
})(document,"/svg/sprite.svg");
</script>
```
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/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="//cdn.sampotts.me/plyr/poster.jpg" controls crossorigin>
		<!-- Video files -->
		<source src="//cdn.sampotts.me/plyr/movie.mp4" type="video/mp4">
		<source src="//cdn.sampotts.me/plyr/movie.webm" type="video/webm">
		
		<!-- Text track file -->
		<track kind="captions" label="English captions" src="//cdn.sampotts.me/plyr/movie_captions_en.vtt" srclang="en" default>
		
		<!-- Fallback for browsers that don't support the <video> element -->
		<div>
			<a href="//cdn.sampotts.me/plyr/movie.mp4">
				<img src="//cdn.sampotts.me/plyr/poster.jpg" alt="Download">
			</a>
		</div>
	</video>
</div>
```
And the same for `<audio>`

```html
<div class="player">
	<audio controls>
		<!-- Audio files -->
		<source src="//cdn.sampotts.me/plyr/logistics-96-sample.mp3" type="audio/mp3">
		
		<!-- Fallback for browsers that don't support the <audio> element -->
		<div>
			<a href="//cdn.sampotts.me/plyr/logistics-96-sample.mp3">Download</a>
		</div>
	</audio>
</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. 

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.

```html
<script src="js/plyr.js"></script>
<script>
plyr.setup({
	html: **your controls html**
});
</script>
```
You can pass the following settings:

<table class="table" width="100%">
<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>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>
  </tr>
  <tr>
    <td><code>html</code></td>
    <td>String</td>
    <td><code>&mdash;</code></td>
    <td>This is **required**. It is the markup used for the controls. In the demo, we use Hogan templates as we are already using them. You can of course, just specify vanilla html. The only requirement is your selectors should match the `selectors` option below. If you check `controls.html` in `/assets/templates` to get an idea of how the default html works. 

    You need to add two placeholders to your html template:
    - {id} for the dynamically generated ID for the player (for form controls)
    - {aria_label} for the dynamically generated play button label for screen readers</td>
  </tr>
  <tr>
    <td><code>debug</code></td>
    <td>Boolean</td>
    <td><code>false</code></td>
    <td>Display debugging information on what Plyr is doing.</td>
  </tr>
  <tr>
    <td><code>seekInterval</code></td>
    <td>Number</td>
    <td><code>10</code></td>
    <td>The time, in seconds, to seek when a user hits fast forward or rewind.</td>
  </tr>
  <tr>
    <td><code>volume</code></td>
    <td>Number</td>
    <td><code>5</code></td>
    <td>A number, between 1 and 10, representing the inital volume of the player.</td>
  </tr>
  <tr>
    <td><code>click</code></td>
    <td>Boolean</td>
    <td><code>true</code></td>
    <td>Click (or tap) will toggle pause/play of a `<video>`.</td>
  </tr>
  <tr>
    <td><code>selectors</code></td>
    <td>Object</td>
    <td>&mdash;</td>
    <td>See `plyr.js` in `/assets` for more info. The only option you might want to change is `player` which is the hook used for Plyr, the default is `.player`.</td>
  </tr>
  <tr>
    <td><code>classes</code></td>
    <td>Object</td>
    <td>&mdash;</td>
    <td>Similar to above, these are the classes added to the player when state changes occur.</td>
  </tr>
  <tr>
    <td><code>captions</code></td>
    <td>Object</td>
    <td>&mdash;</td>
    <td>This currently contains one property `defaultActive` which toggles if captions should be on by default. The default value is `false`.</td>
  </tr>
  <tr>
    <td><code>fullscreen</code></td>
    <td>Object</td>
    <td>&mdash;</td>
    <td>This currently contains one property `enabled` which toggles if fullscreen should be enabled (if the browser supports it). The default value is `true`.</td>
  </tr>
 </tbody>
</table>

## 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.

## Support
- Chrome: full support
- Safari: full support
- Firefox: full support
- Internet Explorer 10, 11: full support
- Internet Explorer 9: native player used (no support for `<progress>` or `<input type="range">`) 

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)
```
If a User Agent is disabled but supports `<video>` and `<audio>` natively, it will use the native player.

Any unsupported browsers will display links to download the media if the correct html is used.

## Useful links 

- [Media Events - W3.org](http://www.w3.org/2010/05/video/mediaevents.html)
- [Styling the `<progress>` element - hongkiat.com](http://www.hongkiat.com/blog/html5-progress-bar/)
- [PayPal's Accessible HTML5 Video Player](https://github.com/paypal/accessible-html5-video-player)