ProximaEntertainment/plyr
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
plyr/readme.md
Sam Potts 880152d0a0 Added CDN references
2015-03-02 01:08:12 +11:00

361 lines
12 KiB
Markdown
Raw Blame History

# 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 4.8KB 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.
- **Responsive** - any screen size.
- **No dependencies** - written in vanilla JavaScript.
- **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.
## Changelog
Check out [the changelog](changelog.md)
## 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.
- Multiple language captions (with selection)
- Localisation of control labels
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.
## Implementation
Check `docs/index.html` and `docs/dist/docs.js` for an example setup.
### Bower
If bower is your thang, you can grab Plyr using:
```
bower install plyr
```
More info on setting up dependencies can be found in the [Bower Docs](http://bower.io/docs/creating-packages/#maintaining-dependencies)
### CDN
If you want to use our CDN, you can use the following. Currently it's HTTP only.
```html
<link rel="stylesheet" href="http://cdn.plyr.io/1.0.18/plyr.css">
<script src="http://cdn.plyr.io/1.0.18/plyr.js"></script>
```
You can also access the `sprite.svg` file at `http://cdn.plyr.io/1.0.18/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.
```html
<link rel="stylesheet" href="dist/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>`, before any other scripts.
```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,"dist/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.selz.com/plyr/1.0/poster.jpg" controls crossorigin>
<!-- Video files -->
<source src="//cdn.selz.com/plyr/1.0/movie.mp4" type="video/mp4">
<source src="//cdn.selz.com/plyr/1.0/movie.webm" type="video/webm">
<!-- Text track file -->
<track kind="captions" label="English captions" src="//cdn.selz.com/plyr/1.0/movie_captions_en.vtt" srclang="en" default>
<!-- Fallback for browsers that don't support the <video> element -->
<div>
<a href="//cdn.selz.com/plyr/1.0/movie.mp4">Download</a>
</div>
</video>
</div>
```
And the same for `<audio>`
```html
<div class="player">
<audio controls>
<!-- Audio files -->
<source src="//cdn.selz.com/plyr/1.0/logistics-96-sample.mp3" type="audio/mp3">
<source src="//cdn.selz.com/plyr/1.0/logistics-96-sample.ogg" type="audio/ogg">
<!-- Fallback for browsers that don't support the <audio> element -->
<div>
<a href="//cdn.selz.com/plyr/1.0/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="dist/plyr.js"></script>
<script>
plyr.setup({
html: **your controls html**
});
</script>
```
#### Options
<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**. See <a href="controls.md">controls.md</a> for more info on how the html needs to be structured.</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>seekTime</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 `/src` 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 two properties; `enabled` which toggles if fullscreen should be enabled (if the browser supports it). The default value is `true`. Also an extra property called `fallback` which will enable a 'full window' view for older browsers. The default value is `true`.</td>
</tr>
<tr>
<td><code>storage</code></td>
<td>Object</td>
<td>&mdash;</td>
<td>This currently contains one property `enabled` 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.</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:
```javascript
document.querySelectorAll(".player")[0].plyr.pause();
```
Here's a list of the methods supported:
<table class="table" width="100%">
<thead>
<tr>
<th width="20%">Method</th>
<th width="15%">Parameters</th>
<th width="65%">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>play</code></td>
<td>&mdash;</td>
<td>Plays the media</td>
</tr>
<tr>
<td><code>pause</code></td>
<td>&mdash;</td>
<td>Pauses the media</td>
</tr>
<tr>
<td><code>restart</code></td>
<td>&mdash;</td>
<td>Restarts playback</td>
</tr>
<tr>
<td><code>rewind</code></td>
<td>Number</td>
<td>Rewinds by the provided parameter, in seconds. If no parameter is provided, the default seekInterval is used (10 seconds).</td>
</tr>
<tr>
<td><code>forward</code></td>
<td>Number</td>
<td>Fast forwards by the provided parameter, in seconds. If no parameter is provided, the default seekInterval is used (10 seconds).</td>
</tr>
<tr>
<td><code>setVolume</code></td>
<td>Number</td>
<td>Sets the player voume to the provided parameter. The value should be between 0 (muted) and 10 (loudest). If no parameter is provided, the default volume is used (5). Values over 10 are ignored.</td>
</tr>
<tr>
<td><code>toggleMute</code></td>
<td>&mdash;</td>
<td>Toggles mute for the player.</td>
</tr>
<tr>
<td><code>toggleCaptions</code></td>
<td>&mdash;</td>
<td>Toggles whether captions are enabled.</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;
media.addEventListener("playing", function() {
console.log("playing");
});
```
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;">
<thead>
<tr>
<td>Safari</td>
<td>Firefox</td>
<td>Chrome</td>
<td>Opera</td>
<td>IE9</td>
<td>IE10+</td>
</tr>
</thead>
<tbody>
<tr>
<td>✔</td>
<td>✔</td>
<td>✔</td>
<td>✔</td>
<td>✖&sup1;</td>
<td>✔&sup2;</td>
</tr>
</tbody>
</table>
&sup1; Native player used (no support for `<progress>` or `<input type="range">`)
&sup2; 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:
```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.
## 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))
## Mentions
- [The Changelog](http://thechangelog.com/plyr-simple-html5-media-player-custom-controls-webvtt-captions/)
- [HTML5 Weekly #177](http://html5weekly.com/issues/177)
- [Web Design Weekly #174](https://web-design-weekly.com/2015/02/24/web-design-weekly-174/)
## 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 :-)
## Useful links and credits
Credit to the PayPal HTML5 Video player from which Plyr's caption functionality is ported from:
- [PayPal's Accessible HTML5 Video Player](https://github.com/paypal/accessible-html5-video-player)
- The icons used in Plyr are [Vicons](https://dribbble.com/shots/1663443-60-Vicons-Free-Icon-Set) plus some ones I made
Also these links helped created Plyr:
- [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/)
## Copyright and License
Copyright 2014, Selz.com under [the BSD license](license.md).
Reference in New Issue View Git Blame Copy Permalink