Skip to content

Commit 5befbfa

Browse files
cookpetecookpete
committed
Tidy up readme
1 parent 4ffd201 commit 5befbfa

2 files changed

Lines changed: 148 additions & 78 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,16 @@
22

33
Thanks for contributing to ReactPlayer!
44

5+
Running the demo locally is relatively easy:
6+
7+
```bash
8+
git clone https://github.com/CookPete/react-player.git
9+
cd react-player
10+
npm install # or yarn
11+
npm start
12+
open http://localhost:3000
13+
```
14+
515
## `dist` files
616

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

‎README.md‎

Lines changed: 138 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,33 @@
1-
ReactPlayer
2-
===========
3-
4-
[![Latest npm version](https://img.shields.io/npm/v/react-player.svg)](https://www.npmjs.com/package/react-player)
5-
[![Build Status](https://img.shields.io/travis/CookPete/react-player/master.svg)](https://travis-ci.org/CookPete/react-player)
6-
[![Dependency Status](https://img.shields.io/david/CookPete/react-player.svg)](https://david-dm.org/CookPete/react-player)
7-
[![Test Coverage](https://img.shields.io/codecov/c/github/cookpete/react-player.svg)](https://codecov.io/gh/CookPete/react-player)
8-
[![Donate](https://img.shields.io/badge/donate-PayPal-blue.svg)](https://paypal.me/ckpt)
9-
10-
A React component for playing a variety of URLs, including file paths, YouTube, Facebook, Twitch, SoundCloud, Streamable, Vimeo, Wistia and DailyMotion.
11-
12-
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.
1+
<h2 align="center">
2+
ReactPlayer
3+
</h2>
4+
5+
<p align="center">
6+
<a href='https://www.npmjs.com/package/react-player'>
7+
<img src='https://img.shields.io/npm/v/react-player.svg' alt='Latest npm version'>
8+
</a>
9+
<a href='https://travis-ci.org/CookPete/react-player'>
10+
<img src='https://img.shields.io/travis/CookPete/react-player/master.svg' alt='Build Status'>
11+
</a>
12+
<a href='https://david-dm.org/CookPete/react-player'>
13+
<img src='https://img.shields.io/david/CookPete/react-player.svg' alt='Dependency Status'>
14+
</a>
15+
<a href='https://codecov.io/gh/CookPete/react-player'>
16+
<img src='https://img.shields.io/codecov/c/github/cookpete/react-player.svg' alt='Test Coverage'>
17+
</a>
18+
<a href='https://paypal.me/ckpt'>
19+
<img src='https://img.shields.io/badge/donate-PayPal-blue.svg' alt='Donate'>
20+
</a>
21+
</p>
22+
23+
<p align="center">
24+
A React component for playing a variety of URLs, including file paths, YouTube, Facebook, Twitch, SoundCloud, Streamable, Vimeo, Wistia and DailyMotion.
25+
</p>
1326

1427
#### Migrating to `1.0.0`
1528

1629
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.
1730

18-
### Polyfills
19-
20-
* 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).
21-
* To support IE11 you will need to use [`babel-polyfill`](https://babeljs.io/docs/usage/polyfill) or a similar ES2015+ polyfill.
22-
2331
### Usage
2432

2533
```bash
@@ -39,45 +47,16 @@ class App extends Component {
3947
}
4048
```
4149

42-
See [the demo source](https://github.com/CookPete/react-player/blob/master/src/demo/App.js) for a full example.
43-
44-
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`
45-
46-
#### Bower
47-
48-
```bash
49-
bower install react-player --save
50-
```
51-
52-
```html
53-
<script src='bower_components/react/react.js'></script>
54-
<script src='bower_components/react/react-dom.js'></script>
55-
<script src='bower_components/react-player/dist/ReactPlayer.js'></script>
56-
<script>
57-
ReactDOM.render(
58-
<ReactPlayer url='https://www.youtube.com/watch?v=d46Azg3Pm4c' playing />,
59-
document.getElementById('container')
60-
)
61-
</script>
62-
```
63-
64-
### Demo
50+
Demo page: [`https://cookpete.com/react-player`](https://cookpete.com/react-player)
6551

66-
See a [live demo](http://cookpete.com/react-player), or run:
52+
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.
6753

68-
```bash
69-
git clone https://github.com/CookPete/react-player.git
70-
cd react-player
71-
npm install # or yarn
72-
npm start
73-
open http://localhost:3000
74-
```
75-
76-
### Mobile considerations
54+
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`.
7755

78-
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:
56+
#### Polyfills
7957

80-
> 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).
58+
* 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).
59+
* To support IE11 you will need to use [`babel-polyfill`](https://babeljs.io/docs/usage/polyfill) or a similar ES2015+ polyfill.
8160

8261
### Props
8362

@@ -90,8 +69,8 @@ Prop | Description | Default
9069
`volume` | Sets the volume of the appropriate player | `0.8`
9170
`muted` | Mutes the player | `false`
9271
`playbackRate` | Sets the playback rate of the appropriate player<br />*Note: Only supported by YouTube, Wistia, and file paths* | `1`
93-
`width` | Sets the width of the player | `640`
94-
`height` | Sets the height of the player | `360`
72+
`width` | Sets the width of the player | `640px`
73+
`height` | Sets the height of the player | `360px`
9574
`style` | Add [inline styles](https://facebook.github.io/react/tips/inline-styles.html) to the root element | `{}`
9675
`progressFrequency` | The time between `onProgress` callbacks, in milliseconds | `1000`
9776
`playsinline` | Applies the `playsinline` attribute where supported | `false`
@@ -158,6 +137,107 @@ Key | Options
158137

159138
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.
160139

140+
### Methods
141+
142+
#### Static Methods
143+
144+
Method | Description
145+
---- | -----------
146+
`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.
147+
148+
#### Instance Methods
149+
150+
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.
151+
152+
Method | Description
153+
---- | -----------
154+
`seekTo(amount)` | Seek to the given number of seconds, or fraction if `amount` is between `0` and `1`
155+
`getCurrentTime()` | Returns the number of seconds that has been played<br />&nbsp; ◦ &nbsp;Returns `null` if duration is unavailable
156+
`getDuration()` | Returns the duration (in seconds) of the currently playing media<br />&nbsp; ◦ &nbsp;Returns `null` if duration is unavailable
157+
`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
158+
159+
### Advanced Usage
160+
161+
#### Responsive player
162+
163+
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:
164+
165+
```js
166+
class ResponsivePlayer extends Component {
167+
render () {
168+
return (
169+
<div className='player-wrapper'>
170+
<ReactPlayer
171+
className='react-player'
172+
url='https://www.youtube.com/watch?v=ysz5S6PUM-U'
173+
width='100%'
174+
height='100%'
175+
/>
176+
</div>
177+
)
178+
}
179+
}
180+
```
181+
182+
```css
183+
.player-wrapper {
184+
position: relative;
185+
padding-top: 56.25% /* Player ratio: 100 / (1280 / 720) */
186+
}
187+
188+
.react-player {
189+
position: absolute;
190+
top: 0;
191+
left: 0;
192+
}
193+
```
194+
195+
See [`jsFiddle` example](https://jsfiddle.net/e6w3rtj1/)
196+
197+
#### Standalone player
198+
199+
If you aren’t using React, you can still render a player using the standalone library:
200+
201+
```html
202+
<script src='https://cdn.rawgit.com/CookPete/react-player/standalone/dist/ReactPlayer.standalone.js'></script>
203+
<script>
204+
const container = document.getElementById('container')
205+
const url = 'https://www.youtube.com/watch?v=d46Azg3Pm4c'
206+
207+
renderReactPlayer(container, { url, playing: true })
208+
209+
function pausePlayer () {
210+
renderReactPlayer(container, { url, playing: false })
211+
}
212+
</script>
213+
```
214+
215+
See [`jsFiddle` example](https://jsfiddle.net/krkcvx9s/)
216+
217+
#### Using Bower
218+
219+
```bash
220+
bower install react-player --save
221+
```
222+
223+
```html
224+
<script src='bower_components/react/react.js'></script>
225+
<script src='bower_components/react/react-dom.js'></script>
226+
<script src='bower_components/react-player/dist/ReactPlayer.js'></script>
227+
<script>
228+
ReactDOM.render(
229+
<ReactPlayer url='https://www.youtube.com/watch?v=d46Azg3Pm4c' playing />,
230+
document.getElementById('container')
231+
)
232+
</script>
233+
```
234+
235+
#### Mobile considerations
236+
237+
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:
238+
239+
> 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).
240+
161241
#### Multiple Sources and Tracks
162242

163243
When playing file paths, an array of sources can be passed to the `url` prop to render multiple `<source>` tags.
@@ -194,45 +274,25 @@ You can also specify a `type` for each source by using objects with `src` and `t
194274
/>
195275
```
196276

197-
198-
### Methods
199-
200-
#### Static Methods
201-
202-
Method | Description
203-
---- | -----------
204-
`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.
205-
206-
#### Instance Methods
207-
208-
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.
209-
210-
Method | Description
211-
---- | -----------
212-
`seekTo(amount)` | Seek to the given number of seconds, or fraction if `amount` is between `0` and `1`
213-
`getCurrentTime()` | Returns the number of seconds that has been played<br />&nbsp; ◦ &nbsp;Returns `null` if duration is unavailable
214-
`getDuration()` | Returns the duration (in seconds) of the currently playing media<br />&nbsp; ◦ &nbsp;Returns `null` if duration is unavailable
215-
`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
216-
217277
### Supported media
218278

219279
* YouTube videos use the [YouTube iFrame Player API](https://developers.google.com/youtube/iframe_api_reference)
220280
* Facebook videos use the [Facebook Embedded Video Player API](https://developers.facebook.com/docs/plugins/embedded-video-player/api)
221281
* SoundCloud tracks use the [SoundCloud Widget API](https://developers.soundcloud.com/docs/api/html5-widget)
222-
* 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
282+
* Streamable videos use [`Player.js`](https://github.com/embedly/player.js)
223283
* Vidme videos are [no longer supported](https://medium.com/vidme/goodbye-for-now-120b40becafa)
224284
* Vimeo videos use the [Vimeo Player API](https://developer.vimeo.com/player/js-api)
225285
* Wistia videos use the [Wistia Player API](https://wistia.com/doc/player-api)
226286
* Twitch videos use the [Twitch Interactive Frames API](https://dev.twitch.tv/docs/embed#interactive-frames-for-live-streams-and-vods)
227287
* DailyMotion videos use the [DailyMotion Player API](https://developer.dailymotion.com/player)
228288
* [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
229-
* HLS streams are played using [hls.js](https://github.com/video-dev/hls.js)
230-
* DASH streams are played using [dash.js](https://github.com/Dash-Industry-Forum/dash.js)
289+
* HLS streams are played using [`hls.js`](https://github.com/video-dev/hls.js)
290+
* DASH streams are played using [`dash.js`](https://github.com/Dash-Industry-Forum/dash.js)
231291

232292
### Contributing
233293

234294
See the [contribution guidelines](https://github.com/CookPete/react-player/blob/master/CONTRIBUTING.md) before creating a pull request.
235295

236296
### Thanks
237297

238-
Huge thanks to anyone who has [contributed](https://github.com/CookPete/react-player/graphs/contributors)
298+
Huge thanks to anyone who has [contributed](https://github.com/CookPete/react-player/graphs/contributors).

0 commit comments

Comments
 (0)