anorgatarrak-wordpress-theme/node_modules/mediaelement/docs/usage.md

499 lines
18 KiB
Markdown
Raw Normal View History

2018-02-15 19:26:12 +01:00
# Usage
* [Initialize player](#initialize)
* [Automatic start](#automatic)
* [Vanilla JavaScript](#vanilla)
* [jQuery](#jquery)
* [NPM/Meteor](#npm-meteor)
* [RequireJS](#requirejs)
* [React](#react)
* [Use Renderers](#renderers-usage)
* [Use `stretching` modes](#stretching-modes)
* [Responsive grid](#grid)
* [Setting new captions](#captions)
* [Destroy player](#destroy)
<a id="initialize"></a>
## Initialize player
You can use this as a standalone library if you wish, or just stick with the full MediaElementPlayer.
**IMPORTANT:** If you use `flash_video` renderer, it's always recommended to use `media.load()` inside the `success` callback to ensure that RTMP and FLV will play properly.
## Standalone
```html
<script>
// You can use either a string for the player ID (i.e., `player`),
// or `document.querySelector()` for any selector
var player = new MediaElement('player', {
pluginPath: "/path/to/shims/",
success: function(mediaElement, originalNode) {
// do things
}
});
</script>
```
<a id="automatic"></a>
### Automatic start
You can avoid running any startup scripts by adding `class="mejs__player"` to the `<video>` or `<audio>` tag. All the player configuration can be added through `data-mejsoptions` attribute.
```html
<video src="myvideo.mp4" width="320" height="240"
class="mejs__player"
data-mejsoptions='{"pluginPath": "/path/to/shims/", "alwaysShowControls": "true"}'></video>
```
<a id="vanilla"></a>
### Vanilla JavaScript
```html
<script>
// You can use either a string for the player ID (i.e., `player`),
// or `document.querySelector()` for any selector
var player = new MediaElementPlayer('player', {
pluginPath: "/path/to/shims/",
// When using `MediaElementPlayer`, an `instance` argument
// is available in the `success` callback
success: function(mediaElement, originalNode, instance) {
// do things
}
});
</script>
```
<a id="jquery"></a>
### jQuery
```html
<script>
$('#mediaplayer').mediaelementplayer({
pluginPath: "/path/to/shims/",
// When using jQuery's `mediaelementplayer`, an `instance` argument
// is available in the `success` callback
success: function(mediaElement, originalNode, instance) {
// do things
}
});
</script>
```
<a id="npm-meteor"></a>
### NPM/Meteor
```javascript
// To import only MediaElement class
import 'mediaelement/standalone';
// To import all the plugin (you will have access to the MediaElement and MediaElementPlayer classes,
// $.fn.mediaelementplayer plugin, all the native renderers, YouTube and Flash shims)
import 'mediaelement/full';
// To import renderers (i.e., Vimeo)
import 'mediaelement/build/renderers/vimeo';
// To import languages (i.e., Spanish)
import 'mediaelement/build/lang/es';
// Later on the code you need to use mejs.i18n.language('es') to set the language
```
**IMPORTANT**: To ensure you can use the `$.fn.mediaelementplayer` plugin, you will need to import jQuery as well in your bundle like follows:
1. Create a `jquery-global.js` file that contains:
```javascript
'use strict';
import jquery from 'jquery';
window.jQuery = jquery;
window.$ = jquery;
```
2. Import the `jquery-global.js` along with the desired package
```javascript
'use strict';
import '/path/to/jquery-global';
import 'mediaelement'; // or import `mediaelement/standalone` if you only want the shim but not the full player;
```
<a id="requirejs"></a>
### RequireJS
With `Require.js`, you will need the following setup if you are planning to use HLS, M(PEG)-DASH or FLV, given the way the packages are bundled.
To make it work, install via NPM any of the external libraries you will need (i.e., HLS.js).
```
npm install hls.js
```
In your code, include a `shim` for the external library and then assign the exported variable to the global scope.
```javascript
requirejs.config({
// Other configuration
shim: {
// Other shims
'path/to/hls': {deps: ['require'], exports: "Hls"},
// If you only need the shim and not the player, use
//'path/to/mediaelement': {deps: ['require'], exports: "MediaElement"}
'path/to/mediaelement-and-player': {deps: ['require'], exports: "MediaElementPlayer"}
}
});
// Later on the code...
require(['path/to/hls'], function (Hls) {
window.Hls = Hls;
require(['path/to/mediaelement-and-player'], function (MediaElementPlayer) {
var player = new MediaElementPlayer('media-id', {
// Player configuration
});
});
});
```
**IMPORTANT NOTE:** To keep Flash shims working you **MUST** setup the path where the shims are via `pluginPath`, and do not forget to add a slash at the end of the string. Please refer to the examples above. In Meteor, the right path to be used is `/packages/johndyer_mediaelement/build/`;
<a id="react"></a>
### React
With `React.js`, you will need to install the external libraries the same way as `Require`.
Once installed through NPM, you will be able to create your component using `MediaElement`. As an example:
**MediaElement.js**
```javascript
import React, { Component } from 'react';
import 'hls.js';
import 'mediaelement';
// Import stylesheet and shims
import 'mediaelement/build/mediaelementplayer.min.css';
import 'mediaelement/build/mediaelement-flash-video.swf';
export default class MediaElement extends Component {
state = {}
success(media, node, instance) {
// Your action when media was successfully loaded
}
error(media) {
// Your action when media had an error loading
}
render() {
const
props = this.props,
sources = JSON.parse(props.sources),
tracks = JSON.parse(props.tracks),
sourceTags = [],
tracksTags = []
;
for (let i = 0, total = sources.length; i < total; i++) {
const source = sources[i];
sourceTags.push(`<source src="${source.src}" type="${source.type}">`);
}
for (let i = 0, total = tracks.length; i < total; i++) {
const track = tracks[i];
tracksTags.push(`<track src="${track.src}" kind="${track.kind}" srclang="${track.lang}"${(track.label ? ` label=${track.label}` : '')}>`);
}
const
mediaBody = `${sourceTags.join("\n")}
${tracksTags.join("\n")}`,
mediaHtml = props.mediaType === 'video' ?
`<video id="${props.id}" width="${props.width}" height="${props.height}"${(props.poster ? ` poster=${props.poster}` : '')}
${(props.controls ? ' controls' : '')}${(props.preload ? ` preload="${props.preload}"` : '')}>
${mediaBody}
</video>` :
`<audio id="${props.id}" width="${props.width}" controls>
${mediaBody}
</audio>`
;
return (<div dangerouslySetInnerHTML={{__html: mediaHtml}}></div>);
}
componentDidMount() {
const {MediaElementPlayer} = global;
if (!MediaElementPlayer) {
return;
}
const options = Object.assign({}, JSON.parse(this.props.options), {
// Read the Notes below for more explanation about how to set up the path for shims
pluginPath: './static/media/',
success: (media, node, instance) => this.success(media, node, instance),
error: (media, node) => this.error(media, node)
});
this.setState({player: new MediaElementPlayer(this.props.id, options)});
}
componentWillUnmount() {
if (this.state.player) {
this.state.player.remove();
this.setState({player: null});
}
}
}
```
So you can use your component like as follows.
**App.js**
```javascript
import React, { Component } from 'react';
import './App.css';
import MediaElement from './MediaElement';
export default class App extends Component {
// Other code
render() {
const
sources = [
{src: 'http://www.streambox.fr/playlists/test_001/stream.m3u8', type: 'application/x-mpegURL'},
{src: 'http://clips.vorwaerts-gmbh.de/big_buck_bunny.mp4', type: 'video/mp4'},
{src: 'rtmp://firehose.cul.columbia.edu:1935/vod/mp4:sample.mp4', type: 'video/rtmp'}
],
config = {},
tracks = {}
;
return (
<MediaElement
id="player1"
mediaType="video"
preload="none"
controls
width="640"
height="360"
poster=""
sources={JSON.stringify(sources)}
options={JSON.stringify(config)}
tracks={JSON.stringify(tracks)}
/>);
}
}
```
**IMPORTANT NOTES**
* If you want to support Flash renderers, you **MUST** activate a file loader in WebPack's configuration file in order to send the shims to the correct location (`./static/media/` in the example above). Something like this:
```javascript
module: {
// All previous code
loaders: [
// All previous loaders
{
test: /\.swf$/,
loader: 'file',
query: {
name: 'static/media/[name].[ext]'
}
}
]
}
```
* For other renderers that cannot be installed through NPM, such as YouTube, you might need to load their script through `componentDidMount` method:
```javascript
componentDidMount() {
let loaded = false;
if (!loaded) {
const tag = document.createElement('script');
tag.src = '//www.youtube.com/player_api';
const firstScriptTag = document.getElementsByTagName('script')[0];
firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);
loaded = true;
}
}
```
<a id="renderers-usage"></a>
## Use Renderers
After the `MediaElement` package has been loaded, include any renderer(s) you are planning to use that not part of the main bundle (`mediaelement-and-player.js`). For example, to include Vimeo and Twitch support:
```html
<script src="/path/to/mediaelement-and-player.min.js"></script>
<script src="/path/to/renderers/vimeo.min.js"></script>
<script src="/path/to/renderers/twitch.min.js"></script>
```
By default, all the renderers will be called by their IDs and the plugin will try to detect the best one.
However, if you need to use just a subset of renderers in a specific order, you must list their IDs using `renderers` option when configuring your player.
```javascript
// Use globally native M(PEG)-DASH renderer first, then Flash shim
mejs.Renderers.order = ['native_dash', 'flash_dash'];
$('video, audio').mediaelementplayer({
renderers: ['native_dash', 'flash_dash'], // Use only M(PEG)DASH renderers
// More configuration
});
```
`MediaElement` can invoke methods from the current renderer's API. An example using native HLS:
```javascript
$('video').mediaelementplayer({
pluginPath: '../build/',
// All the config related to HLS
hls: {
debug: true
},
// More configuration parameters...
success: function(media, node, instance) {
// Use the conditional to detect if you are using `native_hls` renderer for that given media;
// otherwise, you don't need it
if (Hls !== undefined) {
media.addEventListener(Hls.Events.MEDIA_ATTACHED, function () {
// All the code when this event is reached...
console.log('Media attached!');
});
// Manifest file was parsed, invoke loading method
media.addEventListener(Hls.Events.MANIFEST_PARSED, function () {
// All the code when this event is reached...
console.log('Manifest parsed!');
});
media.addEventListener(Hls.Events.FRAG_PARSING_METADATA, function (event, data) {
// All the code when this event is reached...
console.log(data);
});
}
}
});
```
<a id="renderers-list"></a>
Below are listed the renderers with their IDs and player instance to execute other methods from APIs.
Renderer | ID | Reference | MIME Type(s)
--- | -- | --- | ---
Native video/audio | `html5` | --- | video/mp4, audio/mp4, video/webm, audio/mpeg, audio/mp3, audio/ogg, audio/oga, video/ogg
HLS native | `native_hls` | [`hls.js` API](https://github.com/dailymotion/hls.js/blob/master/doc/API.md) | application/x-mpegURL, vnd.apple.mpegURL
M(PEG)-DASH native | `native_dash` | [`dash.js` Documentation](http://cdn.dashjs.org/latest/jsdoc/index.html) | application/dash+xml
FLV native | `native_flv` | [`flv.js` API](https://github.com/Bilibili/flv.js/blob/master/docs/api.md) | video/flv
SoundCloud | `soundcloud_iframe` | [SoundCloud Widget API](https://developers.soundcloud.com/docs/api/html5-widget) | video/soundcloud, video/x-soundcloud
Facebook | `facebook` | --- | video/facebook, video/x-facebook
Vimeo | `vimeo_iframe` | [Vimeo Player API](https://github.com/vimeo/player.js) | video/vimeo, video/x-vimeo
YouTube | `youtube_iframe` | [YouTube IFrame Player API](https://developers.google.com/youtube/iframe_api_reference) | video/youtube, video/x-youtube
DailyMotion | `dailymotion_iframe` | [Dailymotion Player API](https://developer.dailymotion.com/player#player-api) | video/dailymotion, video/x-dailymotion
Twitch | `twitch_iframe` | [Twitch Emded API](https://github.com/justintv/Twitch-API/blob/master/embed-video.md) | video/twitch, video/x-twitch
Video shim | `flash_video` | --- | video/mp4, video/rtmp, audio/rtmp, rtmp/mp4, audio/mp4
Audio shim | `flash_audio` | --- | audio/mp3
OGG Audio shim | `flash_audio_ogg` | --- | audio/ogg, audio/oga
HLS shim | `flash_hls` | [FlasHLS Events](https://github.com/mangui/flashls/blob/dev/API.md) | application/x-mpegURL, vnd.apple.mpegURL
M(PEG)-DASH shim | `flash_dash` | --- |application/dash+xml
To know how well-supported are each one of the formats, visit http://caniuse.com/
**IMPORTANT NOTES**
1. Only renderers prefixed as __native__, YouTube, and Flash shim, are integrated by default on the player. The rest of the renderers are stored in the `build/renderers` folder.
2. For `flash_hls`, you can use the events listed on https://github.com/mangui/flashls/blob/dev/API.md by prepending __on__ followed by the event name in camelcase notation;
i.e., to call `FRAGMENT_PLAYING`, you need to write `onFragmentPlaying` on JS. The events that return objects will have the info in the `data` attribute of the object; the rest, on the `message` attribute.
**Notes**
* Support for `wmv` and `wma` has been dropped since most of the major players are not supporting it as well.
* `ogg` formats will not play consistently in all browsers so it is strongly recommended a MP3 fallback for audio, or MP4 for video.
* `wav` and `webm` formats will only play on Browsers that support it natively since there is currently no Flash fallback to allow them to play in other browsers.
* `flv` and `mpd` will not work on iOS since it doesn't support MSE; for `mpd` use a `m3u8` fallback.
* Soundcloud can play with `html5` renderer using the following URL format: `https://api.soundcloud.com/tracks/XXX/stream?client_id=XXX`
<a id="streching-modes"></a>
## Use `stretching` modes
`MediaElementPlayer` accepts 4 different stretching modes. The following table describes how to set each one of them.
Mode | Setup
---- | -------
auto | Mode by default, this mode checks if there are any elements in the `video`/`audio` tag to turn the _responsive_ mode; if not, will set it up in _none_ mode.
responsive | Can be turned on by setting `max-width: 100%` style (inline, or in the stylesheet), or `width="100%" height="100%"` attributes in the `video`/`audio` tag. In Javascript, set in the player's configuration `stretching: 'responsive'` (preferred) or `videoWidth: '100%' videoHeight: '100%'`.
fill | This mode will crop the video to adapt it to the dimensions of the parent container by only setting up `stretching: 'fill'`. It is encouraged to set up the parent's `height` to `100%` to make it work as expected.
none | Use `width` and `height` attributes specified in the `video`/`audio` tags and no `max-width: 100%` or `width="100%" height="100%"` attributes; otherwise, use the `stretching: 'none'` configuration element to achieve this.
<a id="grid"></a>
## Responsive grid
Since `MediaElement` can adapt its size to be responsive, some might be tempted to use CSS or Javascript to create a responsive grid of videos.
So far, right now the best plugin to be used with `MediaElement` for this task has been [Flexr](http://flexrgrid.com/).
<a id="captions"></a>
## Setting new captions
With `MediaElementPlayer`, the way to do it is just setting the new values for required attributes (`srclang`, `kind` and `src`) and optionally, `label`,
in the `track` tags for all browsers **EXCEPT Safari Desktop**.
With Safari Desktop in its latest version, due to a keyboard trap issue generated when appending the original `video` tag containing `track` element during the construction
of the player, it is necessary to create `track` tags with the attributes specified above, and override the `trackFiles` array.
```javascript
var player = new MediaElementPlayer('#player');
const track = document.createElement('track');
track.kind = 'subtitles';
track.label = 'English';
track.src = '/path/to/captions.vtt';
track.srclang = 'en';
// In this example, we are assuming there is only on `track` tag;
// if there are more, implement your logic to override the necessary one(s)
if (player.trackFiles !== null) {
player.trackFiles = [track];
}
```
Once you set up the new values for the track attributes, or defined the workflow for Safari, it is required to register the new track(s) as follows:
```javascript
player.findTracks();
// This way we are ensuring ALL tracks are being loaded, starting from the first one
player.loadTrack(0);
// Set the default language using the ID of the language.
// Check the radio buttons generated by the player to see the ID you want to set, or use `none`
player.setTrack('mep_0_track_0_subtitles_en');
```
<a id="destroy"></a>
## Destroy player
In order to destroy the player, you must pause the player and then invoke the `remove()` method.
```javascript
var player = new MediaElementPlayer('#player');
// Using jQuery:
// var playerId = $('#mediaplayer').closest('.mejs__container').attr('id');
// var player = mejs.players[playerId];
if (!player.paused) {
player.pause();
}
player.remove();
// If you wanna destroy COMPLETELY the player (including also the `video` tag) use the above and also the following:
var videos = document.getElementsByTagName('video');
for( var i = 0, total = videos.length; i < total; i++ ){
videos[i].parentNode.removeChild(videos[i]);
}
// Using jQuery:
// $('video').each(function() {
// $(this).remove();
// });
```
Same code can be used for `<audio>` elements.
________
[Back to Main](../README.md)