From 5befbfab44313a48d7770cf00f3cda200ebc3bbb Mon Sep 17 00:00:00 2001
From: Pete Cook <pete@cookpete.com>
Date: Thu, 18 Jan 2018 09:30:13 +0000
Subject: [PATCH] Tidy up readme

---
 CONTRIBUTING.md |  10 +++
 README.md       | 216 +++++++++++++++++++++++++++++++-----------------
 2 files changed, 148 insertions(+), 78 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4b1352a7..255c8010 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -2,6 +2,16 @@
 
 Thanks for contributing to ReactPlayer!
 
+Running the demo locally is relatively easy:
+
+```bash
+git clone https://github.com/CookPete/react-player.git
+cd react-player
+npm install # or yarn
+npm start
+open http://localhost:3000
+```
+
 ## `dist` files
 
 There is **no need** to build or commit files in `dist` after making changes. The `dist` files are only there for [bower](http://bower.io) support, and there is very little point in polluting every commit or pull request with the changes. The `dist` files will be automatically built and commmited when new versions are released, so your changes will be included then.
diff --git a/README.md b/README.md
index 27c72558..717e5495 100644
--- a/README.md
+++ b/README.md
@@ -1,25 +1,33 @@
-ReactPlayer
-===========
-
-[![Latest npm version](https://img.shields.io/npm/v/react-player.svg)](https://www.npmjs.com/package/react-player)
-[![Build Status](https://img.shields.io/travis/CookPete/react-player/master.svg)](https://travis-ci.org/CookPete/react-player)
-[![Dependency Status](https://img.shields.io/david/CookPete/react-player.svg)](https://david-dm.org/CookPete/react-player)
-[![Test Coverage](https://img.shields.io/codecov/c/github/cookpete/react-player.svg)](https://codecov.io/gh/CookPete/react-player)
-[![Donate](https://img.shields.io/badge/donate-PayPal-blue.svg)](https://paypal.me/ckpt)
-
-A React component for playing a variety of URLs, including file paths, YouTube, Facebook, Twitch, SoundCloud, Streamable, Vimeo, Wistia and DailyMotion.
-
-The component parses a URL and loads in the appropriate markup and external SDKs to play media from [various sources](#supported-media). [Props](#props) can be passed in to control playback and react to events such as buffering or media ending.
+<h2 align="center">
+  ReactPlayer
+</h2>
+
+<p align="center">
+  <a href='https://www.npmjs.com/package/react-player'>
+    <img src='https://img.shields.io/npm/v/react-player.svg' alt='Latest npm version'>
+  </a>
+  <a href='https://travis-ci.org/CookPete/react-player'>
+    <img src='https://img.shields.io/travis/CookPete/react-player/master.svg' alt='Build Status'>
+  </a>
+  <a href='https://david-dm.org/CookPete/react-player'>
+    <img src='https://img.shields.io/david/CookPete/react-player.svg' alt='Dependency Status'>
+  </a>
+  <a href='https://codecov.io/gh/CookPete/react-player'>
+    <img src='https://img.shields.io/codecov/c/github/cookpete/react-player.svg' alt='Test Coverage'>
+  </a>
+  <a href='https://paypal.me/ckpt'>
+    <img src='https://img.shields.io/badge/donate-PayPal-blue.svg' alt='Donate'>
+  </a>
+</p>
+
+<p align="center">
+  A React component for playing a variety of URLs, including file paths, YouTube, Facebook, Twitch, SoundCloud, Streamable, Vimeo, Wistia and DailyMotion.
+</p>
 
 #### Migrating to `1.0.0`
 
 All existing implementations of `ReactPlayer` should still work without any changes after migrating. The major changes are to how the component works internally. Keep an eye out for bugs and [raise an issue](https://github.com/CookPete/react-player/issues/new) if one doesn’t already exist.
 
-### Polyfills
-
-* If you are using `npm` and need to support [browsers without `Promise`](http://caniuse.com/#feat=promises) you will need a [`Promise` polyfill](https://github.com/stefanpenner/es6-promise).
-* To support IE11 you will need to use [`babel-polyfill`](https://babeljs.io/docs/usage/polyfill) or a similar ES2015+ polyfill.
-
 ### Usage
 
 ```bash
@@ -39,45 +47,16 @@ class App extends Component {
 }
 ```
 
-See [the demo source](https://github.com/CookPete/react-player/blob/master/src/demo/App.js) for a full example.
-
-For platforms like [Meteor](https://www.meteor.com) without direct use of `npm` modules, a minified version of `ReactPlayer` is located in `dist` after installing. To generate this file yourself, checkout the repo and run `npm run build:dist`
-
-#### Bower
-
-```bash
-bower install react-player --save
-```
-
-```html
-<script src='bower_components/react/react.js'></script>
-<script src='bower_components/react/react-dom.js'></script>
-<script src='bower_components/react-player/dist/ReactPlayer.js'></script>
-<script>
-  ReactDOM.render(
-    <ReactPlayer url='https://www.youtube.com/watch?v=d46Azg3Pm4c' playing />,
-    document.getElementById('container')
-  )
-</script>
-```
-
-### Demo
+Demo page: [`https://cookpete.com/react-player`](https://cookpete.com/react-player)
 
-See a [live demo](http://cookpete.com/react-player), or run:
+The component parses a URL and loads in the appropriate markup and external SDKs to play media from [various sources](#supported-media). [Props](#props) can be passed in to control playback and react to events such as buffering or media ending. See [the demo source](https://github.com/CookPete/react-player/blob/master/src/demo/App.js) for a full example.
 
-```bash
-git clone https://github.com/CookPete/react-player.git
-cd react-player
-npm install # or yarn
-npm start
-open http://localhost:3000
-```
-
-### Mobile considerations
+For platforms like [Meteor](https://www.meteor.com) without direct use of `npm` modules, a minified version of `ReactPlayer` is located in `dist` after installing. To generate this file yourself, checkout the repo and run `npm run build:dist`.
 
-Due to various restrictions, `ReactPlayer` is not guaranteed to function properly on mobile devices. The [YouTube player documentation](https://developers.google.com/youtube/iframe_api_reference), for example, explains that [certain mobile browsers require user interaction](https://developers.google.com/youtube/iframe_api_reference#Mobile_considerations) before playing:
+#### Polyfills
 
-> The HTML5 `<video>` element, in certain mobile browsers (such as Chrome and Safari), only allows playback to take place if it’s initiated by a user interaction (such as tapping on the player).
+* If you are using `npm` and need to support [browsers without `Promise`](http://caniuse.com/#feat=promises) you will need a [`Promise` polyfill](https://github.com/stefanpenner/es6-promise).
+* To support IE11 you will need to use [`babel-polyfill`](https://babeljs.io/docs/usage/polyfill) or a similar ES2015+ polyfill.
 
 ### Props
 
@@ -90,8 +69,8 @@ Prop | Description | Default
 `volume` | Sets the volume of the appropriate player | `0.8`
 `muted` | Mutes the player | `false`
 `playbackRate` | Sets the playback rate of the appropriate player<br />*Note: Only supported by YouTube, Wistia, and file paths* | `1`
-`width` | Sets the width of the player | `640`
-`height` | Sets the height of the player | `360`
+`width` | Sets the width of the player | `640px`
+`height` | Sets the height of the player | `360px`
 `style` | Add [inline styles](https://facebook.github.io/react/tips/inline-styles.html) to the root element | `{}`
 `progressFrequency` | The time between `onProgress` callbacks, in milliseconds | `1000`
 `playsinline` | Applies the `playsinline` attribute where supported | `false`
@@ -158,6 +137,107 @@ Key | Options
 
 When `preload` is set to `true` for players that support it, a short, silent video is played in the background when `ReactPlayer` first mounts. This fixes a [bug](https://github.com/CookPete/react-player/issues/7) where videos would not play when loaded in a background browser tab.
 
+### Methods
+
+#### Static Methods
+
+Method | Description
+---- | -----------
+`ReactPlayer.canPlay(url)` | Determine if a URL can be played. This does *not* detect media that is unplayable due to privacy settings, streaming permissions, etc. In that case, the `onError` prop will be invoked after attemping to play. Any URL that does not match any patterns will fall back to a native HTML5 media player.
+
+#### Instance Methods
+
+Use [`ref`](https://facebook.github.io/react/docs/refs-and-the-dom.html) to call instance methods on the player. See [the demo app](src/demo/App.js) for an example of this.
+
+Method | Description
+---- | -----------
+`seekTo(amount)` | Seek to the given number of seconds, or fraction if `amount` is between `0` and `1`
+`getCurrentTime()` | Returns the number of seconds that has been played<br />&nbsp; ◦ &nbsp;Returns `null` if duration is unavailable
+`getDuration()` | Returns the duration (in seconds) of the currently playing media<br />&nbsp; ◦ &nbsp;Returns `null` if duration is unavailable
+`getInternalPlayer()` | Returns the internal player of whatever is currently playing<br />&nbsp; ◦ &nbsp;eg the [YouTube player instance](https://developers.google.com/youtube/iframe_api_reference#Loading_a_Video_Player), or the [`<video>`](https://developer.mozilla.org/en/docs/Web/HTML/Element/video) element when playing a video file<br />&nbsp; ◦ &nbsp;Use `getInternalPlayer('hls')` to get the [hls.js](https://github.com/video-dev/hls.js) player<br />&nbsp; ◦ &nbsp;Use `getInternalPlayer('dash')` to get the [dash.js](https://github.com/Dash-Industry-Forum/dash.js) player<br />&nbsp; ◦ &nbsp;Returns `null` if the internal player is unavailable
+
+### Advanced Usage
+
+#### Responsive player
+
+Set `width` and `height` to `100%` and wrap the player in a [fixed aspect ratio box](https://css-tricks.com/aspect-ratio-boxes) to get a responsive player:
+
+```js
+class ResponsivePlayer extends Component {
+  render () {
+    return (
+      <div className='player-wrapper'>
+        <ReactPlayer 
+          className='react-player'
+          url='https://www.youtube.com/watch?v=ysz5S6PUM-U'
+          width='100%'
+          height='100%'
+        />
+      </div>
+    )
+  }
+}
+```
+
+```css
+.player-wrapper {
+  position: relative;
+  padding-top: 56.25% /* Player ratio: 100 / (1280 / 720) */
+}
+
+.react-player {
+  position: absolute;
+  top: 0;
+  left: 0;
+}
+```
+
+See [`jsFiddle` example](https://jsfiddle.net/e6w3rtj1/)
+
+#### Standalone player
+
+If you aren’t using React, you can still render a player using the standalone library:
+
+```html
+<script src='https://cdn.rawgit.com/CookPete/react-player/standalone/dist/ReactPlayer.standalone.js'></script>
+<script>
+  const container = document.getElementById('container')
+  const url = 'https://www.youtube.com/watch?v=d46Azg3Pm4c'
+
+  renderReactPlayer(container, { url, playing: true })
+
+  function pausePlayer () {
+    renderReactPlayer(container, { url, playing: false })
+  }
+</script>
+```
+
+See [`jsFiddle` example](https://jsfiddle.net/krkcvx9s/)
+
+#### Using Bower
+
+```bash
+bower install react-player --save
+```
+
+```html
+<script src='bower_components/react/react.js'></script>
+<script src='bower_components/react/react-dom.js'></script>
+<script src='bower_components/react-player/dist/ReactPlayer.js'></script>
+<script>
+  ReactDOM.render(
+    <ReactPlayer url='https://www.youtube.com/watch?v=d46Azg3Pm4c' playing />,
+    document.getElementById('container')
+  )
+</script>
+```
+
+#### Mobile considerations
+
+Due to various restrictions, `ReactPlayer` is not guaranteed to function properly on mobile devices. The [YouTube player documentation](https://developers.google.com/youtube/iframe_api_reference), for example, explains that [certain mobile browsers require user interaction](https://developers.google.com/youtube/iframe_api_reference#Mobile_considerations) before playing:
+
+> The HTML5 `<video>` element, in certain mobile browsers (such as Chrome and Safari), only allows playback to take place if it’s initiated by a user interaction (such as tapping on the player).
+
 #### Multiple Sources and Tracks
 
 When playing file paths, an array of sources can be passed to the `url` prop to render multiple `<source>` tags.
@@ -194,40 +274,20 @@ You can also specify a `type` for each source by using objects with `src` and `t
 />
 ```
 
-
-### Methods
-
-#### Static Methods
-
-Method | Description
----- | -----------
-`ReactPlayer.canPlay(url)` | Determine if a URL can be played. This does *not* detect media that is unplayable due to privacy settings, streaming permissions, etc. In that case, the `onError` prop will be invoked after attemping to play. Any URL that does not match any patterns will fall back to a native HTML5 media player.
-
-#### Instance Methods
-
-Use [`ref`](https://facebook.github.io/react/docs/refs-and-the-dom.html) to call instance methods on the player. See [the demo app](src/demo/App.js) for an example of this.
-
-Method | Description
----- | -----------
-`seekTo(amount)` | Seek to the given number of seconds, or fraction if `amount` is between `0` and `1`
-`getCurrentTime()` | Returns the number of seconds that has been played<br />&nbsp; ◦ &nbsp;Returns `null` if duration is unavailable
-`getDuration()` | Returns the duration (in seconds) of the currently playing media<br />&nbsp; ◦ &nbsp;Returns `null` if duration is unavailable
-`getInternalPlayer()` | Returns the internal player of whatever is currently playing<br />&nbsp; ◦ &nbsp;eg the [YouTube player instance](https://developers.google.com/youtube/iframe_api_reference#Loading_a_Video_Player), or the [`<video>`](https://developer.mozilla.org/en/docs/Web/HTML/Element/video) element when playing a video file<br />&nbsp; ◦ &nbsp;Use `getInternalPlayer('hls')` to get the [hls.js](https://github.com/video-dev/hls.js) player<br />&nbsp; ◦ &nbsp;Use `getInternalPlayer('dash')` to get the [dash.js](https://github.com/Dash-Industry-Forum/dash.js) player<br />&nbsp; ◦ &nbsp;Returns `null` if the internal player is unavailable
-
 ### Supported media
 
 * YouTube videos use the [YouTube iFrame Player API](https://developers.google.com/youtube/iframe_api_reference)
 * Facebook videos use the [Facebook Embedded Video Player API](https://developers.facebook.com/docs/plugins/embedded-video-player/api)
 * SoundCloud tracks use the [SoundCloud Widget API](https://developers.soundcloud.com/docs/api/html5-widget)
-* Streamable videos are [resolved](https://streamable.com/documentation#retrieve-video) and played in a [`<video>`](https://developer.mozilla.org/en/docs/Web/HTML/Element/video) element using the track’s `mp4` path
+* Streamable videos use [`Player.js`](https://github.com/embedly/player.js)
 * Vidme videos are [no longer supported](https://medium.com/vidme/goodbye-for-now-120b40becafa)
 * Vimeo videos use the [Vimeo Player API](https://developer.vimeo.com/player/js-api)
 * Wistia videos use the [Wistia Player API](https://wistia.com/doc/player-api)
 * Twitch videos use the [Twitch Interactive Frames API](https://dev.twitch.tv/docs/embed#interactive-frames-for-live-streams-and-vods)
 * DailyMotion videos use the [DailyMotion Player API](https://developer.dailymotion.com/player)
 * [Supported file types](https://developer.mozilla.org/en-US/docs/Web/HTML/Supported_media_formats) are playing using [`<video>`](https://developer.mozilla.org/en/docs/Web/HTML/Element/video) or [`<audio>`](https://developer.mozilla.org/en/docs/Web/HTML/Element/audio) elements
-  * HLS streams are played using [hls.js](https://github.com/video-dev/hls.js)
-  * DASH streams are played using [dash.js](https://github.com/Dash-Industry-Forum/dash.js)
+  * HLS streams are played using [`hls.js`](https://github.com/video-dev/hls.js)
+  * DASH streams are played using [`dash.js`](https://github.com/Dash-Industry-Forum/dash.js)
 
 ### Contributing
 
@@ -235,4 +295,4 @@ See the [contribution guidelines](https://github.com/CookPete/react-player/blob/
 
 ### Thanks
 
-Huge thanks to anyone who has [contributed](https://github.com/CookPete/react-player/graphs/contributors)
+Huge thanks to anyone who has [contributed](https://github.com/CookPete/react-player/graphs/contributors).