README.md
1# 
2
3One file. Any browser. Same UI.
4
5* Author: John Dyer [http://j.hn/](http://j.hn/)
6* Website: [http://mediaelementjs.com/](http://mediaelementjs.com/)
7* License: [MIT](http://mediaelement.mit-license.org/)
8* Meaning: Use everywhere, keep copyright, it'd be swell if you'd link back here.
9* Thanks: my employer, [Dallas Theological Seminary](http://www.dts.edu/)
10* Contributors: [all contributors](https://github.com/mediaelement/mediaelement/graphs/contributors)
11
12[](https://github.com/mediaelement/mediaelement)
13[](https://travis-ci.org/mediaelement/mediaelement)
14[](https://coveralls.io/github/mediaelement/mediaelement)
15[](https://mediaelement.mit-license.org/)
16[](https://cdnjs.com/libraries/mediaelement)
17[](https://www.jsdelivr.com/package/npm/mediaelement)
18
19# Table of Contents
20
21* [Introduction](#intro)
22* [Migrating from `2.x` to `4.x` version](#migration)
23* [Installation and Usage](#installation)
24* [API and Configuration](#api)
25* [Guidelines for Contributors](#guidelines)
26* [Change Log](#changelog)
27* [TODO list](#todo)
28
29<a id="intro"></a>
30## Introduction
31
32_MediaElementPlayer: HTML5 `<video>` and `<audio>` player_
33
34A complete HTML/CSS audio/video player built on top `MediaElement.js`. Many great HTML5 players have a completely separate Flash UI in fallback mode, but MediaElementPlayer.js uses the same HTML/CSS for all players.
35
36`MediaElement.js` is a set of custom Flash plugins that mimic the HTML5 MediaElement API for browsers that don't support HTML5 or don't support the media codecs you're using.
37Instead of using Flash as a _fallback_, Flash is used to make the browser seem HTML5 compliant and enable codecs like H.264 (via Flash) on all browsers.
38
39In general, `MediaElement.js` supports **IE11+, MS Edge, Chrome, Firefox, Safari, iOS 8+** and **Android 4.0+**.
40
41**It is strongly recommended to read the entire documentation and check the `demo` folder to get the most out of this package**. Visit [here](docs) to start.
42
43## * IMPORTANT NOTE for Safari users (Jun 8, 2017)
44
45Since Sierra version, `autoplay` policies have changed. You may experience an error if you try to execute `play` programmatically or via `autoplay` attribute with MediaElement, unless `muted` attribute is specified.
46
47For more information, read https://webkit.org/blog/7734/auto-play-policy-changes-for-macos/
48
49
50## * IMPORTANT CHANGES on `4.2.0` version
51
52As part of the continuous improvements the player, we have decided to drop completely support for IE9 and IE10, since market share of those browsers together is 0.4%, according to http://caniuse.com/usage-table.
53
54This change is for `MediaElement` and `MediaElement Plugins` repositories.
55
56<a id="migration"></a>
57## * IMPORTANT: Migrating from `2.x` to `4.x` version
58
59**NOTE:** `3.x` version has jQuery in the code base, and `4.x` is framework-agnostic. So for either `3.x` or `4.x` versions, the following steps are valid, but it is highly recommended to upgrade to `4.x`.
60
61In order to successfully install `4.x` in an existing setup, you must consider the following guidelines:
62
631. If your installation relies on the legacy player classes (i.e., `mejs-player`, `mejs-container`, etc.), you **must** set up the proper namespace. In `2.x`, the default namespace is `mejs-` but now is `mejs__`. In order to set up a new namespace (or the legacy one), use the `classPrefix` configuration, and make sure you use the `mediaelementplayer-legacy` stylesheet provided in the `/build/` folder.
64
652. By default, `MediaElement` has bundled native renderers, such as HLS, M(PEG)-DASH and FLV, as well as YouTube and Flash shims. **If you want to use any other renderer, you MUST refer to the `build/renderers` folder and add as many as you want**. Check `demo/index.html` for a better reference.
66
673. You **must** set up now the path for the Flash shims if they are not in the same folder as the JS files. To do this, set the path via the `pluginPath` configuration. In the same topic, if you need to support browsers with JavaScript disabled, you **must** reference the correct Flash shim, since in `2.x` there was only a single Flash shim and in `3.x` it was split to target specific media types. Check the [Browsers with JavaScript disabled](docs/installation.md#disabled-javascript) section for more details.
68
694. If you want to use Flash shims from a CDN, do the change related to `pluginPath` setting the CDN's URL, and also setting `shimScriptAccess` configuration as **`always`**.
70
715. If you need to force the Flash shim, the way to do it in `3.x` version is to use the `renderers` configuration and list them in an array.
72
736. `pluginType` was removed to favor `rendererName`. If you rely on that element, just create conditionals based on the renderer ID (all listed [here](docs/usage.md#renderers-list)). For example:
74
75```javascript
76$('video, audio').mediaelementplayer({
77 // Configuration
78 success: function(media) {
79 var isNative = /html5|native/i.test(media.rendererName);
80
81 var isYoutube = ~media.rendererName.indexOf('youtube');
82
83 // etc.
84 }
85});
86```
87
88<a id="installation"></a>
89## Installation and Usage
90
91The full documentation on how to install `MediaElement.js` is available at [Installation](docs/installation.md).
92
93A brief guide on how to create and use instances of `MediaElement` available at [Usage](docs/usage.md).
94
95Additional features can be found at https://github.com/mediaelement/mediaelement-plugins.
96
97<a id="api"></a>
98## API and Configuration
99
100`MediaElement.js` has many options that you can take advantage from. Visit [API and Configuration](docs/api.md) for more details.
101
102Also, a `Utilities/Features` guide is available for development. Visit [Utilities/Features](docs/utils.md) for more details.
103
104<a id="guidelines"></a>
105## Guidelines for Contributors
106
107If you want to contribute to improve this package, please read [Guidelines](docs/guidelines.md).
108
109**NOTE**: If you would like to contribute with translations, make sure that you also check https://github.com/mediaelement/mediaelement-plugins, and perform the
110translations for the files suffixed as `-i18n`.
111
112<a id="sources"></a>
113## Useful resources
114
115A compilation of useful articles can be found [here](docs/resources.md).
116
117<a id="changelog"></a>
118## Change Log
119
120Changes available at [Change Log](changelog.md).
121
122<a id="todo"></a>
123## TODO list
124
125**IMPORTANT:** Before posting an issue, it is strongly encouraged to read the whole documentation since it covers the majority of scenarios exposed in prior issues.
126
127New features and pending bugs can be found at [TODO list](TODO.md).
128
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}