From 62d9913c2faa7914d2f867e163d3f3328c934d5e Mon Sep 17 00:00:00 2001
From: Pat O'Neill <pgoneill@gmail.com>
Date: Thu, 20 Oct 2016 09:58:27 -0400
Subject: [PATCH 01/20] Rewrite setup.md

---
 docs/guides/setup.md | 132 ++++++++++++++-----------------------------
 1 file changed, 42 insertions(+), 90 deletions(-)

diff --git a/docs/guides/setup.md b/docs/guides/setup.md
index 7e6a81f576..ad215e941d 100644
--- a/docs/guides/setup.md
+++ b/docs/guides/setup.md
@@ -1,124 +1,76 @@
-Setup
-=====
+# Video.js Setup
 
-Video.js is pretty easy to set up. It can take a matter of seconds to get the player up and working on your web page.
+## Installing Video.js
 
-Step 1: Include the Video.js Javascript and CSS files in the head of your page.
-------------------------------------------------------------------------------
+Video.js is officially available via CDN, npm, and Bower.
 
-You can download the Video.js source and host it on your own servers, or use the free CDN hosted version. As of Video.js 5.0, the source is [transpiled from ES2015](http://babeljs.io/) (formerly known as ES6) to [ES5](https://es5.github.io/), but IE8 only supports ES3. In order to continue to support IE8, we've bundled an [ES5 shim and sham](https://github.com/es-shims/es5-shim) together and hosted it on the CDN.
+Please refer to the [Getting Started][getting-started] document for details.
 
-```html
-<script src="//vjs.zencdn.net/ie8/1.1.1/videojs-ie8.min.js"></script>
-```
+## Decorating a `<video>` Element
 
-### CDN Version ###
-```html
-<link href="//vjs.zencdn.net/5.4.6/video-js.min.css" rel="stylesheet">
-<script src="//vjs.zencdn.net/5.4.6/video.min.js"></script>
-```
+Once you have Video.js [loaded on your page][getting-started], you're ready to create a player!
 
-Alternatively you can always [go here](http://videojs.com/getting-started/) to get the latest URL for videojs CDN.
-
-We include a stripped down Google Analytics pixel that tracks a random percentage (currently 1%) of players loaded from the CDN. This allows us to see (roughly) what browsers are in use in the wild, along with other useful metrics such as OS and device. If you'd like to disable analytics, you can simply include the following global **before** including Video.js:
-
-```js
-window.HELP_IMPROVE_VIDEOJS = false;
-```
+> Note: Video.js works with `<video>` _and_ `<audio>` elements, but for simplicity we'll refer only to `<video>` elements going forward!
 
-## Install via package manager
+The core strength of Video.js is that it decorates a [standard `<video>` element][w3c-video] and emulates its associated [events and APIs][w3c-media-events], while providing a customizable DOM-based UI.
 
-### NPM
-```
-$ npm install --save video.js
-```
+Video.js supports all attributes of the `<video>` element (such as `controls`, `preload`, etc), but it also supports [its own options][options]. There are two ways to create a Video.js player and pass it options, but they both start with a standard `<video>` element with the attribute `class="video-js"`:
 
-### Bower
-```
-$ bower install --save video.js
+```html
+<video class="video-js">
+  <source src="//vjs.zencdn.net/v/oceans.mp4" type="video/mp4">
+  <source src="//vjs.zencdn.net/v/oceans.webm" type="video/webm">
+</video>
 ```
 
+### Automatic Setup
 
-### Self Hosted. ###
-To entirely self-host, you'll need to pull in the font files and let Video.js know where the swf is located. If you simply copy the dist folder or zip file contents into your project everything
-should Just Work™, but the paths can easily be changed by editing the LESS file and re-building, or by modifying the generated CSS file. Additionally include the [videojs-vtt.js](https://www.npmjs.com/package/videojs-vtt.js) source, which adds the `WebVTT` object to the global scope.
+By default, when your web page finishes loading, Video.js will scan for media elements that have the `data-setup` attribute. The `data-setup` attribute is used to provide [options][options] to Video.js. The minimum example looks like this:
 
 ```html
-<link href="//example.com/path/to/video-js.min.css" rel="stylesheet">
-<script src="//example.com/path/to/videojs-vtt.js"></script>
-<script src="//example.com/path/to/video.min.js"></script>
-<script>
-  videojs.options.flash.swf = "http://example.com/path/to/video-js.swf"
-</script>
+<video class="video-js" data-setup='{}'>
+  <source src="//vjs.zencdn.net/v/oceans.mp4" type="video/mp4">
+  <source src="//vjs.zencdn.net/v/oceans.webm" type="video/webm">
+</video>
 ```
 
+> Note: You **must** use single-quotes with `data-setup` as it is expected to contain JSON and it **must** contain `'{}'` at a minimum!
 
-Step 2: Add an HTML5 video tag to your page.
---------------------------------------------
-With Video.js you just use an HTML5 video tag to embed a video. Video.js will then read the tag and make it work in all browsers, not just ones that support HTML5 video. Beyond the basic markup, Video.js needs a few extra pieces.
+### Manual Setup
 
-> Note: The `data-setup` attribute described here should not be used if you use the alternative setup described in the next section.
+From updating the DOM via standard APIs to full-fledged frameworks like React and Ember, a `<video>` element often does not exist when the page finishes loading. In these cases, automatic setup is not possible, but manual setup is available via [the `videojs` function][videojs].
 
-  1. The 'data-setup' Attribute tells Video.js to automatically set up the video when the page is ready, and read any options (in JSON format) from the attribute (see [options](./options.md)). There are other methods for initializing the player, but this is the easiest.
+One way to call this function is by providing it a string matching a `<video>` element's `id` attribute:
 
-  2. The 'id' Attribute: Should be used and unique for every video on the same page.
-
-  3. The 'class' attribute contains two classes:
-    - `video-js` applies styles that are required for Video.js functionality, like fullscreen and subtitles.
-    - `vjs-default-skin` applies the default skin to the HTML controls, and can be removed or overridden to create your own controls design.
-
-Otherwise include/exclude attributes, settings, sources, and tracks exactly as you would for HTML5 video.*
 ```html
-<video id="example_video_1" class="video-js vjs-default-skin"
-  controls preload="auto" width="640" height="264"
-  poster="http://video-js.zencoder.com/oceans-clip.png"
-  data-setup='{"example_option":true}'>
- <source src="http://video-js.zencoder.com/oceans-clip.mp4" type="video/mp4" />
- <source src="http://video-js.zencoder.com/oceans-clip.webm" type="video/webm" />
- <source src="http://video-js.zencoder.com/oceans-clip.ogv" type="video/ogg" />
- <p class="vjs-no-js">To view this video please enable JavaScript, and consider upgrading to a web browser that <a href="http://videojs.com/html5-video-support/" target="_blank">supports HTML5 video</a></p>
+<video id="my-player" class="video-js">
+  <source src="//vjs.zencdn.net/v/oceans.mp4" type="video/mp4">
+  <source src="//vjs.zencdn.net/v/oceans.webm" type="video/webm">
 </video>
 ```
 
-By default, the big play button is located in the upper left hand corner so it doesn't cover up the interesting parts of the poster. If you'd prefer to center the big play button, you can add an additional `vjs-big-play-centered` class to your video element. For example:
+```js
+videojs('my-player');
+```
+
+Using an `id` attribute isn't always practical when your DOM is generated programmatically. In that case, Video.js accepts a DOM element instead:
 
 ```html
-<video id="example_video_1" class="video-js vjs-default-skin vjs-big-play-centered"
-  controls preload="auto" width="640" height="264"
-  poster="http://video-js.zencoder.com/oceans-clip.png"
-  data-setup='{"example_option":true}'>
-  ...
+<video class="video-js">
+  <source src="//vjs.zencdn.net/v/oceans.mp4" type="video/mp4">
+  <source src="//vjs.zencdn.net/v/oceans.webm" type="video/webm">
 </video>
 ```
 
-Alternative Setup for Dynamically Loaded HTML
----------------------------------------------
-If your web page or application loads the video tag dynamically (ajax, appendChild, etc.), so that it may not exist when the page loads, you'll want to manually set up the player instead of relying on the data-setup attribute. To do this, first remove the data-setup attribute from the tag so there's no confusion around when the player is initialized. Next, run the following javascript some time after the Video.js javascript library has loaded, and after the video tag has been loaded into the DOM.
 ```js
-videojs("example_video_1", {}, function(){
-  // Player (this) is initialized and ready.
-});
+videojs(document.querySelector('.video-js'));
 ```
 
-The first argument in the `videojs` function is the ID of your video tag. Replace it with your own.
-
-The second argument is an options object. It allows you to set additional options like you can with the data-setup attribute.
-
-The third argument is a 'ready' callback. Once Video.js has initialized it will call this function.
+Regardless, in either case, the `data-setup` attribute is still supported for providing [options][options] to Video.js. Additionally, the `videojs` function can take options as its second argument.
 
-Instead of using an element ID, you can also pass a reference to the element itself.
-
-```js
-videojs(document.getElementById('example_video_1'), {}, function() {
-  // This is functionally the same as the previous example.
-});
-```
-
-```js
-videojs(document.getElementsByClassName('awesome_video_class')[0], {}, function() {
-  // You can grab an element by class if you'd like, just make sure
-  // if it's an array that you pick one (here we chose the first).
-});
-```
 
-\* If you have trouble playing back content you know is in the [correct format](http://blog.zencoder.com/2013/09/13/what-formats-do-i-need-for-html5-video/), your HTTP server might not be delivering the content with the correct [MIME type](http://en.wikipedia.org/wiki/Internet_media_type#Type_video). Please double check your content's headers before opening an [issue](/CONTRIBUTING.md).
+[getting-started]: http://videojs.com/getting-started/
+[options]: options.md
+[videojs]: http://docs.videojs.com/docs/api/video.html
+[w3c-media-events]: https://www.w3.org/2010/05/video/mediaevents.html
+[w3c-video]: http://www.w3.org/TR/html5/embedded-content-0.html#the-video-element

From 948897e7ac8256657705214acf0f2d122720fbf7 Mon Sep 17 00:00:00 2001
From: Pat O'Neill <pgoneill@gmail.com>
Date: Thu, 20 Oct 2016 12:52:38 -0400
Subject: [PATCH 02/20] Rewrite README

---
 README.md | 101 +++++++++++++++++++++++++++++++++++-------------------
 1 file changed, 66 insertions(+), 35 deletions(-)

diff --git a/README.md b/README.md
index 8afda5bcf3..e7a8626b3c 100644
--- a/README.md
+++ b/README.md
@@ -1,65 +1,96 @@
-![Video.js logo](http://videojs.com/img/logo.png)
+![Video.js logo][logo]
 
-# [Video.js - HTML5 Video Player](http://videojs.com)
-[![Build Status](https://travis-ci.org/videojs/video.js.svg?branch=master)](https://travis-ci.org/videojs/video.js)
-[![Coverage Status](https://coveralls.io/repos/github/videojs/video.js/badge.svg?branch=master)](https://coveralls.io/github/videojs/video.js?branch=master)
-[![Slack Status](http://slack.videojs.com/badge.svg)](http://slack.videojs.com)
+# [Video.js - HTML5 Video Player][vjs]
 
+[![Build Status][travis-icon]][travis-link]
+[![Coverage Status][coveralls-icon]][coveralls-link]
+[![Slack Status][slack-icon]][slack-link]
 
-[![NPM](https://nodei.co/npm/video.js.png?downloads=true&downloadRank=true)](https://nodei.co/npm/video.js/)
+[![NPM][npm-icon]][npm-link]
 
-> Video.js is a web video player built from the ground up for an HTML5 world. It supports HTML5 and Flash video, as well as YouTube and Vimeo (through [plugins](https://github.com/videojs/video.js/wiki/Plugins)). It supports video playback on desktops and mobile devices. This project was started mid 2010, and the player is now used on over ~~50,000~~ ~~100,000~~ 200,000 websites.
+> Video.js is a web video player built from the ground up for an HTML5 world. It supports HTML5 and Flash video, as well as YouTube and Vimeo (through [plugins][plugins]). It supports video playback on desktops and mobile devices. This project was started mid 2010, and the player is now used on over ~~50,000~~ ~~100,000~~ 200,000 websites.
 
-## Quick start
-Thanks to the awesome folks over at [Fastly](http://www.fastly.com/), there's a free, CDN hosted version of Video.js that anyone can use.
-Also, check out the [Getting Started](http://videojs.com/getting-started/) page on our website which has the latest urls as well.
-Simply add these includes to your document's
-`<head>`:
+## Quick Start
+
+Thanks to the awesome folks over at [Fastly][fastly], there's a free, CDN hosted version of Video.js that anyone can use. Add these tags to your document's `<head>`:
 
 ```html
-<link href="//vjs.zencdn.net/5.8/video-js.min.css" rel="stylesheet">
-<script src="//vjs.zencdn.net/5.8/video.min.js"></script>
+<link href="//vjs.zencdn.net/5.11/video-js.min.css" rel="stylesheet">
+<script src="//vjs.zencdn.net/5.11/video.min.js"></script>
 ```
 
-Then, whenever you want to use Video.js you can simply use the `<video>` element as your normally would, but with an additional `data-setup` attribute containing any Video.js options. These options
-can include any Video.js option plus potential [plugin](http://videojs.com/plugins/) options, just make sure they're valid JSON!
+> For the latest URLs, check out the [Getting Started][getting-started] page on our website.
+
+Next, using Video.js is as simple as creating a `<video>` element, but with an additional `data-setup` attribute. At a minimum, this attribute must have a value of `'{}'`, but it can include any Video.js [options][options] - just make sure it contains valid JSON!
 
 ```html
-<video id="really-cool-video" class="video-js vjs-default-skin" controls
- preload="auto" width="640" height="264" poster="really-cool-video-poster.jpg"
- data-setup='{}'>
-  <source src="really-cool-video.mp4" type="video/mp4">
-  <source src="really-cool-video.webm" type="video/webm">
+<video
+    id="my-player"
+    class="video-js"
+    controls
+    preload="auto"
+    poster="//vjs.zencdn.net/v/oceans.png"
+    data-setup='{}'>
+  <source src="//vjs.zencdn.net/v/oceans.mp4" type="video/mp4"></source>
+  <source src="//vjs.zencdn.net/v/oceans.webm" type="video/webm"></source>
+  <source src="//vjs.zencdn.net/v/oceans.ogv" type="video/ogg"></source>
   <p class="vjs-no-js">
-    To view this video please enable JavaScript, and consider upgrading to a web browser
-    that <a href="http://videojs.com/html5-video-support/" target="_blank">supports HTML5 video</a>
+    To view this video please enable JavaScript, and consider upgrading to a
+    web browser that
+    <a href="http://videojs.com/html5-video-support/" target="_blank">
+      supports HTML5 video
+    </a>
   </p>
 </video>
 ```
 
-If you don't want to use auto-setup, you can leave off the `data-setup` attribute and initialize a video element manually.
+When the page loads, Video.js will find this element and automatically setup a player in its place.
+
+If you don't want to use automatic setup, you can leave off the `data-setup` attribute and initialize a `<video>` element manually:
 
-```javascript
-var player = videojs('really-cool-video', { /* Options */ }, function() {
-  console.log('Good to go!');
+```js
+var player = videojs('my-player', { /* options */ }, function() {
+  videojs.log('Your player is ready!');
 
-  this.play(); // if you don't trust autoplay for some reason
+  // If you don't trust autoplay for some reason...
+  this.play();
 
   // How about an event listener?
   this.on('ended', function() {
-    console.log('awww...over so soon?');
+    videojs.log('Awww...over so soon?!');
   });
 });
 ```
 
-If you're ready to dive in, the [documentation](http://docs.videojs.com) is the first place to go for more information.
+If you're ready to dive in, the [Getting Started][getting-started] page and [documentation][docs] are the best places to go for more information. If you get stuck, head over to our [Slack channel][slack-link]!
 
 ## Contributing
-Video.js is a free and open source library, and we appreciate any help you're willing to give. Check out the [contributing guide](/CONTRIBUTING.md).
 
-_Video.js uses [BrowserStack](https://browserstack.com) for compatibility testing_
-## Building your own Video.js from source
-To build your own custom version read the section on [contributing code](/CONTRIBUTING.md#contributing-code) and ["Building your own copy"](/CONTRIBUTING.md#building-your-own-copy-of-videojs) in the contributing guide.
+Video.js is a free and open source library, and we appreciate any help you're willing to give - whether it's fixing bugs, improving documentation, or suggesting new features. Check out the [contributing guide][contributing] for more!
+
+_Video.js uses [BrowserStack][browserstack] for compatibility testing._
+
 ## License
 
-Video.js is licensed under the Apache License, Version 2.0. [View the license file](LICENSE)
+Video.js is [licensed][license] under the Apache License, Version 2.0.
+
+[browserstack]: https://browserstack.com
+[contributing]: CONTRIBUTING.md
+[contributing-building]: CONTRIBUTING.md#building-your-own-copy-of-videojs
+[contributing-code]: CONTRIBUTING.md#contributing-code
+[coveralls-icon]: https://coveralls.io/repos/github/videojs/video.js/badge.svg?branch=master
+[coveralls-link]: https://coveralls.io/github/videojs/video.js?branch=master
+[docs]: http://docs.videojs.com
+[fastly]: http://www.fastly.com/
+[getting-started]: http://videojs.com/getting-started/
+[license]: LICENSE
+[logo]: http://videojs.com/img/logo.png
+[npm-icon]: https://nodei.co/npm/video.js.png?downloads=true&downloadRank=true
+[npm-link]: https://nodei.co/npm/video.js/
+[options]: docs/options.md
+[plugins]: http://videojs.com/plugins/
+[slack-icon]: http://slack.videojs.com/badge.svg
+[slack-link]: http://slack.videojs.com
+[travis-icon]: https://travis-ci.org/videojs/video.js.svg?branch=master
+[travis-link]: https://travis-ci.org/videojs/video.js
+[vjs]: http://videojs.com

From 97db4876c5dc3d187b191a15e12e83c5f4bb0d2a Mon Sep 17 00:00:00 2001
From: Pat O'Neill <pgoneill@gmail.com>
Date: Thu, 20 Oct 2016 13:39:36 -0400
Subject: [PATCH 03/20] Rewrite index.md

---
 docs/index.md | 64 ++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 48 insertions(+), 16 deletions(-)

diff --git a/docs/index.md b/docs/index.md
index 78df309bf1..5427bf0030 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,37 +1,69 @@
-[Video.js homepage](http://videojs.com)
+# [Video.js][vjs] Documentation
 
-<h1>Video.js Documentation</h1>
+There are two categories of docs: [Guides][guides] and [API docs][api].
 
-There are two categories of docs: [Guides](./guides/) and [API docs](./api/). Guides explain general topics and use cases (e.g. setup). API docs are automatically generated from the codebase and give specific details about functions, properties, and events.
-
-(Corrections and additions welcome)
+Guides explain general topics and use cases (e.g. setup). API docs are automatically generated from the codebase and give specific details about functions, properties, and events.
 
 ## Guides
 
 ### Getting Started
 
-* [Setup](./guides/setup.md) - The setup documentation gives a deeper view of the additional methods you can use to trigger the player setup.
+#### [Setup][guides-setup]
+
+The setup documentation gives a deeper view of the additional methods you can use to trigger the player setup.
+
+#### [Options][guides-options]
 
-* [Options](./guides/options.md) - There are a number of options that can be used to change how the player behaves, starting with the HTML5 media options like autoplay and preload, and expanding to Video.js specific options.
+There are a number of options that can be used to change how the player behaves, starting with the HTML5 media options like autoplay and preload, and expanding to Video.js specific options.
 
-* [Tracks](./guides/tracks.md) - Tracks are used for displaying text information over a video, selecting different audio tracks for a video, or selected different video tracks for a video.
+#### [Tracks][guides-tracks]
+
+Tracks are used for displaying text information over a video, selecting different audio tracks for a video, or selecting different video tracks.
 
 ### Customizing
 
-* [API](./guides/api.md) - The Video.js API allows you to control the video through javascript or trigger event listeners, whether the video is playing through HTML5, flash, or another playback technology.
+#### [API][guides-api]
+
+The Video.js API allows you to control the video through javascript or trigger event listeners, whether the video is playing through HTML5, flash, or another playback technology.
 
-* [Skins](./guides/skins.md) - You can change the look of the player across playback technologies just by editing a CSS file. The skins documentation gives you a intro to how the HTML and CSS of the default skin is put together.
+#### [Skins][guides-skins]
 
-* [Tech](./guides/tech.md) - A 'playback technology' is the term we're using to represent HTML5 video, Flash, and other video plugins, as well as other players like the YouTube player. Basically anything that has a unique API to audio or video. Additional playback technologies can be added relatively easily.
+You can change the look of the player across playback technologies just by editing a CSS file. The skins documentation gives you a intro to how the HTML and CSS of the default skin is put together.
 
-* [Plugins](./guides/plugins.md) - You can package up interesting Video.js customizations and reuse them elsewhere. Find out how to build your own plugin or use one created by someone else.
+#### [Tech][guides-tech]
+
+A "tech" is the shorthand we're using to describe any video playback technology - be it HTML5 video, Flash, . Basically anything that has a unique API to audio or video. Additional playback technologies can be added relatively easily.
+
+#### [Plugins][guides-plugins]
+
+You can package up interesting Video.js customizations and reuse them elsewhere. Find out how to build your own plugin or use one created by someone else.
 
 ### Resources
 
-* [Glossary](./guides/glossary.md) - Some helpful definitions.
+#### [Glossary][guides-glossary]
 
-* [Removing Players](./guides/removing-players.md) - Helpful for using VideoJS in single page apps.
+Some helpful definitions for those unfamiliar with web video-related terms - with links to more technical details.
 
 ## API Docs
-- The most relevant API doc is the [player API doc](http://docs.videojs.com/docs/api/player.html)
-- [Full list of API Docs](http://docs.videojs.com/docs/api/index.html)
+
+You can refer to the [full list of API docs][api], but the most relevant API doc is for the [Player][api-player].
+
+
+[api]: http://docs.videojs.com/docs/api/index.html
+[api-player]: http://docs.videojs.com/docs/api/player.html
+[guides]: ./guides/
+[guides-api]: ./guides/api.md
+[guides-audio]: ./guides/audio.md
+[guides-components]: ./guides/components.md
+[guides-glossary]: ./guides/glossary.md
+[guides-languages]: ./guides/languages.md
+[guides-options]: ./guides/options.md
+[guides-plugins]: ./guides/plugins.md
+[guides-removing]: ./guides/removing.md
+[guides-setup]: ./guides/setup.md
+[guides-skins]: ./guides/skins.md
+[guides-tech]: ./guides/tech.md
+[guides-text-tracks]: ./guides/text-tracks.md
+[guides-tracks]: ./guides/tracks.md
+[guides-video-tracks]: ./guides/video-tracks.md
+[vjs]: http://videojs.com

From 835e4fed36c580fecbfda201956a77db99294e94 Mon Sep 17 00:00:00 2001
From: Pat O'Neill <pgoneill@gmail.com>
Date: Sun, 23 Oct 2016 13:25:11 -0400
Subject: [PATCH 04/20] Rewrite options.md

---
 docs/guides/options.md | 330 +++++++++++++++++++++++++++++++----------
 docs/guides/setup.md   |   4 +-
 2 files changed, 256 insertions(+), 78 deletions(-)

diff --git a/docs/guides/options.md b/docs/guides/options.md
index 2e5a696311..55efb30c1a 100644
--- a/docs/guides/options.md
+++ b/docs/guides/options.md
@@ -1,138 +1,316 @@
-Options
-=======
+# Options
 
-Setting Options
----------------
+<!-- START doctoc -->
+<!-- END doctoc -->
 
-The Video.js embed code is simply an HTML5 video tag, so for many of the options you can use the standard tag attributes to set the options.
+## Setting Options
+
+Because Video.js decorates an HTML5 `<video>` element, many of the options available to you are also available as [standard `<video>` tag attributes][video-attrs]:
 
 ```html
 <video controls autoplay preload="auto" ...>
 ```
 
-Alternatively, you can use the data-setup attribute to provide options in the [JSON](http://json.org/example.html) format. This is also how you would set options that aren't standard to the video tag.
+Alternatively, you can use the `data-setup` attribute to provide options as [JSON][json]. This is also how you would set options that aren't standard to the `<video>` element:
 
 ```html
-<video data-setup='{ "controls": true, "autoplay": false, "preload": "auto" }'...>
+<video data-setup='{"controls": true, "autoplay": false, "preload": "auto"}'...>
+```
+
+Finally, if you're not using the `data-setup` attribute to trigger the player setup, you can pass in an object of player options as the second argument to the `videojs` function:
+
+```js
+videojs('my-player', {
+  controls: true,
+  autoplay: false,
+  preload: 'auto'
+});
 ```
 
-Finally, if you're not using the data-setup attribute to trigger the player setup, you can pass in an object with the player options as the second argument in the javascript setup function.
+### Setting Global Defaults
+
+Default options for all players can be found at `videojs.options`. In order to override them, mutate this object as needed. For example, to set `{autoplay: true}` for all players:
 
 ```js
-videojs("example_video_1", { "controls": true, "autoplay": false, "preload": "auto" });
+videojs.options.autoplay = true;
 ```
 
+### A Note on `<video>` Tag Attributes
 
-Individual Options
-------------------
+Many attributes are so-called [boolean attributes][boolean-attrs]. This means they are either on or off. In these cases, the attribute _should have no value_ - its presence implies a true value and its absence implies a false value.
 
-> ### Note on Video Tag Attributes ###
-> With HTML5 video tag attributes that can only be true or false (boolean), you simply include the attribute (no equals sign) to turn it on, or exclude it to turn it off. For example, to turn controls on:
+_These are incorrect:_
 
-WRONG
 ```html
 <video controls="true" ...>
+<video controls="false" ...>
 ```
 
-RIGHT
+> **Note:** The example with `controls="false"` can be a point of confusion for new developers - it will actually turn controls _on_!
+
+These are correct:
+
 ```html
 <video controls ...>
+<video ...>
 ```
 
-> The biggest issue people run into is trying to set these values to false using false as the value (e.g. controls="false") which actually does the opposite and sets the value to true because the attribute is still included. If you need the attribute to include an equals sign for XHTML validation, you can set the attribute's value to the same as its name (e.g. controls="controls").
+### Precedence
+
+There are multiple ways to provide options for Video.js, so we should be clear about which methods take precedence. From highest to lowest, the precedence rules are:
 
+1. Options as the second argument to the `videojs` function
+1. Options parsed from the `data-setup` attribute
+1. `<video>` element attributes and children
 
-### controls ###
-The controls option sets whether or not the player has controls that the user can interact with. Without controls the only way to start the video playing is with the autoplay attribute or through the API.
+For example, given:
 
 ```html
-<video controls ...>
-or
-{ "controls": true }
+<video id="foo" src="foo-1.mp4" data-setup='{"src":"foo-2.mp4"}'></video>
+<script>
+  videojs('foo', {src: 'foo-3.mp4'});
+</script>
 ```
 
+The `src` option would have the value `'foo-3.mp4'`.
 
-### autoplay ###
-If autoplay is true, the video will start playing as soon as page is loaded (without any interaction from the user).
-NOT SUPPORTED BY APPLE iOS DEVICES. Apple blocks the autoplay functionality in an effort to protect its customers from unwillingly using a lot of their (often expensive) monthly data plans. A user touch/click is required to start the video in this case.
-```html
-<video autoplay ...>
-or
-{ "autoplay": true }
-```
+## Options Reference
 
+### Standard `<video>` Element Options
 
-### preload ###
-The preload attribute informs the browser whether or not the video data should begin downloading as soon as the video tag is loaded. The options are auto, metadata, and none.
+Each of these options is also available as a standard `<video>` element attribute; so, they can be defined in all three manners [outlined above](#setting-options). Typically, defaults are not listed as this is left to browser vendors.
 
-'auto': Start loading the video immediately (if the browser agrees). Some mobile devices like iPhones and iPads will not preload the video in order to protect their users' bandwidth. This is why the value is called 'auto' and not something more final like 'true'.
+#### `autoplay`
 
-'metadata': Load only the meta data of the video, which includes information like the duration and dimensions of the video.
+> Type: `Boolean`
 
-'none': Don't preload any of the video data. This will wait until the user clicks play to begin downloading.
+If `true`/present as an attribute, begins playback automatically.
 
-```html
-<video preload ...>
-or
-{ "preload": "auto" }
-```
+> **Note:** As of iOS 10, Apple offers `autoplay` support in Safari. However, in order for it to work, the `<video>` element must have `muted` and `playsinline` attributes!
 
+#### `controls`
 
-### poster ###
-The poster attribute sets the image that displays before the video begins playing. This is often a frame of the video or a custom title screen. As soon as the user clicks play the image will go away.
-```html
-<video poster="myPoster.jpg" ...>
-or
-{ "poster": "myPoster.jpg" }
-```
+> Type: `Boolean`
 
+Determines whether or not the player has controls that the user can interact with. Without controls the only way to start the video playing is with the `autoplay` attribute or through the Player API.
 
-### loop ###
-The loop attribute causes the video to start over as soon as it ends. This could be used for a visual effect like clouds in the background.
-```html
-<video loop ...>
-or
-{ "loop": true }
+#### `height`
+
+> Type: `String|Number`
+
+Sets the display height of the video player in pixels.
+
+#### `loop`
+
+> Type: `Boolean`
+
+Causes the video to start over as soon as it ends.
+
+#### `muted`
+
+> Type: `Boolean`
+
+Will silence any audio by default.
+
+#### `poster`
+
+> Type: `String`
+
+A URL to an image that displays before the video begins playing. This is often a frame of the video or a custom title screen. As soon as the user hits "play" the image will go away.
+
+#### `preload`
+
+> Type: `String`
+
+Suggests to the browser whether or not the video data should begin downloading as soon as the `<video>` element is loaded. Supported values are:
+
+- `'auto'`
+
+  Start loading the video immediately (if the browser supports it). Some mobile devices will not preload the video in order to protect their users' bandwidth/data usage. This is why the value is called 'auto' and not something more conclusive like `'true'`.
+
+  _This tends to be the most common and recommended value as it allows the browser to choose the best behavior._
+
+- `'metadata'`
+
+  Load only the meta data of the video, which includes information like the duration and dimensions of the video.
+
+- `'none'`
+
+  Don't preload any data. The browser will wait until the user hits "play" to begin downloading.
+
+#### `src`
+
+> Type: `String`
+
+The source URL to a video source to embed.
+
+#### `width`
+
+> Type: `String|Number`
+
+Sets the display height of the video player in pixels.
+
+### Video.js-specific Options
+
+Each option is `undefined` by default unless otherwise specified.
+
+#### `aspectRatio`
+
+> Type: `String`
+
+Puts the player in [fluid](#fluid) mode and the value is used when calculating the dynamic size of the player. The value should represent a ratio - two numbers separated by a colon (e.g. `"16:9"` or `"4:3"`).
+
+#### `children`
+
+> Type: `Array`
+
+#### `fluid`
+
+> Type: `Boolean`
+
+When `true`, the Video.js player will have a fluid size. In other words, it will scale to fit its container.
+
+#### `inactivityTimeout`
+
+> Type: `Number`
+
+Video.js indicates that the user is interacting with the player by way of the `"vjs-user-active"` and `"vjs-user-inactive"` classes and the `"useractive"` event.
+
+The `inactivityTimeout` determines how many milliseconds of inactivity is required before declaring the user inactive.
+
+#### `language`
+
+> Type: `String`
+
+A [two-letter code][lang-codes] matching one of the available languages in the player. This sets the initial language for a player, but it can always be changed.
+
+Learn more about [languages in Video.js](languages.md).
+
+#### `languages`
+
+> Type: `Object`
+
+Customize which languages are available in a player. The keys of this object will be [two-letter language codes][lang-codes] and the values will be objects with English keys and translated values.
+
+Learn more about [languages in Video.js](languages.md).
+
+> **Note**: Generally, this option is not needed and it would be better to pass your custom languages to `videojs.addLanguage()`, so they are available in all players!
+
+#### `notSupportedMessage`
+
+> Type: `String`
+
+Allows overriding the default message that is displayed when Video.js cannot play back a media source.
+
+#### `plugins`
+
+> Type: `Object`
+
+This supports having plugins be initialized automatically with custom options when the player is initialized - rather than requiring you to initialize them manually.
+
+```js
+videojs('my-player', {
+  plugins: {
+    foo: {bar: true},
+    boo: {baz: false}
+  }
+});
 ```
 
+The above is roughly equivalent to:
 
-### width ###
-The width attribute sets the display width of the video.
-```html
-<video width="640" ...>
-or
-{ "width": 640 }
+```js
+var player = videojs('my-player');
+
+player.foo({bar: true});
+player.boo({baz: false});
 ```
 
+Although, since the `plugins` option is an object, the order of initialization is not guaranteed!
 
-### height ###
-The height attribute sets the display height of the video.
-```html
-<video height="480" ...>
-or
-{ "height": 480 }
+#### `sourceOrder`
+
+> Type: `Boolean`
+
+Tells Video.js to prefer the order of [`sources`](#sources) over [`techOrder`](#techOrder) in selecting a source and playback tech.
+
+#### `sources`
+
+> Type: `Array`
+
+An array of objects that mirror the native `<video>` element's capability to have a series of child `<source>` elements. This should be an array of objects with the `src` and `type` properties. For example:
+
+```js
+videojs('my-player', {
+  sources: [{
+    src: '//path/to/video.mp4',
+    type: 'video/mp4'
+  }, {
+    src: '//path/to/video.webm',
+    type: 'video/webm'
+  }]
+});
 ```
 
-Component Options
------------------
+#### `techOrder`
+
+> Type: `Array`, Default: `['html5', 'flash']`
+
+Defines the order in which Video.js techs are preferred. By default, this means that the `Html5` tech is preferred, but Video.js will fall back to `Flash` if no `Html5`-compatible source can be found.
+
+### Component Options
+
+The Video.js player is a component. Like all components, you can define what children it includes, what order they appear in, and what options are passed to them.
+
+This is meant to be a quick reference; so, for more detailed information on components in Video.js, check out the [components guide](components.md).
+
+#### `children`
+
+> Type: `Array|Object`
+
+If an `Array` - which is the default - this is used to determine the order in which children are created on a player.
+
+This can also be passed as an `Object`. In this case, it is used to provide `options` for any/all children.
 
-You can set the options for any single player component. For instance, if you wanted to remove the `muteToggle` button, which
-is a child of `controlBar`, you can just set that component to false:
+#### `${componentName}`
+
+> Type: `Object`
+
+Components can be given custom options via the _lower-camel-case variant of the component name_ (e.g. `controlBar` for `ControlBar`). These can be nested in a representation of grandchild relationships. For example, to disable the fullscreen control:
 
 ```js
-var player = videojs('video-id', {
+videojs('my-player', {
   controlBar: {
-    muteToggle: false
+    fullscreenControl: false
   }
 });
 ```
 
-This also works using the `data-setup` attribute on the video element, just remember the options need to use proper JSON
-notation.
+### Tech Options
 
-```html
-<video ... data-setup='{ "controlBar": { "muteToggle": false } }'></video>
+#### `${techName}`
+
+> Type: `Object`
+
+Video.js playback technologies (i.e. "techs") can be given custom options as part of the options passed to the `videojs` function. They should be passed under the _lower-case variant of the tech name_ (e.g. `"flash"` or `"html5"`).
+
+This is not used in most implementations, but one case where it may be is dictating where the Video.js SWF file is located for the `Flash` tech:
+
+```js
+videojs('my-player', {
+  flash: {
+    swf: '//path/to/videojs.swf'
+  }
+});
+```
+
+However, this is a case where changing the global defaults is more useful:
+
+```js
+videojs.options.flash.swf = '//path/to/videojs.swf'
 ```
 
-The [components guide](./components.md) has an excellent breakdown of the structure of a player, you
-just need to remember to nest child components in a `children` array for each level.
+[boolean-attrs]: https://www.w3.org/TR/2011/WD-html5-20110525/common-microsyntaxes.html#boolean-attributes
+[json]: http://json.org/example.html
+[lang-codes]: http://www.iana.org/assignments/language-subtag-registry/language-subtag-registry
+[video-attrs]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video#Attributes
diff --git a/docs/guides/setup.md b/docs/guides/setup.md
index ad215e941d..5753f84967 100644
--- a/docs/guides/setup.md
+++ b/docs/guides/setup.md
@@ -34,7 +34,7 @@ By default, when your web page finishes loading, Video.js will scan for media el
 </video>
 ```
 
-> Note: You **must** use single-quotes with `data-setup` as it is expected to contain JSON and it **must** contain `'{}'` at a minimum!
+> Note: You **must** use single-quotes with `data-setup` as it is expected to contain JSON.
 
 ### Manual Setup
 
@@ -66,7 +66,7 @@ Using an `id` attribute isn't always practical when your DOM is generated progra
 videojs(document.querySelector('.video-js'));
 ```
 
-Regardless, in either case, the `data-setup` attribute is still supported for providing [options][options] to Video.js. Additionally, the `videojs` function can take options as its second argument.
+Regardless, in either case, the `data-setup` attribute is still supported for providing [options][options] to Video.js. Additionally, the `videojs` function can take options as its second argument. [Learn more about Video.js options][options].
 
 
 [getting-started]: http://videojs.com/getting-started/

From f9c01a469abdf9c851ee232d6072a66cf7d25ced Mon Sep 17 00:00:00 2001
From: Pat O'Neill <pgoneill@gmail.com>
Date: Sun, 23 Oct 2016 13:57:54 -0400
Subject: [PATCH 05/20] ToCs

---
 docs/guides/options.md | 40 ++++++++++++++++++++++++++++++++++++++--
 docs/guides/setup.md   | 11 +++++++++++
 2 files changed, 49 insertions(+), 2 deletions(-)

diff --git a/docs/guides/options.md b/docs/guides/options.md
index 55efb30c1a..3a082e2756 100644
--- a/docs/guides/options.md
+++ b/docs/guides/options.md
@@ -1,7 +1,43 @@
 # Options
 
-<!-- START doctoc -->
-<!-- END doctoc -->
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+
+- [Setting Options](#setting-options)
+  - [Setting Global Defaults](#setting-global-defaults)
+  - [A Note on `<video>` Tag Attributes](#a-note-on-video-tag-attributes)
+  - [Precedence](#precedence)
+- [Options Reference](#options-reference)
+  - [Standard `<video>` Element Options](#standard-video-element-options)
+    - [`autoplay`](#autoplay)
+    - [`controls`](#controls)
+    - [`height`](#height)
+    - [`loop`](#loop)
+    - [`muted`](#muted)
+    - [`poster`](#poster)
+    - [`preload`](#preload)
+    - [`src`](#src)
+    - [`width`](#width)
+  - [Video.js-specific Options](#videojs-specific-options)
+    - [`aspectRatio`](#aspectratio)
+    - [`children`](#children)
+    - [`fluid`](#fluid)
+    - [`inactivityTimeout`](#inactivitytimeout)
+    - [`language`](#language)
+    - [`languages`](#languages)
+    - [`notSupportedMessage`](#notsupportedmessage)
+    - [`plugins`](#plugins)
+    - [`sourceOrder`](#sourceorder)
+    - [`sources`](#sources)
+    - [`techOrder`](#techorder)
+  - [Component Options](#component-options)
+    - [`children`](#children-1)
+    - [`${componentName}`](#componentname)
+  - [Tech Options](#tech-options)
+    - [`${techName}`](#techname)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
 ## Setting Options
 
diff --git a/docs/guides/setup.md b/docs/guides/setup.md
index 5753f84967..8aca1daff8 100644
--- a/docs/guides/setup.md
+++ b/docs/guides/setup.md
@@ -1,5 +1,16 @@
 # Video.js Setup
 
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+
+- [Installing Video.js](#installing-videojs)
+- [Decorating a `<video>` Element](#decorating-a-video-element)
+  - [Automatic Setup](#automatic-setup)
+  - [Manual Setup](#manual-setup)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 ## Installing Video.js
 
 Video.js is officially available via CDN, npm, and Bower.

From adf3197b8dd7c87e3f8c55a4446febc9fd959d66 Mon Sep 17 00:00:00 2001
From: Pat O'Neill <pgoneill@gmail.com>
Date: Mon, 31 Oct 2016 11:45:27 -0400
Subject: [PATCH 06/20] Changes due to feedback

---
 README.md              |  2 +-
 docs/guides/options.md | 50 +++++++++++++++++++++++++++++++++++++-----
 docs/guides/setup.md   |  2 ++
 docs/index.md          |  2 +-
 4 files changed, 49 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index e7a8626b3c..0ae82a09ef 100644
--- a/README.md
+++ b/README.md
@@ -70,7 +70,7 @@ Video.js is a free and open source library, and we appreciate any help you're wi
 
 _Video.js uses [BrowserStack][browserstack] for compatibility testing._
 
-## License
+## [License][license]
 
 Video.js is [licensed][license] under the Apache License, Version 2.0.
 
diff --git a/docs/guides/options.md b/docs/guides/options.md
index 3a082e2756..745ac77370 100644
--- a/docs/guides/options.md
+++ b/docs/guides/options.md
@@ -79,6 +79,7 @@ _These are incorrect:_
 
 ```html
 <video controls="true" ...>
+<video loop="true" ...>
 <video controls="false" ...>
 ```
 
@@ -88,6 +89,7 @@ These are correct:
 
 ```html
 <video controls ...>
+<video loop="loop" ...>
 <video ...>
 ```
 
@@ -114,7 +116,7 @@ The `src` option would have the value `'foo-3.mp4'`.
 
 ### Standard `<video>` Element Options
 
-Each of these options is also available as a standard `<video>` element attribute; so, they can be defined in all three manners [outlined above](#setting-options). Typically, defaults are not listed as this is left to browser vendors.
+Each of these options is also available as a [standard `<video>` element attribute][video-attrs]; so, they can be defined in all three manners [outlined above](#setting-options). Typically, defaults are not listed as this is left to browser vendors.
 
 #### `autoplay`
 
@@ -122,7 +124,7 @@ Each of these options is also available as a standard `<video>` element attribut
 
 If `true`/present as an attribute, begins playback automatically.
 
-> **Note:** As of iOS 10, Apple offers `autoplay` support in Safari. However, in order for it to work, the `<video>` element must have `muted` and `playsinline` attributes!
+> **Note:** As of iOS 10, Apple offers `autoplay` support in Safari. For details, refer to ["New <video> Policies for iOS"][ios-10-updates].
 
 #### `controls`
 
@@ -206,19 +208,21 @@ Puts the player in [fluid](#fluid) mode and the value is used when calculating t
 
 When `true`, the Video.js player will have a fluid size. In other words, it will scale to fit its container.
 
+Also, if the `<video>` element has the `"vjs-fluid"`, this option is automatically set to `true`.
+
 #### `inactivityTimeout`
 
 > Type: `Number`
 
 Video.js indicates that the user is interacting with the player by way of the `"vjs-user-active"` and `"vjs-user-inactive"` classes and the `"useractive"` event.
 
-The `inactivityTimeout` determines how many milliseconds of inactivity is required before declaring the user inactive.
+The `inactivityTimeout` determines how many milliseconds of inactivity is required before declaring the user inactive. A value of `0` indicates that there is no `inactivityTimeout` and the user will never be considered inactive.
 
 #### `language`
 
 > Type: `String`
 
-A [two-letter code][lang-codes] matching one of the available languages in the player. This sets the initial language for a player, but it can always be changed.
+A [language code][lang-codes] matching one of the available languages in the player. This sets the initial language for a player, but it can always be changed.
 
 Learn more about [languages in Video.js](languages.md).
 
@@ -226,7 +230,7 @@ Learn more about [languages in Video.js](languages.md).
 
 > Type: `Object`
 
-Customize which languages are available in a player. The keys of this object will be [two-letter language codes][lang-codes] and the values will be objects with English keys and translated values.
+Customize which languages are available in a player. The keys of this object will be [language codes][lang-codes] and the values will be objects with English keys and translated values.
 
 Learn more about [languages in Video.js](languages.md).
 
@@ -270,6 +274,41 @@ Although, since the `plugins` option is an object, the order of initialization i
 
 Tells Video.js to prefer the order of [`sources`](#sources) over [`techOrder`](#techOrder) in selecting a source and playback tech.
 
+Given the following example:
+
+```js
+videojs('my-player', {
+  sourceOrder: true,
+  sources: [{
+    src: '//path/to/video.flv',
+    type: 'video/x-flv'
+  }, {
+    src: '//path/to/video.mp4',
+    type: 'video/mp4'
+  }, {
+    src: '//path/to/video.webm',
+    type: 'video/webm'
+  }],
+  techOrder: ['html5', 'flash']
+});
+```
+
+Normally, the fact that HTML5 comes before Flash in the `techOrder` would mean Video.js would look for a compatible _source_ for HTML5 and would pick either the MP4 or WebM video (depending on browser support) only falling back to Flash if no compatible source for HTML5 was found.
+
+However, because the `sourceOrder` is `true`, Video.js flips that process around. It will look for a compatible _tech_ for each source in order. Presumably, it would first find a match between the FLV (since it's first in the source order) and the Flash tech.
+
+In summary, the default algorithm is:
+
+- for each tech:
+  - for each source:
+    - if tech can play source, use this tech/source combo
+
+With `sourceOrder: true`, the algorithm becomes:
+
+- for each source:
+  - for each tech:
+    - if tech can play source, use this tech/source combo
+
 #### `sources`
 
 > Type: `Array`
@@ -347,6 +386,7 @@ videojs.options.flash.swf = '//path/to/videojs.swf'
 ```
 
 [boolean-attrs]: https://www.w3.org/TR/2011/WD-html5-20110525/common-microsyntaxes.html#boolean-attributes
+[ios-10-updates]: https://webkit.org/blog/6784/new-video-policies-for-ios/
 [json]: http://json.org/example.html
 [lang-codes]: http://www.iana.org/assignments/language-subtag-registry/language-subtag-registry
 [video-attrs]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video#Attributes
diff --git a/docs/guides/setup.md b/docs/guides/setup.md
index 8aca1daff8..341385a41d 100644
--- a/docs/guides/setup.md
+++ b/docs/guides/setup.md
@@ -15,6 +15,8 @@
 
 Video.js is officially available via CDN, npm, and Bower.
 
+Video.js works out of the box with not only HTML `<script>` and `<link>` tags, but also all major bundlers/packagers/builders, such as Browserify, Node, WebPack, etc.
+
 Please refer to the [Getting Started][getting-started] document for details.
 
 ## Decorating a `<video>` Element
diff --git a/docs/index.md b/docs/index.md
index 5427bf0030..97b4c7878e 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,6 +1,6 @@
 # [Video.js][vjs] Documentation
 
-There are two categories of docs: [Guides][guides] and [API docs][api].
+There are two categories of docs: [Guides][guides] and [API docs][guides-api].
 
 Guides explain general topics and use cases (e.g. setup). API docs are automatically generated from the codebase and give specific details about functions, properties, and events.
 

From f8d9afc022072452bd66b40ad45a4797b1995726 Mon Sep 17 00:00:00 2001
From: Pat O'Neill <pgoneill@gmail.com>
Date: Mon, 31 Oct 2016 16:22:37 -0400
Subject: [PATCH 07/20] Reshuffle options/setup; remove api/glossary

---
 docs/guides/api.md      |  44 ---------
 docs/guides/glossary.md |  39 --------
 docs/guides/options.md  | 194 ++++++++++++----------------------------
 docs/guides/setup.md    | 123 ++++++++++++++++++++++---
 docs/index.md           |  18 +---
 5 files changed, 171 insertions(+), 247 deletions(-)
 delete mode 100644 docs/guides/api.md
 delete mode 100644 docs/guides/glossary.md

diff --git a/docs/guides/api.md b/docs/guides/api.md
deleted file mode 100644
index a1b5fd437a..0000000000
--- a/docs/guides/api.md
+++ /dev/null
@@ -1,44 +0,0 @@
-API
-===
-
-The Video.js API allows you to interact with the video through JavaScript, whether the browser is playing the video through HTML5 video, Flash, or any other supported playback technologies.
-
-Referencing the Player
-----------------------
-To use the API functions, you need access to the player object. Luckily this is easy to get. You just need to make sure your video tag has an ID. The example embed code has an ID of "example\_video_1". If you have multiple videos on one page, make sure every video tag has a unique ID.
-
-```js
-var myPlayer = videojs('example_video_1');
-```
-
-(If the player hasn't been initialized yet via the data-setup attribute or another method, this will also initialize the player.)
-
-Wait Until the Player is Ready
-------------------------------
-The time it takes Video.js to set up the video and API will vary depending on the playback technology being used (HTML5 will often be much faster to load than Flash). For that reason we want to use the player's 'ready' function to trigger any code that requires the player's API.
-
-```js
-videojs("example_video_1").ready(function(){
-  var myPlayer = this;
-
-  // EXAMPLE: Start playing the video.
-  myPlayer.play();
-
-});
-```
-
-API Methods
------------
-Now that you have access to a ready player, you can control the video, get values, or respond to video events. The Video.js API function names follow the [HTML5 media API](http://www.whatwg.org/specs/web-apps/current-work/multipage/the-video-element.html). The main difference is that getter/setter functions are used for video properties.
-
-```js
-
-// setting a property on a bare HTML5 video element
-myVideoElement.currentTime = "120";
-
-// setting a property on a Video.js player
-myPlayer.currentTime(120);
-
-```
-
-The full list of player API methods and events can be found in the [player API docs](http://docs.videojs.com/docs/api/index.html).
diff --git a/docs/guides/glossary.md b/docs/guides/glossary.md
deleted file mode 100644
index 86ec1e9def..0000000000
--- a/docs/guides/glossary.md
+++ /dev/null
@@ -1,39 +0,0 @@
-Glossary
-========
-Terms related to web video.
-
-### DOM (Document Object Model)
-The container of elements on the page that must be loaded before you can interact with the elements with through Javascript.
-http://en.wikipedia.org/wiki/Document_Object_Model
-
-
-### Flash Fallback
-The Flash video player (SWF) used to play a video when HTML5 isn't supported.
-
-
-### TimeRange
-
-
-### HTML5 Video
-HTML is the markup language that makes up every page on the web. The newest version, HTML5, includes specifications for a video tag, that is meant to allow website developers to add a video to a page the same way they would add an image. In order for this to work, web browser developers (Mozilla, Apple, Microsoft, Google, Opera, etc.) have to build the video playback functionality into their browsers. The W3C has created directions on how video should work in browsers, and it’s up to browser developers to follow those directions, so that video works the same across all browsers. This doesn’t always happen thanks to technology, legal, and financial choices made by browser developers, but so far no one’s varying too far from the specifications. However the specifications are still being changed and refined, so browsers developers have to keep up with that as well.
-
-Playing video in a web page may not seem so special since you can already view video on a web page through plugins like Flash Player, Quicktime, Silverlight, and RealPlayer, however this is a big step forward for standardizing video playback across web browsers and devices. The goal is that in the future, developers will only need to use one method for embedding a video, that’s based on open standards (not controlled by one company), and it will work everywhere.
-
-A prime example of this is the iPhone and iPad. Apple has decided not to support Flash on their mobile devices, but they do support HTML5 video. Since Flash is currently the most common way video is added to web pages, most web video (aside from YouTube who has a special relationship with Apple) can’t be viewed on the iPhone or iPad. These devices are very popular, so many web sites are switching to hybrid HTML5/Flash player setups (like VideoJS).
-
-
-### Video Tag
-There are a number of great resources that will give you an introduction to the video tag an how it is used including:
-
-  - [Dive into HTML5](http://diveintohtml5.org/video.html)
-  - Lynda.com's ['HTML5 Video and Audio in Depth'](http://www.lynda.com/HTML-5-tutorials/HTML5-Video-and-Audio-in-Depth/80781-2.html) video tutorials created by yours truly.
-
-An if you really want to dig in, you can read the (W3C Spec)[http://www.w3.org/TR/html5/video.html]. (Warning - not for the faint of heart)
-
-
-### Skin
-"Skin" refers to the design of the player's controls, also sometimes called the chrome. With VideoJS, new skins can be built simply by creating a new stylesheet.
-
-
-### Content Delivery Network (CDN)
-A network of servers around the world that host copies of a file. When your browser requests one of these files, the CDN automatically determines which server is closest to your location and delivers the file from there. This drastically increases delivery time, especially internationally.
diff --git a/docs/guides/options.md b/docs/guides/options.md
index 745ac77370..9b0a574c1d 100644
--- a/docs/guides/options.md
+++ b/docs/guides/options.md
@@ -1,124 +1,46 @@
-# Options
+# Video.js Options Reference
+
+> **Note:** This document is only a reference for available options. To learn about passing options to Video.js, see [the setup guide](setup.md#options).
 
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
 
-- [Setting Options](#setting-options)
-  - [Setting Global Defaults](#setting-global-defaults)
-  - [A Note on `<video>` Tag Attributes](#a-note-on-video-tag-attributes)
-  - [Precedence](#precedence)
-- [Options Reference](#options-reference)
-  - [Standard `<video>` Element Options](#standard-video-element-options)
-    - [`autoplay`](#autoplay)
-    - [`controls`](#controls)
-    - [`height`](#height)
-    - [`loop`](#loop)
-    - [`muted`](#muted)
-    - [`poster`](#poster)
-    - [`preload`](#preload)
-    - [`src`](#src)
-    - [`width`](#width)
-  - [Video.js-specific Options](#videojs-specific-options)
-    - [`aspectRatio`](#aspectratio)
-    - [`children`](#children)
-    - [`fluid`](#fluid)
-    - [`inactivityTimeout`](#inactivitytimeout)
-    - [`language`](#language)
-    - [`languages`](#languages)
-    - [`notSupportedMessage`](#notsupportedmessage)
-    - [`plugins`](#plugins)
-    - [`sourceOrder`](#sourceorder)
-    - [`sources`](#sources)
-    - [`techOrder`](#techorder)
-  - [Component Options](#component-options)
-    - [`children`](#children-1)
-    - [`${componentName}`](#componentname)
-  - [Tech Options](#tech-options)
-    - [`${techName}`](#techname)
+- [Standard `<video>` Element Options](#standard-video-element-options)
+  - [`autoplay`](#autoplay)
+  - [`controls`](#controls)
+  - [`height`](#height)
+  - [`loop`](#loop)
+  - [`muted`](#muted)
+  - [`poster`](#poster)
+  - [`preload`](#preload)
+  - [`src`](#src)
+  - [`width`](#width)
+- [Video.js-specific Options](#videojs-specific-options)
+  - [`aspectRatio`](#aspectratio)
+  - [`children`](#children)
+  - [`fluid`](#fluid)
+  - [`inactivityTimeout`](#inactivitytimeout)
+  - [`language`](#language)
+  - [`languages`](#languages)
+  - [`notSupportedMessage`](#notsupportedmessage)
+  - [`plugins`](#plugins)
+  - [`sourceOrder`](#sourceorder)
+  - [`sources`](#sources)
+  - [`techOrder`](#techorder)
+- [Component Options](#component-options)
+  - [`children`](#children-1)
+  - [`${componentName}`](#componentname)
+- [Tech Options](#tech-options)
+  - [`${techName}`](#techname)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
-## Setting Options
-
-Because Video.js decorates an HTML5 `<video>` element, many of the options available to you are also available as [standard `<video>` tag attributes][video-attrs]:
-
-```html
-<video controls autoplay preload="auto" ...>
-```
-
-Alternatively, you can use the `data-setup` attribute to provide options as [JSON][json]. This is also how you would set options that aren't standard to the `<video>` element:
-
-```html
-<video data-setup='{"controls": true, "autoplay": false, "preload": "auto"}'...>
-```
-
-Finally, if you're not using the `data-setup` attribute to trigger the player setup, you can pass in an object of player options as the second argument to the `videojs` function:
-
-```js
-videojs('my-player', {
-  controls: true,
-  autoplay: false,
-  preload: 'auto'
-});
-```
-
-### Setting Global Defaults
-
-Default options for all players can be found at `videojs.options`. In order to override them, mutate this object as needed. For example, to set `{autoplay: true}` for all players:
-
-```js
-videojs.options.autoplay = true;
-```
-
-### A Note on `<video>` Tag Attributes
-
-Many attributes are so-called [boolean attributes][boolean-attrs]. This means they are either on or off. In these cases, the attribute _should have no value_ - its presence implies a true value and its absence implies a false value.
-
-_These are incorrect:_
-
-```html
-<video controls="true" ...>
-<video loop="true" ...>
-<video controls="false" ...>
-```
-
-> **Note:** The example with `controls="false"` can be a point of confusion for new developers - it will actually turn controls _on_!
-
-These are correct:
-
-```html
-<video controls ...>
-<video loop="loop" ...>
-<video ...>
-```
-
-### Precedence
-
-There are multiple ways to provide options for Video.js, so we should be clear about which methods take precedence. From highest to lowest, the precedence rules are:
-
-1. Options as the second argument to the `videojs` function
-1. Options parsed from the `data-setup` attribute
-1. `<video>` element attributes and children
-
-For example, given:
-
-```html
-<video id="foo" src="foo-1.mp4" data-setup='{"src":"foo-2.mp4"}'></video>
-<script>
-  videojs('foo', {src: 'foo-3.mp4'});
-</script>
-```
-
-The `src` option would have the value `'foo-3.mp4'`.
-
-## Options Reference
-
-### Standard `<video>` Element Options
+## Standard `<video>` Element Options
 
 Each of these options is also available as a [standard `<video>` element attribute][video-attrs]; so, they can be defined in all three manners [outlined above](#setting-options). Typically, defaults are not listed as this is left to browser vendors.
 
-#### `autoplay`
+### `autoplay`
 
 > Type: `Boolean`
 
@@ -126,37 +48,37 @@ If `true`/present as an attribute, begins playback automatically.
 
 > **Note:** As of iOS 10, Apple offers `autoplay` support in Safari. For details, refer to ["New <video> Policies for iOS"][ios-10-updates].
 
-#### `controls`
+### `controls`
 
 > Type: `Boolean`
 
 Determines whether or not the player has controls that the user can interact with. Without controls the only way to start the video playing is with the `autoplay` attribute or through the Player API.
 
-#### `height`
+### `height`
 
 > Type: `String|Number`
 
 Sets the display height of the video player in pixels.
 
-#### `loop`
+### `loop`
 
 > Type: `Boolean`
 
 Causes the video to start over as soon as it ends.
 
-#### `muted`
+### `muted`
 
 > Type: `Boolean`
 
 Will silence any audio by default.
 
-#### `poster`
+### `poster`
 
 > Type: `String`
 
 A URL to an image that displays before the video begins playing. This is often a frame of the video or a custom title screen. As soon as the user hits "play" the image will go away.
 
-#### `preload`
+### `preload`
 
 > Type: `String`
 
@@ -176,33 +98,33 @@ Suggests to the browser whether or not the video data should begin downloading a
 
   Don't preload any data. The browser will wait until the user hits "play" to begin downloading.
 
-#### `src`
+### `src`
 
 > Type: `String`
 
 The source URL to a video source to embed.
 
-#### `width`
+### `width`
 
 > Type: `String|Number`
 
 Sets the display height of the video player in pixels.
 
-### Video.js-specific Options
+## Video.js-specific Options
 
 Each option is `undefined` by default unless otherwise specified.
 
-#### `aspectRatio`
+### `aspectRatio`
 
 > Type: `String`
 
 Puts the player in [fluid](#fluid) mode and the value is used when calculating the dynamic size of the player. The value should represent a ratio - two numbers separated by a colon (e.g. `"16:9"` or `"4:3"`).
 
-#### `children`
+### `children`
 
 > Type: `Array`
 
-#### `fluid`
+### `fluid`
 
 > Type: `Boolean`
 
@@ -210,7 +132,7 @@ When `true`, the Video.js player will have a fluid size. In other words, it will
 
 Also, if the `<video>` element has the `"vjs-fluid"`, this option is automatically set to `true`.
 
-#### `inactivityTimeout`
+### `inactivityTimeout`
 
 > Type: `Number`
 
@@ -218,7 +140,7 @@ Video.js indicates that the user is interacting with the player by way of the `"
 
 The `inactivityTimeout` determines how many milliseconds of inactivity is required before declaring the user inactive. A value of `0` indicates that there is no `inactivityTimeout` and the user will never be considered inactive.
 
-#### `language`
+### `language`
 
 > Type: `String`
 
@@ -226,7 +148,7 @@ A [language code][lang-codes] matching one of the available languages in the pla
 
 Learn more about [languages in Video.js](languages.md).
 
-#### `languages`
+### `languages`
 
 > Type: `Object`
 
@@ -236,13 +158,13 @@ Learn more about [languages in Video.js](languages.md).
 
 > **Note**: Generally, this option is not needed and it would be better to pass your custom languages to `videojs.addLanguage()`, so they are available in all players!
 
-#### `notSupportedMessage`
+### `notSupportedMessage`
 
 > Type: `String`
 
 Allows overriding the default message that is displayed when Video.js cannot play back a media source.
 
-#### `plugins`
+### `plugins`
 
 > Type: `Object`
 
@@ -268,7 +190,7 @@ player.boo({baz: false});
 
 Although, since the `plugins` option is an object, the order of initialization is not guaranteed!
 
-#### `sourceOrder`
+### `sourceOrder`
 
 > Type: `Boolean`
 
@@ -309,7 +231,7 @@ With `sourceOrder: true`, the algorithm becomes:
   - for each tech:
     - if tech can play source, use this tech/source combo
 
-#### `sources`
+### `sources`
 
 > Type: `Array`
 
@@ -327,19 +249,19 @@ videojs('my-player', {
 });
 ```
 
-#### `techOrder`
+### `techOrder`
 
 > Type: `Array`, Default: `['html5', 'flash']`
 
 Defines the order in which Video.js techs are preferred. By default, this means that the `Html5` tech is preferred, but Video.js will fall back to `Flash` if no `Html5`-compatible source can be found.
 
-### Component Options
+## Component Options
 
 The Video.js player is a component. Like all components, you can define what children it includes, what order they appear in, and what options are passed to them.
 
 This is meant to be a quick reference; so, for more detailed information on components in Video.js, check out the [components guide](components.md).
 
-#### `children`
+### `children`
 
 > Type: `Array|Object`
 
@@ -347,7 +269,7 @@ If an `Array` - which is the default - this is used to determine the order in wh
 
 This can also be passed as an `Object`. In this case, it is used to provide `options` for any/all children.
 
-#### `${componentName}`
+### `${componentName}`
 
 > Type: `Object`
 
@@ -361,9 +283,9 @@ videojs('my-player', {
 });
 ```
 
-### Tech Options
+## Tech Options
 
-#### `${techName}`
+### `${techName}`
 
 > Type: `Object`
 
@@ -385,8 +307,6 @@ However, this is a case where changing the global defaults is more useful:
 videojs.options.flash.swf = '//path/to/videojs.swf'
 ```
 
-[boolean-attrs]: https://www.w3.org/TR/2011/WD-html5-20110525/common-microsyntaxes.html#boolean-attributes
 [ios-10-updates]: https://webkit.org/blog/6784/new-video-policies-for-ios/
-[json]: http://json.org/example.html
 [lang-codes]: http://www.iana.org/assignments/language-subtag-registry/language-subtag-registry
 [video-attrs]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video#Attributes
diff --git a/docs/guides/setup.md b/docs/guides/setup.md
index 341385a41d..dd6aa76490 100644
--- a/docs/guides/setup.md
+++ b/docs/guides/setup.md
@@ -4,14 +4,18 @@
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
 
-- [Installing Video.js](#installing-videojs)
-- [Decorating a `<video>` Element](#decorating-a-video-element)
+- [Getting Video.js](#getting-videojs)
+- [Creating a Player](#creating-a-player)
   - [Automatic Setup](#automatic-setup)
   - [Manual Setup](#manual-setup)
+- [Options](#options)
+  - [Global Defaults](#global-defaults)
+  - [A Note on `<video>` Tag Attributes](#a-note-on-video-tag-attributes)
+- [Player Readiness](#player-readiness)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
-## Installing Video.js
+## Getting Video.js
 
 Video.js is officially available via CDN, npm, and Bower.
 
@@ -19,15 +23,15 @@ Video.js works out of the box with not only HTML `<script>` and `<link>` tags, b
 
 Please refer to the [Getting Started][getting-started] document for details.
 
-## Decorating a `<video>` Element
+## Creating a Player
 
-Once you have Video.js [loaded on your page][getting-started], you're ready to create a player!
+> **Note:** Video.js works with `<video>` _and_ `<audio>` elements, but for simplicity we'll refer only to `<video>` elements going forward.
 
-> Note: Video.js works with `<video>` _and_ `<audio>` elements, but for simplicity we'll refer only to `<video>` elements going forward!
+Once you have Video.js [loaded on your page][getting-started], you're ready to create a player!
 
 The core strength of Video.js is that it decorates a [standard `<video>` element][w3c-video] and emulates its associated [events and APIs][w3c-media-events], while providing a customizable DOM-based UI.
 
-Video.js supports all attributes of the `<video>` element (such as `controls`, `preload`, etc), but it also supports [its own options][options]. There are two ways to create a Video.js player and pass it options, but they both start with a standard `<video>` element with the attribute `class="video-js"`:
+Video.js supports all attributes of the `<video>` element (such as `controls`, `preload`, etc), but it also supports [its own options](#options). There are two ways to create a Video.js player and pass it options, but they both start with a standard `<video>` element with the attribute `class="video-js"`:
 
 ```html
 <video class="video-js">
@@ -38,7 +42,7 @@ Video.js supports all attributes of the `<video>` element (such as `controls`, `
 
 ### Automatic Setup
 
-By default, when your web page finishes loading, Video.js will scan for media elements that have the `data-setup` attribute. The `data-setup` attribute is used to provide [options][options] to Video.js. The minimum example looks like this:
+By default, when your web page finishes loading, Video.js will scan for media elements that have the `data-setup` attribute. The `data-setup` attribute is used to pass options to Video.js. A minimal example looks like this:
 
 ```html
 <video class="video-js" data-setup='{}'>
@@ -47,11 +51,11 @@ By default, when your web page finishes loading, Video.js will scan for media el
 </video>
 ```
 
-> Note: You **must** use single-quotes with `data-setup` as it is expected to contain JSON.
+> **Note:** You _must_ use single-quotes with `data-setup` as it is expected to contain JSON.
 
 ### Manual Setup
 
-From updating the DOM via standard APIs to full-fledged frameworks like React and Ember, a `<video>` element often does not exist when the page finishes loading. In these cases, automatic setup is not possible, but manual setup is available via [the `videojs` function][videojs].
+On the modern web, a `<video>` element often does not exist when the page finishes loading. In these cases, automatic setup is not possible, but manual setup is available via [the `videojs` function][videojs].
 
 One way to call this function is by providing it a string matching a `<video>` element's `id` attribute:
 
@@ -66,7 +70,7 @@ One way to call this function is by providing it a string matching a `<video>` e
 videojs('my-player');
 ```
 
-Using an `id` attribute isn't always practical when your DOM is generated programmatically. In that case, Video.js accepts a DOM element instead:
+However, using an `id` attribute isn't always practical; so, the `videojs` function accepts a DOM element instead:
 
 ```html
 <video class="video-js">
@@ -79,11 +83,104 @@ Using an `id` attribute isn't always practical when your DOM is generated progra
 videojs(document.querySelector('.video-js'));
 ```
 
-Regardless, in either case, the `data-setup` attribute is still supported for providing [options][options] to Video.js. Additionally, the `videojs` function can take options as its second argument. [Learn more about Video.js options][options].
+## Options
+
+> **Note:** This guide only covers how to pass options during player setup. For a complete reference on _all_ available options, see the [options guide](options.md).
+
+There are three ways to pass options to Video.js. Because Video.js decorates an HTML5 `<video>` element, many of the options available are also available as [standard `<video>` tag attributes][video-attrs]:
+
+```html
+<video controls autoplay preload="auto" ...>
+```
+
+Alternatively, you can use the `data-setup` attribute to pass options as [JSON][json]. This is also how you would set options that aren't standard to the `<video>` element:
+
+```html
+<video data-setup='{"controls": true, "autoplay": false, "preload": "auto"}'...>
+```
+
+Finally, if you're not using the `data-setup` attribute to trigger the player setup, you can pass in an object of player options as the second argument to the `videojs` function:
+
+```js
+videojs('my-player', {
+  controls: true,
+  autoplay: false,
+  preload: 'auto'
+});
+```
+
+### Global Defaults
+
+Default options for all players can be found at `videojs.options` and can be changed directly. For example, to set `{autoplay: true}` for all future players:
+
+```js
+videojs.options.autoplay = true;
+```
+
+### A Note on `<video>` Tag Attributes
+
+Many attributes are so-called [boolean attributes][boolean-attrs]. This means they are either on or off. In these cases, the attribute _should have no value_ - its presence implies a true value and its absence implies a false value.
+
+_These are incorrect:_
+
+```html
+<video controls="true" ...>
+<video loop="true" ...>
+<video controls="false" ...>
+```
+
+> **Note:** The example with `controls="false"` can be a point of confusion for new developers - it will actually turn controls _on_!
+
+These are correct:
+
+```html
+<video controls ...>
+<video loop="loop" ...>
+<video ...>
+```
+
+## Player Readiness
+
+Because Video.js techs have the potential to be loaded asynchronously, it isn't always safe to interact with a player immediately upon setup. For this reason, Video.js players have a concept of "readiness" which will be familiar to anyone who has used jQuery before.
+
+Essentially, any number of ready callbacks can be defined for a Video.js player. There are three ways to pass these callbacks. In each example, we'll add an identical class to the player:
+
+Pass a callback to the `videojs()` function as a third argument:
+
+```js
+// Passing `null` for the options argument.
+videojs('my-player', null, function() {
+  this.addClass('my-example');
+});
+```
+
+Pass a callback to a player's `ready()` method:
+
+```js
+var player = videojs('my-player');
+
+player.ready(function() {
+  this.addClass('my-example');
+});
+```
+
+Listen for the player's `"ready"` event:
+
+```js
+var player = videojs('my-player');
+
+player.on('ready', function() {
+  this.addClass('my-example');
+});
+```
+
+In each case, the callback is called asynchronously - _even if the player is already ready!_
 
 
+[boolean-attrs]: https://www.w3.org/TR/2011/WD-html5-20110525/common-microsyntaxes.html#boolean-attributes
 [getting-started]: http://videojs.com/getting-started/
-[options]: options.md
+[json]: http://json.org/example.html
+[video-attrs]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video#Attributes
 [videojs]: http://docs.videojs.com/docs/api/video.html
 [w3c-media-events]: https://www.w3.org/2010/05/video/mediaevents.html
 [w3c-video]: http://www.w3.org/TR/html5/embedded-content-0.html#the-video-element
diff --git a/docs/index.md b/docs/index.md
index 97b4c7878e..d8596976cd 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,6 +1,6 @@
 # [Video.js][vjs] Documentation
 
-There are two categories of docs: [Guides][guides] and [API docs][guides-api].
+There are two categories of docs: [Guides][guides] and [API docs][api].
 
 Guides explain general topics and use cases (e.g. setup). API docs are automatically generated from the codebase and give specific details about functions, properties, and events.
 
@@ -10,7 +10,7 @@ Guides explain general topics and use cases (e.g. setup). API docs are automatic
 
 #### [Setup][guides-setup]
 
-The setup documentation gives a deeper view of the additional methods you can use to trigger the player setup.
+The setup guide covers all methods of setting up Video.js players.
 
 #### [Options][guides-options]
 
@@ -22,27 +22,17 @@ Tracks are used for displaying text information over a video, selecting differen
 
 ### Customizing
 
-#### [API][guides-api]
-
-The Video.js API allows you to control the video through javascript or trigger event listeners, whether the video is playing through HTML5, flash, or another playback technology.
-
 #### [Skins][guides-skins]
 
 You can change the look of the player across playback technologies just by editing a CSS file. The skins documentation gives you a intro to how the HTML and CSS of the default skin is put together.
 
-#### [Tech][guides-tech]
-
-A "tech" is the shorthand we're using to describe any video playback technology - be it HTML5 video, Flash, . Basically anything that has a unique API to audio or video. Additional playback technologies can be added relatively easily.
-
 #### [Plugins][guides-plugins]
 
 You can package up interesting Video.js customizations and reuse them elsewhere. Find out how to build your own plugin or use one created by someone else.
 
-### Resources
-
-#### [Glossary][guides-glossary]
+#### [Tech][guides-tech]
 
-Some helpful definitions for those unfamiliar with web video-related terms - with links to more technical details.
+A "tech" is the shorthand we're using to describe any video playback technology - be it HTML5 video, Flash, . Basically anything that has a unique API to audio or video. Additional playback technologies can be added relatively easily.
 
 ## API Docs
 

From bdef60a2bbd4c4228cb6392510bd5101ac7df18d Mon Sep 17 00:00:00 2001
From: Pat O'Neill <pgoneill@gmail.com>
Date: Mon, 14 Nov 2016 14:22:02 -0500
Subject: [PATCH 08/20] Feedback changes

---
 README.md              |  17 +++--
 docs/guides/options.md | 141 ++++++++++++++++++++++++++---------------
 docs/guides/setup.md   |   2 +-
 docs/index.md          |   6 +-
 4 files changed, 109 insertions(+), 57 deletions(-)

diff --git a/README.md b/README.md
index 0ae82a09ef..fbaf86c4c0 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@
 
 [![NPM][npm-icon]][npm-link]
 
-> Video.js is a web video player built from the ground up for an HTML5 world. It supports HTML5 and Flash video, as well as YouTube and Vimeo (through [plugins][plugins]). It supports video playback on desktops and mobile devices. This project was started mid 2010, and the player is now used on over ~~50,000~~ ~~100,000~~ 200,000 websites.
+> Video.js is a web video player built from the ground up for an HTML5 world. It supports HTML5 and Flash video, as well as YouTube and Vimeo (through [plugins][plugins]). It supports video playback on desktops and mobile devices. This project was started mid 2010, and the player is now used on over ~~50,000~~ ~~100,000~~ ~~200,000~~ 400,000 websites.
 
 ## Quick Start
 
@@ -46,13 +46,22 @@ Next, using Video.js is as simple as creating a `<video>` element, but with an a
 
 When the page loads, Video.js will find this element and automatically setup a player in its place.
 
-If you don't want to use automatic setup, you can leave off the `data-setup` attribute and initialize a `<video>` element manually:
+If you don't want to use automatic setup, you can leave off the `data-setup` attribute and initialize a `<video>` element manually using the `videojs` function:
 
 ```js
-var player = videojs('my-player', { /* options */ }, function() {
+var player = videojs('my-player');
+```
+
+The `videojs` function also accepts an `options` object and a callback to be invoked
+ when the player is ready:
+
+```js
+var options = {};
+
+var player = videojs('my-player', options, function onPlayerReady() {
   videojs.log('Your player is ready!');
 
-  // If you don't trust autoplay for some reason...
+  // In this context, `this` is the player that was created by Video.js.
   this.play();
 
   // How about an event listener?
diff --git a/docs/guides/options.md b/docs/guides/options.md
index 9b0a574c1d..0f89908b7e 100644
--- a/docs/guides/options.md
+++ b/docs/guides/options.md
@@ -37,119 +37,101 @@
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
 ## Standard `<video>` Element Options
-
 Each of these options is also available as a [standard `<video>` element attribute][video-attrs]; so, they can be defined in all three manners [outlined above](#setting-options). Typically, defaults are not listed as this is left to browser vendors.
 
 ### `autoplay`
+> Type: `boolean`
 
-> Type: `Boolean`
-
-If `true`/present as an attribute, begins playback automatically.
+If `true`/present as an attribute, begins playback when the player is ready.
 
 > **Note:** As of iOS 10, Apple offers `autoplay` support in Safari. For details, refer to ["New <video> Policies for iOS"][ios-10-updates].
 
 ### `controls`
-
-> Type: `Boolean`
+> Type: `boolean`
 
 Determines whether or not the player has controls that the user can interact with. Without controls the only way to start the video playing is with the `autoplay` attribute or through the Player API.
 
 ### `height`
-
-> Type: `String|Number`
+> Type: `string|number`
 
 Sets the display height of the video player in pixels.
 
 ### `loop`
-
-> Type: `Boolean`
+> Type: `boolean`
 
 Causes the video to start over as soon as it ends.
 
 ### `muted`
-
-> Type: `Boolean`
+> Type: `boolean`
 
 Will silence any audio by default.
 
 ### `poster`
-
-> Type: `String`
+> Type: `string`
 
 A URL to an image that displays before the video begins playing. This is often a frame of the video or a custom title screen. As soon as the user hits "play" the image will go away.
 
 ### `preload`
-
-> Type: `String`
+> Type: `string`
 
 Suggests to the browser whether or not the video data should begin downloading as soon as the `<video>` element is loaded. Supported values are:
 
-- `'auto'`
+#### `'auto'`
+Start loading the video immediately (if the browser supports it). Some mobile devices will not preload the video in order to protect their users' bandwidth/data usage. This is why the value is called 'auto' and not something more conclusive like `'true'`.
 
-  Start loading the video immediately (if the browser supports it). Some mobile devices will not preload the video in order to protect their users' bandwidth/data usage. This is why the value is called 'auto' and not something more conclusive like `'true'`.
+_This tends to be the most common and recommended value as it allows the browser to choose the best behavior._
 
-  _This tends to be the most common and recommended value as it allows the browser to choose the best behavior._
+#### `'metadata'`
+Load only the meta data of the video, which includes information like the duration and dimensions of the video. Sometimes, the meta data will be loaded by downloading a few frames of video.
 
-- `'metadata'`
-
-  Load only the meta data of the video, which includes information like the duration and dimensions of the video.
-
-- `'none'`
-
-  Don't preload any data. The browser will wait until the user hits "play" to begin downloading.
+#### `'none'`
+Don't preload any data. The browser will wait until the user hits "play" to begin downloading.
 
 ### `src`
-
-> Type: `String`
+> Type: `string`
 
 The source URL to a video source to embed.
 
 ### `width`
-
-> Type: `String|Number`
+> Type: `string|number`
 
 Sets the display height of the video player in pixels.
 
 ## Video.js-specific Options
-
 Each option is `undefined` by default unless otherwise specified.
 
 ### `aspectRatio`
-
-> Type: `String`
+> Type: `string`
 
 Puts the player in [fluid](#fluid) mode and the value is used when calculating the dynamic size of the player. The value should represent a ratio - two numbers separated by a colon (e.g. `"16:9"` or `"4:3"`).
 
 ### `children`
+> Type: `Array|Object`
 
-> Type: `Array`
+This option is inherited from the [`Component` base class](#component-options).
 
 ### `fluid`
-
-> Type: `Boolean`
+> Type: `boolean`
 
 When `true`, the Video.js player will have a fluid size. In other words, it will scale to fit its container.
 
 Also, if the `<video>` element has the `"vjs-fluid"`, this option is automatically set to `true`.
 
 ### `inactivityTimeout`
-
-> Type: `Number`
+> Type: `number`
 
 Video.js indicates that the user is interacting with the player by way of the `"vjs-user-active"` and `"vjs-user-inactive"` classes and the `"useractive"` event.
 
 The `inactivityTimeout` determines how many milliseconds of inactivity is required before declaring the user inactive. A value of `0` indicates that there is no `inactivityTimeout` and the user will never be considered inactive.
 
 ### `language`
-
-> Type: `String`
+> Type: `string`, Default: browser default or `'en'`
 
 A [language code][lang-codes] matching one of the available languages in the player. This sets the initial language for a player, but it can always be changed.
 
 Learn more about [languages in Video.js](languages.md).
 
 ### `languages`
-
 > Type: `Object`
 
 Customize which languages are available in a player. The keys of this object will be [language codes][lang-codes] and the values will be objects with English keys and translated values.
@@ -158,14 +140,17 @@ Learn more about [languages in Video.js](languages.md).
 
 > **Note**: Generally, this option is not needed and it would be better to pass your custom languages to `videojs.addLanguage()`, so they are available in all players!
 
-### `notSupportedMessage`
+### `nativeControlsForTouch`
+> Type: `boolean`
 
-> Type: `String`
+Explicitly set a default value for [the associated tech option](#nativecontrolsfortouch).
+
+### `notSupportedMessage`
+> Type: `string`
 
 Allows overriding the default message that is displayed when Video.js cannot play back a media source.
 
 ### `plugins`
-
 > Type: `Object`
 
 This supports having plugins be initialized automatically with custom options when the player is initialized - rather than requiring you to initialize them manually.
@@ -190,9 +175,10 @@ player.boo({baz: false});
 
 Although, since the `plugins` option is an object, the order of initialization is not guaranteed!
 
-### `sourceOrder`
+See [the plugins guide](plugins.md) for more information on Video.js plugins.
 
-> Type: `Boolean`
+### `sourceOrder`
+> Type: `Array`
 
 Tells Video.js to prefer the order of [`sources`](#sources) over [`techOrder`](#techOrder) in selecting a source and playback tech.
 
@@ -232,7 +218,6 @@ With `sourceOrder: true`, the algorithm becomes:
     - if tech can play source, use this tech/source combo
 
 ### `sources`
-
 > Type: `Array`
 
 An array of objects that mirror the native `<video>` element's capability to have a series of child `<source>` elements. This should be an array of objects with the `src` and `type` properties. For example:
@@ -249,12 +234,25 @@ videojs('my-player', {
 });
 ```
 
-### `techOrder`
+Using `<source>` elements will have the same effect:
+
+```html
+<video ...>
+  <source src="//path/to/video.mp4" type="video/mp4">
+  <source src="//path/to/video.webm" type="video/webm">
+</video>
+```
 
+### `techOrder`
 > Type: `Array`, Default: `['html5', 'flash']`
 
 Defines the order in which Video.js techs are preferred. By default, this means that the `Html5` tech is preferred, but Video.js will fall back to `Flash` if no `Html5`-compatible source can be found.
 
+### `vtt.js`
+> Type: `string`
+
+Allows overriding the default URL to vtt.js, which may be loaded asynchronously to polyfill support for `WebVTT`.
+
 ## Component Options
 
 The Video.js player is a component. Like all components, you can define what children it includes, what order they appear in, and what options are passed to them.
@@ -262,12 +260,34 @@ The Video.js player is a component. Like all components, you can define what chi
 This is meant to be a quick reference; so, for more detailed information on components in Video.js, check out the [components guide](components.md).
 
 ### `children`
-
 > Type: `Array|Object`
 
-If an `Array` - which is the default - this is used to determine the order in which children are created on a player.
+If an `Array` - which is the default - this is used to determine which children (by component name) and in which order they are created on a player (or other component):
 
-This can also be passed as an `Object`. In this case, it is used to provide `options` for any/all children.
+```js
+// The following code creates a player with ONLY bigPlayButton and
+// controlBar child components.
+videojs('my-player', {
+  children: [
+    'bigPlayButton',
+    'controlBar'
+  ]
+});
+```
+
+The `children` options can also be passed as an `Object`. In this case, it is used to provide `options` for any/all children, including disabling them with `false`:
+
+```js
+// This player's ONLY child will be the controlBar. Clearly, this is not the
+// ideal method for disabling a grandchild!
+videojs('my-player', {
+  children: {
+    controlBar: {
+      fullscreenControl: false
+    }
+  }
+});
+```
 
 ### `${componentName}`
 
@@ -307,6 +327,25 @@ However, this is a case where changing the global defaults is more useful:
 videojs.options.flash.swf = '//path/to/videojs.swf'
 ```
 
+#### `nativeCaptions`
+
+> Type: `boolean`
+
+Can be set to `false` to force emulation of text tracks instead of native support.
+
+#### `nativeControlsForTouch`
+
+> Type: `boolean`
+
+Only supported by the `Html5` tech, this option can be set to `true` to force native controls for touch devices.
+
+#### `nativeTextTracks`
+
+> Type: `boolean`
+
+Can be set to `false` to force emulation of text tracks instead of native support.
+
+
 [ios-10-updates]: https://webkit.org/blog/6784/new-video-policies-for-ios/
 [lang-codes]: http://www.iana.org/assignments/language-subtag-registry/language-subtag-registry
 [video-attrs]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video#Attributes
diff --git a/docs/guides/setup.md b/docs/guides/setup.md
index dd6aa76490..82edd98f0e 100644
--- a/docs/guides/setup.md
+++ b/docs/guides/setup.md
@@ -119,7 +119,7 @@ videojs.options.autoplay = true;
 
 ### A Note on `<video>` Tag Attributes
 
-Many attributes are so-called [boolean attributes][boolean-attrs]. This means they are either on or off. In these cases, the attribute _should have no value_ - its presence implies a true value and its absence implies a false value.
+Many attributes are so-called [boolean attributes][boolean-attrs]. This means they are either on or off. In these cases, the attribute _should have no value_ (or should have its name as its value) - its presence implies a true value and its absence implies a false value.
 
 _These are incorrect:_
 
diff --git a/docs/index.md b/docs/index.md
index d8596976cd..b069445c1c 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -28,7 +28,11 @@ You can change the look of the player across playback technologies just by editi
 
 #### [Plugins][guides-plugins]
 
-You can package up interesting Video.js customizations and reuse them elsewhere. Find out how to build your own plugin or use one created by someone else.
+You can package up interesting Video.js customizations and reuse them elsewhere. Find out how to build your own plugin or [use one created by someone else](https://github.com/videojs/video.js/wiki/Plugins).
+
+#### [Components][guides-components]
+
+Video.js is built around a collection of components. These are the building blocks of the player UI.
 
 #### [Tech][guides-tech]
 

From 0ab9f861c6a09fb7243221e538d4d6f311a1edff Mon Sep 17 00:00:00 2001
From: Pat O'Neill <pgoneill@gmail.com>
Date: Tue, 15 Nov 2016 10:19:23 -0500
Subject: [PATCH 09/20] Add link to builtwith

---
 README.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index fbaf86c4c0..9162e12aa1 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@
 
 [![NPM][npm-icon]][npm-link]
 
-> Video.js is a web video player built from the ground up for an HTML5 world. It supports HTML5 and Flash video, as well as YouTube and Vimeo (through [plugins][plugins]). It supports video playback on desktops and mobile devices. This project was started mid 2010, and the player is now used on over ~~50,000~~ ~~100,000~~ ~~200,000~~ 400,000 websites.
+> Video.js is a web video player built from the ground up for an HTML5 world. It supports HTML5 and Flash video, as well as YouTube and Vimeo (through [plugins][plugins]). It supports video playback on desktops and mobile devices. This project was started mid 2010, and the player is now used on over ~~50,000~~ ~~100,000~~ ~~200,000~~ [400,000 websites][builtwith].
 
 ## Quick Start
 
@@ -83,7 +83,9 @@ _Video.js uses [BrowserStack][browserstack] for compatibility testing._
 
 Video.js is [licensed][license] under the Apache License, Version 2.0.
 
+
 [browserstack]: https://browserstack.com
+[buildwith]: https://trends.builtwith.com/media/VideoJS
 [contributing]: CONTRIBUTING.md
 [contributing-building]: CONTRIBUTING.md#building-your-own-copy-of-videojs
 [contributing-code]: CONTRIBUTING.md#contributing-code

From ed0022e4f7342c5cc3327ee6a9a0b014955480ac Mon Sep 17 00:00:00 2001
From: Pat O'Neill <pgoneill@gmail.com>
Date: Wed, 30 Nov 2016 12:08:07 -0500
Subject: [PATCH 10/20] Address code review comments

---
 docs/guides/options.md | 19 ++++++-------------
 1 file changed, 6 insertions(+), 13 deletions(-)

diff --git a/docs/guides/options.md b/docs/guides/options.md
index 0f89908b7e..349512e67e 100644
--- a/docs/guides/options.md
+++ b/docs/guides/options.md
@@ -178,7 +178,9 @@ Although, since the `plugins` option is an object, the order of initialization i
 See [the plugins guide](plugins.md) for more information on Video.js plugins.
 
 ### `sourceOrder`
-> Type: `Array`
+> Type: `boolean`, Default: `false`
+
+> **Note:** In video.js 6.0, this option will default to `true`.
 
 Tells Video.js to prefer the order of [`sources`](#sources) over [`techOrder`](#techOrder) in selecting a source and playback tech.
 
@@ -253,6 +255,8 @@ Defines the order in which Video.js techs are preferred. By default, this means
 
 Allows overriding the default URL to vtt.js, which may be loaded asynchronously to polyfill support for `WebVTT`.
 
+This option will be used in the "novtt" build of video.js (i.e. `video.novtt.js`). Otherwise, vtt.js is bundled with video.js.
+
 ## Component Options
 
 The Video.js player is a component. Like all components, you can define what children it includes, what order they appear in, and what options are passed to them.
@@ -290,7 +294,6 @@ videojs('my-player', {
 ```
 
 ### `${componentName}`
-
 > Type: `Object`
 
 Components can be given custom options via the _lower-camel-case variant of the component name_ (e.g. `controlBar` for `ControlBar`). These can be nested in a representation of grandchild relationships. For example, to disable the fullscreen control:
@@ -304,9 +307,7 @@ videojs('my-player', {
 ```
 
 ## Tech Options
-
 ### `${techName}`
-
 > Type: `Object`
 
 Video.js playback technologies (i.e. "techs") can be given custom options as part of the options passed to the `videojs` function. They should be passed under the _lower-case variant of the tech name_ (e.g. `"flash"` or `"html5"`).
@@ -327,23 +328,15 @@ However, this is a case where changing the global defaults is more useful:
 videojs.options.flash.swf = '//path/to/videojs.swf'
 ```
 
-#### `nativeCaptions`
-
-> Type: `boolean`
-
-Can be set to `false` to force emulation of text tracks instead of native support.
-
 #### `nativeControlsForTouch`
-
 > Type: `boolean`
 
 Only supported by the `Html5` tech, this option can be set to `true` to force native controls for touch devices.
 
 #### `nativeTextTracks`
-
 > Type: `boolean`
 
-Can be set to `false` to force emulation of text tracks instead of native support.
+Can be set to `false` to force emulation of text tracks instead of native support. The `nativeCaptions` option also exists, but is simply an alias to `nativeTextTracks`.
 
 
 [ios-10-updates]: https://webkit.org/blog/6784/new-video-policies-for-ios/

From 13a0eec90526a57ba4dabd3d5ded1e9c099c7de7 Mon Sep 17 00:00:00 2001
From: Pat O'Neill <pgoneill@gmail.com>
Date: Mon, 31 Oct 2016 16:57:18 -0400
Subject: [PATCH 11/20] tracks index

---
 docs/guides/tracks.md | 17 +++++++++++++----
 1 file changed, 13 insertions(+), 4 deletions(-)

diff --git a/docs/guides/tracks.md b/docs/guides/tracks.md
index d72a61969a..2c3f09ad0c 100644
--- a/docs/guides/tracks.md
+++ b/docs/guides/tracks.md
@@ -1,6 +1,15 @@
 # Tracks
-There are currently three types of tracks
 
-* [AudioTracks](./audio-tracks.md) - allows the selection of alternative AudioTracks for a video
-* [VideoTracks](./video-tracks.md) - allows the selection of an alternative VideoTrack for a video
-* [TextTracks](./text-tracks.md) - Text Tracks are used to display subtitles and captions, and add a menu for navigating between chapters in a video.
+There are currently three types of tracks:
+
+## [Audio Tracks](./audio-tracks.md)
+
+Audio tracks allow the selection of alternate audio for a video.
+
+## [Video Tracks](./video-tracks.md)
+
+Video tracks allow the selection of alternate video content.
+
+## [Text Tracks](./text-tracks.md)
+
+Text tracks are used to display subtitles and captions and add a menu for navigating between chapters in a video.

From d2195759f6ea6eea3657d385585917c1eeb673a3 Mon Sep 17 00:00:00 2001
From: Pat O'Neill <pgoneill@gmail.com>
Date: Wed, 2 Nov 2016 17:06:58 -0400
Subject: [PATCH 12/20] Update tracks guides

---
 docs/guides/audio-tracks.md | 105 +++++++++-------
 docs/guides/text-tracks.md  | 241 +++++++++++++++++++-----------------
 docs/guides/video-tracks.md | 113 +++++++++--------
 3 files changed, 250 insertions(+), 209 deletions(-)

diff --git a/docs/guides/audio-tracks.md b/docs/guides/audio-tracks.md
index 4d35288778..74a9300a28 100644
--- a/docs/guides/audio-tracks.md
+++ b/docs/guides/audio-tracks.md
@@ -1,55 +1,43 @@
 # Audio Tracks
+Audio tracks are a feature of HTML5 video for providing alternate audio track selections to the user, so that a track other than the main track can be played. Video.js offers a cross-browser implementation of audio tracks.
 
-Audio Tracks are a function of HTML5 video for providing alternative audio track selections to the user, so that a track other than the main track can be played. Video.js makes audio tracks work across all browsers. There are currently five types of tracks:
+## Caveats
+- It is not possible to add audio tracks through HTML. They must be added [programmatically](#api).
+- Literal switching of audio tracks for playback is not handled by Video.js and must be handled by something else. Video.js only stores the track representation.
 
-- **Alternative**: alternative audio for the main video track
-- **Descriptions**: descriptions of what is happening in the video track
-- **Main**: the main audio track for this video
-- **Translation**: a translation of the main audio track
-- **Commentary**: commentary on the video, usually the director of the content talking about design choices
-
-## Missing Funtionality
-- It is currently impossible to add AudioTracks in a non-programtic way
-- Literal switching of AudioTracks for playback is not handled by video.js and must be handled by something else. video.js only stores the track representation
-
-## Adding to Video.js
-
-> Right now adding audio tracks in the HTML is unsupported. Audio Tracks must be added programatically.
-
-You must add audio tracks [programatically](#api) for the time being.
-
-## Attributes
-Audio Track propertites and settings
-
-### kind
-One of the five track types listed above. Kind defaults to empty string if no kind is included, or an invalid kind is used.
-
-### label
-The label for the track that will be show to the user, for example in a menu that list the different languages available for audio tracks.
+## Working with Audio Tracks
+### Add an Audio Track to the Player
+```js
+// Create a player.
+var player = videojs('my-player');
+
+// Create a track object.
+var track = new videojs.AudioTrack({
+  kind: 'translation',
+  label: 'Spanish',
+  language: 'es'
+});
 
-### language
-The two-letter code (valid BCP 47 language tag) for the language of the audio track, for example "en" for English. A list of language codes is [available here](languages.md#language-codes).
+// Add the track to the player's audio track list.
+player.audioTracks().addTrack(track);
+```
 
-### enabled
-If this track should be playing or not. In video.js we only allow one track to be enabled at a time. so if you enable more than one the last one to be enabled will end up being the only one.
+### Listen for a Track Becoming Enabled
+When a new track is enabled (other than the main track) an event is fired on the `AudioTrackList` called `"change"`. You can listen for that event and do something with it.
 
-## Interacting with Audio Tracks
-### Doing something when a track becomes enabled
-When a new track is enabled (other than the main track) an event is fired on the `AudioTrackList` called `change` you can listen to that event and do something with it.
-Here's an example:
 ```js
-// get the current players AudioTrackList object
-let tracks = player.audioTracks();
+// Get the current player's AudioTrackList object.
+var tracks = player.audioTracks();
 
-// listen to the change event
+// Listen to the "change" event.
 tracks.addEventListener('change', function() {
 
-  // print the currently enabled AudioTrack label
-  for (let i = 0; i < tracks.length; i++) {
-    let track = tracks[i];
+  // Log the currently enabled AudioTrack label.
+  for (var i = 0; i < tracks.length; i++) {
+    var track = tracks[i];
 
     if (track.enabled) {
-      console.log(track.label);
+      videojs.log(track.label);
       return;
     }
   }
@@ -57,13 +45,36 @@ tracks.addEventListener('change', function() {
 ```
 
 ## API
+### `videojs.AudioTrack`
+This class can be used to create new audio track objects. Each property below is available as an option to the `AudioTrack` constructor.
+
+#### `kind`
+One of the audio track types supported by Video.js:
+
+- `"alternative"`: A possible alternative to the main track.
+- `"descriptions"`: An audio description of a video track.
+- `"main"`: The primary audio track for this video.
+- `"main-desc"`: The primary audio track, mixed with audio descriptions.
+- `"translation"`: A translated version of the main audio track.
+- `"commentary"`: Commentary on the primary audio track, e.g. a director's commentary.
+
+Defaults to empty string if `kind` is missing or an invalid `kind` is used.
+
+#### `label`
+The label for the track that will be shown to the user. For example, in a menu that lists the different languages available as alternate audio tracks.
+
+#### `language`
+The valid BCP 47 code for the language of the audio track, e.g. `"en"` for English or `"es"` for Spanish. For supported language translations, please see the [Languages Folder (/lang)](https://github.com/videojs/video.js/tree/master/lang) folder located in the Video.js root.
+
+#### `enabled`
+Whether or not this track should be playing. In Video.js, we only allow one track to be enabled at a time; so, if you enable more than one the last one to be enabled will end up being the only one.
 
-### `player.audioTracks() -> AudioTrackList`
-This is the main interface into the audio tracks of the player.
-It returns an AudioTrackList which is an array like object that contains all the `AudioTrack` on the player.
+### Player Methods
+#### `player.audioTracks()`
+This is the main interface into the audio tracks of the player. It returns an `AudioTrackList`, which is an array-like object that contains all the `AudioTrack`s associated with the player.
 
-### `player.audioTracks().addTrack(AudioTrack)`
-Add an existing AudioTrack to the players internal list of AudioTracks.
+#### `player.audioTracks().addTrack(AudioTrack)`
+Add an `AudioTrack` object to the player's `AudioTrackList`.
 
-### `player.audioTracks().removeTrack(AudioTrack)`
-Remove a track from the AudioTrackList currently on the player. if no track exists this will do nothing.
+#### `player.audioTracks().removeTrack(AudioTrack)`
+Remove an `AudioTrack` from the player's `AudioTrackList`. If the track is not in the `AudioTrackList`, it is simply ignored.
diff --git a/docs/guides/text-tracks.md b/docs/guides/text-tracks.md
index bfbbed932b..bb3922f515 100644
--- a/docs/guides/text-tracks.md
+++ b/docs/guides/text-tracks.md
@@ -1,119 +1,104 @@
 # Text Tracks
-
-Text Tracks are a function of HTML5 video for providing time triggered text to the viewer. Video.js makes tracks work across all browsers. There are currently five types of tracks:
-
-- **Subtitles**: Translations of the dialogue in the video for when audio is available but not understood. Subtitles are shown over the video.
-- **Captions**: Transcription of the dialogue, sound effects, musical cues, and other audio information for when the viewer is deaf/hard of hearing, or the video is muted. Captions are also shown over the video.
-- **Chapters**: Chapter titles that are used to create navigation within the video. Typically they're in the form of a list of chapters that the viewer can click on to go to a specific chapter.
-- **Descriptions**: Text descriptions of what's happening in the video for when the video portion isn't available, because the viewer is blind, not using a screen, or driving and about to crash because they're trying to enjoy a video while driving. Descriptions are read by a screen reader or turned into a separate audio track.
-- **Metadata**: Tracks that have data meant for javascript to parse and do something with. These aren't shown to the user.
+Text tracks are a feature of HTML5 video for displaying time-triggered text to the viewer. Video.js offers a cross-browser implementation of audio tracks.
 
 ## Creating the Text File
-Timed text requires a text file in [WebVTT](http://dev.w3.org/html5/webvtt/) format. This format defines a list of "cues" that have a start time, and end time, and text to display. [Microsoft has a builder](https://dev.modern.ie/testdrive/demos/captionmaker/) that can help you get started on the file.
+Timed text requires a text file in [WebVTT](http://dev.w3.org/html5/webvtt/) format. This format defines a list of "cues" that have a start time, an end time, and text to display. [Microsoft has a builder](https://dev.modern.ie/testdrive/demos/captionmaker/) that can help you get started on the file.
 
-When creating captions, there's also additional [caption formatting techniques] (http://www.theneitherworld.com/mcpoodle/SCC_TOOLS/DOCS/SCC_FORMAT.HTML#style) that would be good to use, like brackets around sound effects: [ sound effect ]. If you'd like a more in depth style guide for captioning, you can reference the [Captioning Key](http://www.dcmp.org/captioningkey/), but keep in mind not all features are supported by WebVTT or (more likely) the Video.js WebVTT implementation.
+When creating captions, there are additional [caption formatting techniques](http://www.theneitherworld.com/mcpoodle/SCC_TOOLS/DOCS/SCC_FORMAT.HTML#style) to make captions more meaningful, like brackets around sound effects (e.g. `[ birds chirping ]`). For a more in depth style guide for captioning, see the [Captioning Key](http://www.dcmp.org/captioningkey/), but keep in mind not all features are supported by WebVTT or (more likely) the Video.js WebVTT implementation.
 
-## Adding to Video.js
-Once you have your WebVTT file created, you can add it to Video.js using the track tag. Put your track tag after all the source elements, and before any fallback content.
+## Adding Text Tracks to Video.js
+Once you have your WebVTT file created, you can add it to Video.js using the `<track>` tag. Put your `<track>` tag(s) after all the source elements and before any fallback content.
 
 ```html
-<video id="example_video_1" class="video-js"
-  controls preload="auto" width="640" height="264"
-  data-setup='{"example_option":true}'>
- <source src="http://vjs.zencdn.net/v/oceans.mp4" type="video/mp4" />
- <source src="http://vjs.zencdn.net/v/oceans.webm" type="video/webm" />
- <source src="http://vjs.zencdn.net/v/oceans.ogv" type="video/ogg" />
-
- <track kind="captions" src="http://example.com/path/to/captions.vtt" srclang="en" label="English" default>
-
+<video
+  class="video-js"
+  controls
+  preload="auto"
+  width="640"
+  height="264"
+  data-setup='{}'>
+ <source src="//vjs.zencdn.net/v/oceans.mp4" type="video/mp4">
+ <source src="//vjs.zencdn.net/v/oceans.webm" type="video/webm">
+ <track kind="captions" src="//example.com/path/to/captions.vtt" srclang="en" label="English" default>
 </video>
 ```
 
-You can also add tracks [programatically](#api).
+You can also add tracks [programmatically](#api).
+
+### Text Tracks from Another Domain
+Because Video.js loads the text track file via JavaScript, the [same-origin policy](http://en.wikipedia.org/wiki/Same_origin_policy) applies. If you'd like to have a player served from one domain, but the text track served from another, you'll need to [enable CORS](http://enable-cors.org/) on the server that is serving your text tracks.
+
+In addition to enabling CORS, you will need to add the [`crossorigin` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/CORS_settings_attributes) to the video element itself. This attribute has two possible values `"anonymous"` and `"use-credentials"`. Most users will want to use `"anonymous"` with cross-origin tracks:
 
-## Subtitles from Another Domain
-Because we're pulling in the text track file via Javascript, the [same-origin policy](http://en.wikipedia.org/wiki/Same_origin_policy) applies. If you'd like to have a player served from one domain,
-but the text track served from another, you'll need to [enable CORS](http://enable-cors.org/) in order to do so.
-In addition to enabling CORS on the server serving the text tracks, you will need to add the [`crossorigin` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/CORS_settings_attributes) to the video element itself. This attribute has two values `anonymous` and `use-credentials`. Most users will want to use `anonymous` with cross-origin tracks.
-It can be added to the video element like so:
 ```html
 <video class="video-js" crossorigin="anonymous">
-  <source src="http://vjs.zencdn.net/v/oceans.mp4" type="video/mp4">
-  <track src="http://example.com/oceans.vtt" kind="captions" srclang="en" label="English">
+  <source src="//vjs.zencdn.net/v/oceans.mp4" type="video/mp4">
+  <track src="//example.com/oceans.vtt" kind="captions" srclang="en" label="English">
 </video>
 ```
-One thing to be aware of is that in this case the video files themselves will *also* needs CORS headers applied to it. This is because some browsers apply the crossorigin attribute to the video source itself and not just the tracks and is considered a [security concern by the spec](https://html.spec.whatwg.org/multipage/embedded-content.html#security-and-privacy-considerations).
-
-## Track Attributes
-Additional settings for track tags.
 
-### kind
-One of the five track types listed above. Kind defaults to subtitles if no kind is included.
+One thing to be aware of is that the video files themselves will _also_ need CORS headers. This is because some browsers apply the `crossorigin` attribute to the video source itself and not just the tracks. This is considered a [security concern by the spec](https://html.spec.whatwg.org/multipage/embedded-content.html#security-and-privacy-considerations).
 
-### label
-The label for the track that will be show to the user, for example in a menu that list the different languages available for subtitles.
+## Working with Text Tracks
+### Showing Tracks Programmatically
+Certain use cases call for turning captions on and off programmatically rather than forcing the user to do so themselves. This can be easily achieved by modifying the `mode` property of the text tracks.
 
-### default
-The default attribute can be used to have a track default to showing. Otherwise the viewer would need to select their language from the captions or subtitles menu.
-NOTE: For chapters, default is required if you want the chapters menu to show.
+The `mode` can be one of three values `"disabled"`, `"hidden"`, and `"showing"`. When a text track's `mode` is `"disabled"`, the track does not show on screen as the video is playing.
 
-### srclang
-The two-letter code (valid BCP 47 language tag) for the language of the text track, for example "en" for English. A list of language codes is [available here](languages.md#language-codes).
+When the `mode` is set to `"showing"`, the track is visible to the viewer and updates while the video is playing.
 
-## Interacting with Text Tracks
-### Showing tracks programmatically
-Some of you would want to turn captions on and off programmatically rather than just forcing the user to do so themselves. This can be easily achieved by modifying the `mode` of the text tracks.
-The `mode` can be one of three values `disabled`, `hidden`, and `showing`.
-When a text track's `mode` is `disabled`, the track does not show on screen as the video is playing.
-When the `mode` is set to `showing`, the track is visible to the viewer and updates while the video is playing.
-You can change of a particular track like so:
 ```js
-let tracks = player.textTracks();
+// Get all text tracks for the current player.
+var tracks = player.textTracks();
 
-for (let i = 0; i < tracks.length; i++) {
-  let track = tracks[i];
+for (var i = 0; i < tracks.length; i++) {
+  var track = tracks[i];
 
-  // find the captions track that's in english
+  // Find the English captions track and mark it as "showing".
   if (track.kind === 'captions' && track.language === 'en') {
     track.mode = 'showing';
   }
 }
 ```
 
-### Doing something when a cue becomes active
-Above, we mentioned that `mode` can also be `hidden`, what this means is that the track will update
-as the video is playing but it won't be visible to the viewer. This is most useful for `metadata` text tracks.
-One usecase for metadata text tracks is to have something happen when their cues become active, to do so, you listen to the `cuechange` event on the track. These events fire when the mode is `showing` as well.
-Here's an example:
+### Listen for a Cue Becoming Active
+One of the supported values for `mode` is `"hidden"`. This `mode` means that the track will update as the video is playing, but it won't be visible to the viewer. This is most useful for tracks where `kind="metadata"`.
+
+A common use case for metadata text tracks is to use them to trigger behaviors when their cues become active. For this purpose, tracks emit a `"cuechange"` event.
+
 ```js
-let tracks = player.textTracks();
-let metadataTrack;
+// Get all text tracks for the current player.
+var tracks = player.textTracks();
+var metadataTrack;
 
-for (let i = 0; i < tracks.length; i++) {
-  let track = tracks[i];
+for (var i = 0; i < tracks.length; i++) {
+  var track = tracks[i];
 
-  // find the metadata track that's labeled ads
-  if (track.kind === 'captions' && track.label === 'ads') {
+  // Find the metadata track that's labeled "ads".
+  if (track.kind === 'metadata' && track.label === 'ads') {
     track.mode = 'hidden';
-    // store it for usage outside of the loop
+
+    // Store it for usage outside of the loop.
     metadataTrack = track;
   }
 }
 
+// Add a listener for the "cuechange" event and start ad playback.
 metadataTrack.addEventListener('cuechange', function() {
   player.ads.startLinearAdMode();
 });
 ```
 
 ## Emulated Text Tracks
-By default, video.js will try and use native text tracks if possible and fall back to emulated text tracks if the native functionality is broken or incomplete or non-existent.
-The Flash tech will always use the emulated text track functionality.
-The video.js API and TextTrack objects were modeled after the w3c's specification.
-video.js uses [Mozilla's vtt.js](https://github.com/mozilla/vtt.js) library to parse and display its emulated text tracks.
+By default, Video.js will use native text tracks and fall back to emulated text tracks if the native functionality is broken, incomplete, or non-existent. The Flash tech will always use the emulated text track functionality.
+
+The Video.js API and TextTrack objects were modeled after the W3C specification. Video.js uses [Mozilla's vtt.js](https://github.com/mozilla/vtt.js) library to parse and display emulated text tracks.
+
+To disable native text track functionality and force Video.js to use emulated text tracks always, the `nativeTextTracks` option can be passed to a tech:
 
-If you wanted to disable native text track functionality and force video.js to use emulated text tracks always, you can supply the `nativeTextTracks` option to the tech like so:
 ```js
-let player = videojs('myvideo', {
+// Create a player, passing `nativeTextTracks: false` to the HTML5 tech.
+var player = videojs('myvideo', {
   html5: {
     nativeTextTracks: false
   }
@@ -121,64 +106,96 @@ let player = videojs('myvideo', {
 ```
 
 ### Text Track Settings
-When using emulated Text Tracks, captions will have an additional item in the menu called "caption settings".
-This allows the viewer of the player to change some styles of how the captions are displayed on screen.
+When using emulated text tracks, captions will have an additional item in the menu called "Caption Settings". This allows the user to alter how captions are styled on screen.
+
+This feature can be disabled by turning off the `TextTrackSettings` component and hiding the menu item.
 
-If you don't want that, you can disable it by turning off the text track settings component and hiding the menu item like so:
 ```js
-let player = videojs('myvideo', {
-  // make the text track settings dialog not initialize
+var player = videojs('myvideo', {
+  // Make the text track settings dialog not initialize.
   textTrackSettings: false
 });
 ```
+
 ```css
-/* hide the captions settings item from the captions menu */
+/* Hide the captions settings item from the captions menu. */
 .vjs-texttrack-settings {
   display: none;
 }
 ```
 
 ## Text Track Precedence
-In general, the Descriptions tracks is of lower precedence than captions and subtitles.
-What this means for you?
-* If you are using the `default` attribute, videojs will choose the first track that is marked as `default` and turn it on. If There are multiple tracks marked `default`, it will try and turn on the first `captions` or `subtitles` track *before* any `descriptions` tracks.
-  * This only applied to the emulated captions support, native text tracks behavior will change depending on the browser
-* If you select a given track from the menu, videojs will turn off all the other tracks of the same kind. This may seem like you can have both subtitles and captions turned on at the same time but unfortuantely, at this time we only support one track being displayed at a time.
-  * This means that for emulated text tracks, we'll choose the first captions or subtitles track that is enabled to display.
-  * When native text tracks are supported, we will still disable the other tracks of the same kind but it is possible that multiple text tracks are shown.
-  * If a `descriptions` track is selected and subsequently a `subtitles` or `captions` track is selected, the `descriptions` track is disabled and its menu button is also disabled.
-* When enabling a track programmatically, there's not much checking that videojs does.
-  * For emulated text tracks, when it's time to display the captions, video.js would choose the first track that's showing, again choosing `subtitles` or `captions` over `descriptions`, if necessary.
-  * For native text tracks, this behavior depends on the browser. Some browsers will let you have multiple text tracks but others will disable all other tracks when a new one is selected.
+In general, `"descriptions"` tracks are of lower precedence than `"captions"` and `"subtitles"`. What this mean for developers using Video.js?
+
+- If you are using the `default` attribute, Video.js will choose the first track that is marked as `default` and turn it on. If there are multiple tracks marked `default`, it will turn on the first `"captions"` or `"subtitles"` track _before_ any `"descriptions"` tracks.
+  - This only applied to the emulated text track support, native text tracks behavior will change depending on the browser.
+- If a track is selected from the menu, Video.js will turn off all the other tracks of the same kind. While this suggests Video.js supports both `"subtitles"` and `"captions"` being turned on simultaneously, this is currently not the case; Video.js only supports one track being displayed at a time.
+  - This means that for emulated text tracks, Video.js will display the first enabled `"subtitles"` or `"captions"` track.
+  - When native text tracks are supported, other tracks of the same kind will still be disabled, but it is possible that multiple text tracks are shown.
+  - If a `"descriptions"` track is selected and subsequently a `"subtitles"` or `"captions"` track is selected, the `"descriptions"` track is disabled and its menu button is also disabled.
+- When enabling a track programmatically, Video.js performs minimal enforcement.
+  - For emulated text tracks, Video.js chooses the first track that's `"showing"` - again choosing `"subtitles"` or `"captions"` over `"descriptions"`.
+  - For native text tracks, this behavior depends on the browser. Some browsers will allow multiple text tracks, but others will disable all other tracks when a new one is selected.
 
 ## API
+### `videojs.TextTrack`
+This class can be used to create new text track objects. Each property below is available as an option to the `TextTrack` constructor, as a property of the created `TextTrack` object, or as a DOM attribute.
 
-### `player.textTracks() -> TextTrackList`
-This is the main interface into the text tracks of the player.
-It return a TextTrackList which lists all the tracks on the player.
+#### `kind`
+One of the track types supported by Video.js:
 
-### `player.remoteTextTracks() -> TextTrackList`
-This is a helper method to get a list of all the tracks that were created from `track` elements or that were added to the player by the `addRemoteTextTrack` method. All these tracks are removeable from the player, where-as not all tracks from `player.textTracks()` are necessarily removeable.
+- `"subtitles"`: Translations of the dialogue in the video for when audio is available but not understood. Subtitles are shown over the video.
+- `"captions"`: Transcription of the dialogue, sound effects, musical cues, and other audio information for viewer who are deaf/hard of hearing, or the video is muted. Captions are also shown over the video.
+- `"chapters"`: Chapter titles that are used to create navigation within the video. Typically, these are in the form of a list of chapters that the viewer can use to navigate the video.
+- `"descriptions"`: Text descriptions of the action in the content for when the video portion isn't available or because the viewer is blind or not using a screen. Descriptions are read by a screen reader or turned into a separate audio track.
+- `"metadata"`: Tracks that have data meant for JavaScript to parse and do something with. These aren't shown to the user.
 
-### `player.remoteTextTrackEls() -> HTMLTrackElementList`
-Another helper method, this is a list of all the `track` elements associated with the player. Both emulated or otherwise.
+Defaults to `"subtitles"`.
 
-### `player.addTextTrack(String kind, [String label [, String language]]) -> TextTrack`
-This is based on the [w3c spec API](http://www.w3.org/html/wg/drafts/html/master/embedded-content-0.html#dom-media-addtexttrack) and when given a kind and an optional label and language, will create a new text track for you to use.
-This method is intended for purely programmatic usage of tracks and has one important limitation:
-tracks created using this method *cannot* be removed. The native `addTextTrack` does not have a corresponding `removeTextTrack`, so, we actually discourage the usage of this method.
+#### `label`
+Short descriptive text for the track that will used in the user interface. For example, in a menu for selecting a captions language.
+
+#### `default`
+The boolean `default` attribute can be used to indicate that a track's mode should start as `"showing"`. Otherwise, the viewer would need to select their language from a captions or subtitles menu.
+
+> **Note:** For chapters, `default` is required if you want the chapters menu to show.
+
+#### `srclang`
+The valid BCP 47 code for the language of the text track, e.g. `"en"` for English or `"es"` for Spanish. For supported language translations, please see the [Languages Folder (/lang)](https://github.com/videojs/video.js/tree/master/lang) folder located in the Video.js root.
+
+### Player Methods
+#### `player.textTracks()`
+This is the main interface into the text tracks of a player. It returns a `TextTrackList`, which is an array-like object that contains all the `TextTrack`s associated with the player.
+
+#### `player.remoteTextTracks()`
+This method returns a `TextTrackList` of all the tracks that were created from `<track>` elements or that were added to the player using the `addRemoteTextTrack` method.
+
+These are distinct from the list returned by `textTracks()` because all these tracks are _removeable_, whereas tracks from `textTracks()` are not necessarily removeable.
+
+#### `player.remoteTextTrackEls()`
+This methods returns a `HTMLTrackElementList` of all the `<track>` elements - both emulated and native - associated with the player.
+
+#### `player.addTextTrack(String kind, [String label [, String language]]) -> TextTrack`
+Based on the [W3C spec API](http://www.w3.org/html/wg/drafts/html/master/embedded-content-0.html#dom-media-addtexttrack), this method takes a `kind` and optional `label` and `language` arguments and creates a new `TextTrack`.
+
+> **Note:** This method is intended for _purely programmatic usage_ of tracks and has one important limitation:
+>
+> Tracks created using this method _cannot be removed_. The native `addTextTrack` does not have a corresponding `removeTextTrack`; so, we actually discourage the usage of this method.
+
+#### `player.addRemoteTextTrack(Object options)`
+This method takes an `options` object that looks pretty similar to the `<track>` element and returns a `HTMLTrackElement` object.
+
+The `HTMLTrackElement` object has a `track` property on it which is the actual `TextTrack` object. This object is equivalent to the one that can be returned from `addTextTrack()` with the added benefit that it can be removed from the player.
+
+Internally, Video.js will either add a `<track>` element for you or emulate one depending on whether native text tracks are supported or not.
 
-### `player.addRemoteTextTrack(Object options) -> HTMLTrackElement`
-This function takes an options object that looks pretty similar to the track element and returns a HTMLTrackElement.
-This object has a `track` property on it which is the actual TextTrack object.
-This `TextTrack` object is equivalent to the one that can be returned from `player.addTextTrack` with the added bonus that it can be removed from the player.
-Internally, video.js will either add a `<track>` element for you, or emulate that depending on whether native text tracks are supported or not.
 The options available are:
-* `kind`
-* `label`
-* `language` (also `srclang`)
-* `id`
-* `src`
-
-### `player.removeRemoteTextTrack(HTMLTrackElement|TextTrack)`
-This function takes either an HTMLTrackElement or a TextTrack object and removes it from the player.
+
+- `kind`
+- `label`
+- `language` (also `srclang`)
+- `id`
+- `src`
+
+#### `player.removeRemoteTextTrack(HTMLTrackElement|TextTrack)`
+This method takes either an `HTMLTrackElement` or a `TextTrack` object and removes it from the player.
diff --git a/docs/guides/video-tracks.md b/docs/guides/video-tracks.md
index 3723597412..bc81992b88 100644
--- a/docs/guides/video-tracks.md
+++ b/docs/guides/video-tracks.md
@@ -1,70 +1,83 @@
 # Video Tracks
+Video tracks are a feature of HTML5 video for providing alternate video tracks to the user, so they can change type of video they want to watch. Video.js offers a cross-browser implementation of video tracks.
 
-Video Tracks are a function of HTML5 video for providing a selection of alternative video tracks to the user, so that they can change type of video they want to watch. Video.js makes video tracks work across all browsers. There are currently six types of tracks:
+## Caveats
+- It is not possible to add video tracks through HTML. They must be added [programmatically](#api).
+- Literal switching of video tracks for playback is not handled by Video.js and must be handled by something else. Video.js only stores the track representation.
 
-- **Alternative**: an alternative video representation of the main video track
-- **Captions**: The main video track with burned in captions
-- **Main**: the main video track
-- **Sign**: the main video track with added sign language overlay
-- **Subtitles**: the main video track with burned in subtitles
-- **Commentary**: the main video track with burned in commentary
+## Working with Video Tracks
+### Add a Video Track to the Player
+```js
+// Create a player.
+var player = videojs('my-player');
+
+// Create a track object.
+var track = new videojs.VideoTrack({
+  kind: 'commentary',
+  label: 'Director\'s Commentary',
+  language: 'en'
+});
 
-## Missing Funtionality
-- It is currently impossible to add VideoTracks in a non-programtic way
-- Literal switching of VideoTracks for playback is not handled by video.js and must be handled by something else. video.js only stores the track representation
-- There is currently no UI implementation of VideoTracks
+// Add the track to the player's video track list.
+player.videoTracks().addTrack(track);
+```
 
-## Adding to Video.js
+### Listen for a Track Becoming Enabled
+When a new track is enabled (other than the main track) an event is fired on the `VideoTrackList` called `"change"`. You can listen for that event and do something with it.
 
-> Right now adding video tracks in the HTML is unsupported. Video Tracks must be added programatically.
+```js
+// Get the current player's VideoTrackList object.
+var tracks = player.videoTracks();
 
-You must add video tracks [programatically](#api) for the time being.
+// Listen to the "change" event.
+tracks.addEventListener('change', function() {
 
-## Attributes
-Video Track propertites and settings
+  // Log the currently enabled VideoTrack label.
+  for (var i = 0; i < tracks.length; i++) {
+    var track = tracks[i];
 
-### kind
-One of the five track types listed above. Kind defaults to empty string if no kind is included, or an invalid kind is used.
+    if (track.enabled) {
+      videojs.log(track.label);
+      return;
+    }
+  }
+});
+```
 
-### label
-The label for the track that will be show to the user, for example in a menu that list the different languages available for video tracks.
+## API
+### `videojs.VideoTrack`
+This class can be used to create new video track objects. Each property below is available as an option to the `VideoTrack` constructor.
 
-### language
-The two-letter code (valid BCP 47 language tag) for the language of the video track, for example "en" for English. A list of language codes is [available here](languages.md#language-codes).
+## Attributes
+Video Track propertites and settings
 
-### selected
-If this track should be playing or not. Trying to select more than one track will cause other tracks to be deselected.
+### `kind`
+One of the track types supported by Video.js:
 
-## Interacting with Video Tracks
-### Doing something when a track becomes enabled
-When a new track is enabled (other than the main track) an event is fired on the `VideoTrackList` called `change` you can listen to that event and do something with it.
-Here's an example:
-```js
-// get the current players VideoTrackList object
-let tracks = player.videoTracks();
+- `"alternative"`: A possible alternative to the main track.
+- `"captions"`: The main video track with burned in captions
+- `"main"`: The main video track.
+- `"sign"`: The main video track with added sign language overlay.
+- `"subtitles"`: The main video track with burned in subtitles.
+- `"commentary"`: The main video track with burned in commentary.
 
-// listen to the change event
-tracks.addEventListener('change', function() {
-  // get the currently selected track
-  let index = tracks.selectedIndex;
-  let track = tracks[index];
+Defaults to empty string if `kind` is missing or an invalid `kind` is used.
 
-  // print the currently selected track
-  console.log(track.label);
-});
-```
+### `label`
+The label for the track that will be shown to the user. For example, in a menu that lists the different captions available as alternate video tracks.
 
-## API
+### `language`
+The valid BCP 47 code for the language of the video track, e.g. `"en"` for English or `"es"` for Spanish. For supported language translations, please see the [Languages Folder (/lang)](https://github.com/videojs/video.js/tree/master/lang) folder located in the Video.js root.
 
-### `player.videoTracks() -> VideoTrackList`
-This is the main interface into the video tracks of the player.
-It returns an VideoTrackList which is an array like object that contains all the `VideoTrack` on the player.
+### `selected`
+Whether or not this track should be playing. Only one video track may be selected at a time.
 
-### `player.videoTracks().addTrack(VideoTrack)`
-Add an existing VideoTrack to the players internal list of VideoTracks.
+### Player Methods
+#### `player.videoTracks()`
+This is the main interface into the video tracks of the player. It returns a `VideoTrackList`, which is an array-like object that contains all the `VideoTrack`s associated with the player.
 
-### `player.videoTracks().removeTrack(VideoTrack)`
-Remove a track from the VideoTrackList currently on the player. if no track exists this will do nothing.
+#### `player.videoTracks().addTrack(VideoTrack)`
+Add an `VideoTrack` object to the player's `VideoTrackList`.
 
-### `player.videoTracks().selectedIndex`
-The current index for the selected track
+#### `player.videoTracks().removeTrack(VideoTrack)`
+Remove an `VideoTrack` from the player's `VideoTrackList`. If the track is not in the `VideoTrackList`, it is simply ignored.

From 0410954e3a6964aaecc97e4bd885a1ed45e42a34 Mon Sep 17 00:00:00 2001
From: Pat O'Neill <pgoneill@gmail.com>
Date: Wed, 30 Nov 2016 16:45:17 -0500
Subject: [PATCH 13/20] Address PR concerns

---
 docs/guides/audio-tracks.md |  73 ++++++++++++++-------
 docs/guides/text-tracks.md  | 122 ++++++++++++++++++------------------
 docs/guides/tracks.md       |   4 --
 docs/guides/video-tracks.md |  82 ++++++++++++++++--------
 4 files changed, 169 insertions(+), 112 deletions(-)

diff --git a/docs/guides/audio-tracks.md b/docs/guides/audio-tracks.md
index 74a9300a28..14f15c941d 100644
--- a/docs/guides/audio-tracks.md
+++ b/docs/guides/audio-tracks.md
@@ -2,8 +2,8 @@
 Audio tracks are a feature of HTML5 video for providing alternate audio track selections to the user, so that a track other than the main track can be played. Video.js offers a cross-browser implementation of audio tracks.
 
 ## Caveats
-- It is not possible to add audio tracks through HTML. They must be added [programmatically](#api).
-- Literal switching of audio tracks for playback is not handled by Video.js and must be handled by something else. Video.js only stores the track representation.
+- It is not possible to add audio tracks through HTML like you can with text tracks. They must be added programmatically.
+- Video.js only stores track representations. Switching audio tracks for playback is _not handled by Video.js_ and must be handled elsewhere - for example, videojs-contrib-hls handles switching audio tracks to support track selection through the UI.
 
 ## Working with Audio Tracks
 ### Add an Audio Track to the Player
@@ -13,6 +13,7 @@ var player = videojs('my-player');
 
 // Create a track object.
 var track = new videojs.AudioTrack({
+  id: 'my-spanish-audio-track',
   kind: 'translation',
   label: 'Spanish',
   language: 'es'
@@ -22,19 +23,21 @@ var track = new videojs.AudioTrack({
 player.audioTracks().addTrack(track);
 ```
 
-### Listen for a Track Becoming Enabled
-When a new track is enabled (other than the main track) an event is fired on the `AudioTrackList` called `"change"`. You can listen for that event and do something with it.
+### Listen for a Video Track Becoming Enabled
+When a track is enabled or disabled on an `AudioTrackList`, a `change` event will be fired. You can listen for that event and do something with it.
+
+> NOTE: The initial `AudioTrack` selection (usually the main track that is selected) should not fire a `change` event.
 
 ```js
 // Get the current player's AudioTrackList object.
-var tracks = player.audioTracks();
+var audioTrackList = player.audioTracks();
 
 // Listen to the "change" event.
-tracks.addEventListener('change', function() {
+audioTrackList.addEventListener('change', function() {
 
   // Log the currently enabled AudioTrack label.
-  for (var i = 0; i < tracks.length; i++) {
-    var track = tracks[i];
+  for (var i = 0; i < audioTrackList.length; i++) {
+    var track = audioTrackList[i];
 
     if (track.enabled) {
       videojs.log(track.label);
@@ -44,12 +47,38 @@ tracks.addEventListener('change', function() {
 });
 ```
 
+### Removing an Audio Track from the Player
+Assuming a player already exists and has an audio track that you want to remove, you might do something like the following:
+
+```js
+// Get the track we created in an earlier example.
+var track = player.audioTracks().getTrackById('my-spanish-audio-track');
+
+// Remove it from the audio track list.
+player.audioTracks().removeTrack(track);
+```
+
 ## API
+For more complete information, refer to the [Video.js API docs](http://docs.videojs.com/docs/api/index.html), specifically:
+
+- `Player#audioTracks`
+- `AudioTrackList`
+- `AudioTrack`
+
 ### `videojs.AudioTrack`
-This class can be used to create new audio track objects. Each property below is available as an option to the `AudioTrack` constructor.
+This class is based on [the `AudioTrack` standard][spec-audiotrack] and can be used to create new audio track objects.
+
+Each property below is available as an option to the `AudioTrack` constructor.
+
+#### `id`
+> [standard definition](https://html.spec.whatwg.org/multipage/embedded-content.html#dom-audiotrack-id)
+
+A unique identifier for this track. Video.js will generate one if not given.
 
 #### `kind`
-One of the audio track types supported by Video.js:
+> [standard definition](https://html.spec.whatwg.org/multipage/embedded-content.html#dom-audiotrack-kind)
+
+Video.js supports standard `kind` values for `AudioTracks`:
 
 - `"alternative"`: A possible alternative to the main track.
 - `"descriptions"`: An audio description of a video track.
@@ -57,24 +86,26 @@ One of the audio track types supported by Video.js:
 - `"main-desc"`: The primary audio track, mixed with audio descriptions.
 - `"translation"`: A translated version of the main audio track.
 - `"commentary"`: Commentary on the primary audio track, e.g. a director's commentary.
-
-Defaults to empty string if `kind` is missing or an invalid `kind` is used.
+- `""` (default): No explicit kind, or the kind given by the track's metadata is not recognized by the user agent.
 
 #### `label`
+> [standard definition](https://html.spec.whatwg.org/multipage/embedded-content.html#dom-audiotrack-label)
+
 The label for the track that will be shown to the user. For example, in a menu that lists the different languages available as alternate audio tracks.
 
 #### `language`
-The valid BCP 47 code for the language of the audio track, e.g. `"en"` for English or `"es"` for Spanish. For supported language translations, please see the [Languages Folder (/lang)](https://github.com/videojs/video.js/tree/master/lang) folder located in the Video.js root.
+> [standard definition](https://html.spec.whatwg.org/multipage/embedded-content.html#dom-audiotrack-language)
+
+The valid [BCP 47](https://tools.ietf.org/html/bcp47) code for the language of the audio track, e.g. `"en"` for English or `"es"` for Spanish.
+
+For supported language translations, please see the [languages folder (/lang)](https://github.com/videojs/video.js/tree/master/lang) folder located in the Video.js root and refer to the [languages guide](./languages.md) for more information on languages in Video.js.
 
 #### `enabled`
-Whether or not this track should be playing. In Video.js, we only allow one track to be enabled at a time; so, if you enable more than one the last one to be enabled will end up being the only one.
+> [standard definition](https://html.spec.whatwg.org/multipage/embedded-content.html#dom-audiotrack-enabled)
+
+Whether or not this track should be playing.
 
-### Player Methods
-#### `player.audioTracks()`
-This is the main interface into the audio tracks of the player. It returns an `AudioTrackList`, which is an array-like object that contains all the `AudioTrack`s associated with the player.
+In Video.js, we only allow one track to be enabled at a time; so, if you enable more than one, the last one to be enabled will end up being the only one. While the spec allows for more than one track to be enabled, Safari and most implementations only allow one audio track to be enabled at a time.
 
-#### `player.audioTracks().addTrack(AudioTrack)`
-Add an `AudioTrack` object to the player's `AudioTrackList`.
 
-#### `player.audioTracks().removeTrack(AudioTrack)`
-Remove an `AudioTrack` from the player's `AudioTrackList`. If the track is not in the `AudioTrackList`, it is simply ignored.
+[spec-audiotrack]: https://html.spec.whatwg.org/multipage/embedded-content.html#audiotrack
diff --git a/docs/guides/text-tracks.md b/docs/guides/text-tracks.md
index bb3922f515..0553a61f5c 100644
--- a/docs/guides/text-tracks.md
+++ b/docs/guides/text-tracks.md
@@ -1,13 +1,20 @@
 # Text Tracks
-Text tracks are a feature of HTML5 video for displaying time-triggered text to the viewer. Video.js offers a cross-browser implementation of audio tracks.
+Text tracks are a feature of HTML5 video for displaying time-triggered text to the viewer. Video.js offers a cross-browser implementation of text tracks.
+
+## A Note on "Remote" Text Tracks
+Video.js refers to so-called "remote" text tracks. This is a convenient term for tracks that have an associated `<track>` element rather than those that do not.
+
+Either can be created programmatically, but _only remote text tracks can be removed from a player._ For that reason, we recommend _only_ using remote text tracks.
 
 ## Creating the Text File
 Timed text requires a text file in [WebVTT](http://dev.w3.org/html5/webvtt/) format. This format defines a list of "cues" that have a start time, an end time, and text to display. [Microsoft has a builder](https://dev.modern.ie/testdrive/demos/captionmaker/) that can help you get started on the file.
 
-When creating captions, there are additional [caption formatting techniques](http://www.theneitherworld.com/mcpoodle/SCC_TOOLS/DOCS/SCC_FORMAT.HTML#style) to make captions more meaningful, like brackets around sound effects (e.g. `[ birds chirping ]`). For a more in depth style guide for captioning, see the [Captioning Key](http://www.dcmp.org/captioningkey/), but keep in mind not all features are supported by WebVTT or (more likely) the Video.js WebVTT implementation.
+> **Note:** When creating captions, there are additional [caption formatting techniques](http://www.theneitherworld.com/mcpoodle/SCC_TOOLS/DOCS/SCC_FORMAT.HTML#style) to make captions more meaningful, like brackets around sound effects (e.g. `[ birds chirping ]`).
+>
+> For a more in depth style guide for captioning, see the [Captioning Key](http://www.dcmp.org/captioningkey/), but keep in mind not all features are supported by WebVTT or (more likely) the Video.js WebVTT implementation.
 
 ## Adding Text Tracks to Video.js
-Once you have your WebVTT file created, you can add it to Video.js using the `<track>` tag. Put your `<track>` tag(s) after all the source elements and before any fallback content.
+Once you have your WebVTT files created, you can add them to your `video` element using the `track` tag. Similar to `source` elements, `track` elements should be added as children of the `video` element:
 
 ```html
 <video
@@ -17,13 +24,44 @@ Once you have your WebVTT file created, you can add it to Video.js using the `<t
   width="640"
   height="264"
   data-setup='{}'>
- <source src="//vjs.zencdn.net/v/oceans.mp4" type="video/mp4">
- <source src="//vjs.zencdn.net/v/oceans.webm" type="video/webm">
- <track kind="captions" src="//example.com/path/to/captions.vtt" srclang="en" label="English" default>
+  <source src="//vjs.zencdn.net/v/oceans.mp4" type="video/mp4">
+  <source src="//vjs.zencdn.net/v/oceans.webm" type="video/webm">
+  <track kind="captions" src="//example.com/path/to/captions.vtt" srclang="en" label="English" default>
 </video>
 ```
 
-You can also add tracks [programmatically](#api).
+Video.js will automatically read `track` elements from the `video` element. Tracks (remote and non-remote) can also be added programmatically.
+
+### `track` Attributes
+#### `kind`
+> [standard definition](https://html.spec.whatwg.org/multipage/embedded-content.html#text-track-kind)
+
+One of the track types supported by Video.js:
+
+- `"subtitles"` (default): Translations of the dialogue in the video for when audio is available but not understood. Subtitles are shown over the video.
+- `"captions"`: Transcription of the dialogue, sound effects, musical cues, and other audio information for viewer who are deaf/hard of hearing, or the video is muted. Captions are also shown over the video.
+- `"chapters"`: Chapter titles that are used to create navigation within the video. Typically, these are in the form of a list of chapters that the viewer can use to navigate the video.
+- `"descriptions"`: Text descriptions of the action in the content for when the video portion isn't available or because the viewer is blind or not using a screen. Descriptions are read by a screen reader or turned into a separate audio track.
+- `"metadata"`: Tracks that have data meant for JavaScript to parse and do something with. These aren't shown to the user.
+
+#### `label`
+> [standard definition](https://html.spec.whatwg.org/multipage/embedded-content.html#text-track-label)
+
+Short descriptive text for the track that will used in the user interface. For example, in a menu for selecting a captions language.
+
+#### `default`
+> [standard definition](https://html.spec.whatwg.org/multipage/embedded-content.html#dom-track-default)
+
+The boolean `default` attribute can be used to indicate that a track's mode should start as `"showing"`. Otherwise, the viewer would need to select their language from a captions or subtitles menu.
+
+> **Note:** For chapters, `default` is required if you want the chapters menu to show.
+
+#### `srclang`
+> [standard definition](https://html.spec.whatwg.org/multipage/embedded-content.html#dom-track-srclang)
+
+The valid [BCP 47](https://tools.ietf.org/html/bcp47) code for the language of the text track, e.g. `"en"` for English or `"es"` for Spanish.
+
+For supported language translations, please see the [languages folder (/lang)](https://github.com/videojs/video.js/tree/master/lang) folder located in the Video.js root and refer to the [languages guide](./languages.md) for more information on languages in Video.js.
 
 ### Text Tracks from Another Domain
 Because Video.js loads the text track file via JavaScript, the [same-origin policy](http://en.wikipedia.org/wiki/Same_origin_policy) applies. If you'd like to have a player served from one domain, but the text track served from another, you'll need to [enable CORS](http://enable-cors.org/) on the server that is serving your text tracks.
@@ -138,64 +176,28 @@ In general, `"descriptions"` tracks are of lower precedence than `"captions"` an
   - For native text tracks, this behavior depends on the browser. Some browsers will allow multiple text tracks, but others will disable all other tracks when a new one is selected.
 
 ## API
-### `videojs.TextTrack`
-This class can be used to create new text track objects. Each property below is available as an option to the `TextTrack` constructor, as a property of the created `TextTrack` object, or as a DOM attribute.
+For more complete information, refer to the [Video.js API docs](http://docs.videojs.com/docs/api/index.html).
 
-#### `kind`
-One of the track types supported by Video.js:
+### Remote Text Tracks
+As mentioned [above](#a-note-on-remote-text-tracks), remote text tracks represent the recommended API offered by Video.js as they can be removed.
 
-- `"subtitles"`: Translations of the dialogue in the video for when audio is available but not understood. Subtitles are shown over the video.
-- `"captions"`: Transcription of the dialogue, sound effects, musical cues, and other audio information for viewer who are deaf/hard of hearing, or the video is muted. Captions are also shown over the video.
-- `"chapters"`: Chapter titles that are used to create navigation within the video. Typically, these are in the form of a list of chapters that the viewer can use to navigate the video.
-- `"descriptions"`: Text descriptions of the action in the content for when the video portion isn't available or because the viewer is blind or not using a screen. Descriptions are read by a screen reader or turned into a separate audio track.
-- `"metadata"`: Tracks that have data meant for JavaScript to parse and do something with. These aren't shown to the user.
-
-Defaults to `"subtitles"`.
-
-#### `label`
-Short descriptive text for the track that will used in the user interface. For example, in a menu for selecting a captions language.
-
-#### `default`
-The boolean `default` attribute can be used to indicate that a track's mode should start as `"showing"`. Otherwise, the viewer would need to select their language from a captions or subtitles menu.
-
-> **Note:** For chapters, `default` is required if you want the chapters menu to show.
-
-#### `srclang`
-The valid BCP 47 code for the language of the text track, e.g. `"en"` for English or `"es"` for Spanish. For supported language translations, please see the [Languages Folder (/lang)](https://github.com/videojs/video.js/tree/master/lang) folder located in the Video.js root.
-
-### Player Methods
-#### `player.textTracks()`
-This is the main interface into the text tracks of a player. It returns a `TextTrackList`, which is an array-like object that contains all the `TextTrack`s associated with the player.
-
-#### `player.remoteTextTracks()`
-This method returns a `TextTrackList` of all the tracks that were created from `<track>` elements or that were added to the player using the `addRemoteTextTrack` method.
-
-These are distinct from the list returned by `textTracks()` because all these tracks are _removeable_, whereas tracks from `textTracks()` are not necessarily removeable.
-
-#### `player.remoteTextTrackEls()`
-This methods returns a `HTMLTrackElementList` of all the `<track>` elements - both emulated and native - associated with the player.
-
-#### `player.addTextTrack(String kind, [String label [, String language]]) -> TextTrack`
-Based on the [W3C spec API](http://www.w3.org/html/wg/drafts/html/master/embedded-content-0.html#dom-media-addtexttrack), this method takes a `kind` and optional `label` and `language` arguments and creates a new `TextTrack`.
-
-> **Note:** This method is intended for _purely programmatic usage_ of tracks and has one important limitation:
->
-> Tracks created using this method _cannot be removed_. The native `addTextTrack` does not have a corresponding `removeTextTrack`; so, we actually discourage the usage of this method.
+- `Player#remoteTextTracks()`
+- `Player#remoteTextTrackEls()`
+- `Player#addRemoteTextTrack(Object options)`
 
-#### `player.addRemoteTextTrack(Object options)`
-This method takes an `options` object that looks pretty similar to the `<track>` element and returns a `HTMLTrackElement` object.
+  Available options are the same as the [available `track` attributes](#track-attributes). And `language` is a supported option as an alias for the `srclang` attribute - either works here.
 
-The `HTMLTrackElement` object has a `track` property on it which is the actual `TextTrack` object. This object is equivalent to the one that can be returned from `addTextTrack()` with the added benefit that it can be removed from the player.
+- `Player#removeRemoteTextTrack(HTMLTrackElement|TextTrack)`
 
-Internally, Video.js will either add a `<track>` element for you or emulate one depending on whether native text tracks are supported or not.
+### Text Tracks
+It is generally recommended that you use _remote_ text tracks rather than these purely programmatic text tracks for the majority of use-cases.
 
-The options available are:
+- `Player#textTracks()`
+- `Player#addTextTrack(String kind, [String label [, String language]])`
 
-- `kind`
-- `label`
-- `language` (also `srclang`)
-- `id`
-- `src`
+  > **Note:** Non-remote text tracks are intended for _purely programmatic usage_ of tracks and have the important limitation that they _cannot be removed once created_.
+  >
+  > The standard `addTextTrack` does **not** have a corresponding `removeTextTrack` method; so, we actually discourage the use of this method!
 
-#### `player.removeRemoteTextTrack(HTMLTrackElement|TextTrack)`
-This method takes either an `HTMLTrackElement` or a `TextTrack` object and removes it from the player.
+- `TextTrackList()`
+- `TextTrack()`
diff --git a/docs/guides/tracks.md b/docs/guides/tracks.md
index 2c3f09ad0c..4cd508b987 100644
--- a/docs/guides/tracks.md
+++ b/docs/guides/tracks.md
@@ -1,15 +1,11 @@
 # Tracks
-
 There are currently three types of tracks:
 
 ## [Audio Tracks](./audio-tracks.md)
-
 Audio tracks allow the selection of alternate audio for a video.
 
 ## [Video Tracks](./video-tracks.md)
-
 Video tracks allow the selection of alternate video content.
 
 ## [Text Tracks](./text-tracks.md)
-
 Text tracks are used to display subtitles and captions and add a menu for navigating between chapters in a video.
diff --git a/docs/guides/video-tracks.md b/docs/guides/video-tracks.md
index bc81992b88..1483bf7318 100644
--- a/docs/guides/video-tracks.md
+++ b/docs/guides/video-tracks.md
@@ -1,9 +1,11 @@
 # Video Tracks
-Video tracks are a feature of HTML5 video for providing alternate video tracks to the user, so they can change type of video they want to watch. Video.js offers a cross-browser implementation of video tracks.
+> **Note:** While video tracks [are a standard][spec-videotrack], there are no compatible implementations at this time. This is an experimental technology!
+
+Video tracks are a feature of HTML5 video for providing alternate video tracks to the user, so they can change the type of video they want to watch. Video.js offers a cross-browser implementation of video tracks.
 
 ## Caveats
-- It is not possible to add video tracks through HTML. They must be added [programmatically](#api).
-- Literal switching of video tracks for playback is not handled by Video.js and must be handled by something else. Video.js only stores the track representation.
+- It is not possible to add video tracks through HTML like you can with text tracks. They must be added programmatically.
+- Video.js only stores track representations. Switching video tracks for playback is _not handled by Video.js_ and must be handled elsewhere.
 
 ## Working with Video Tracks
 ### Add a Video Track to the Player
@@ -13,6 +15,7 @@ var player = videojs('my-player');
 
 // Create a track object.
 var track = new videojs.VideoTrack({
+  id: 'my-alternate-video-track',
   kind: 'commentary',
   label: 'Director\'s Commentary',
   language: 'en'
@@ -22,19 +25,21 @@ var track = new videojs.VideoTrack({
 player.videoTracks().addTrack(track);
 ```
 
-### Listen for a Track Becoming Enabled
-When a new track is enabled (other than the main track) an event is fired on the `VideoTrackList` called `"change"`. You can listen for that event and do something with it.
+### Listen for a Video Track Becoming Enabled
+When a track is enabled or disabled on an `VideoTrackList`, a `change` event will be fired. You can listen for that event and do something with it.
+
+> NOTE: The initial `VideoTrack` selection (usually the main track that is selected) should not fire a `change` event.
 
 ```js
 // Get the current player's VideoTrackList object.
-var tracks = player.videoTracks();
+var videoTrackList = player.videoTracks();
 
 // Listen to the "change" event.
-tracks.addEventListener('change', function() {
+videoTrackList.addEventListener('change', function() {
 
   // Log the currently enabled VideoTrack label.
-  for (var i = 0; i < tracks.length; i++) {
-    var track = tracks[i];
+  for (var i = 0; i < videoTrackList.length; i++) {
+    var track = videoTrackList[i];
 
     if (track.enabled) {
       videojs.log(track.label);
@@ -44,15 +49,38 @@ tracks.addEventListener('change', function() {
 });
 ```
 
+### Removing an Video Track from the Player
+Assuming a player already exists and has an video track that you want to remove, you might do something like the following:
+
+```js
+// Get the track we created in an earlier example.
+var track = player.videoTracks().getTrackById('my-alternate-video-track');
+
+// Remove it from the video track list.
+player.videoTracks().removeTrack(track);
+```
+
 ## API
+For more complete information, refer to the [Video.js API docs](http://docs.videojs.com/docs/api/index.html), specifically:
+
+- `Player#videoTracks`
+- `VideoTrackList`
+- `VideoTrack`
+
 ### `videojs.VideoTrack`
-This class can be used to create new video track objects. Each property below is available as an option to the `VideoTrack` constructor.
+This class is based on [the `VideoTrack` standard][spec-videotrack] and can be used to create new video track objects.
+
+Each property below is available as an option to the `VideoTrack` constructor.
+
+#### `id`
+> [standard definition](https://html.spec.whatwg.org/multipage/embedded-content.html#dom-videotrack-id)
+
+A unique identifier for this track. Video.js will generate one if not given.
 
-## Attributes
-Video Track propertites and settings
+#### `kind`
+> [standard definition](https://html.spec.whatwg.org/multipage/embedded-content.html#dom-videotrack-kind)
 
-### `kind`
-One of the track types supported by Video.js:
+Video.js supports standard `kind` values for `VideoTracks`:
 
 - `"alternative"`: A possible alternative to the main track.
 - `"captions"`: The main video track with burned in captions
@@ -60,24 +88,24 @@ One of the track types supported by Video.js:
 - `"sign"`: The main video track with added sign language overlay.
 - `"subtitles"`: The main video track with burned in subtitles.
 - `"commentary"`: The main video track with burned in commentary.
+- `""` (default): No explicit kind, or the kind given by the track's metadata is not recognized by the user agent.
 
-Defaults to empty string if `kind` is missing or an invalid `kind` is used.
+#### `label`
+> [standard definition](https://html.spec.whatwg.org/multipage/embedded-content.html#dom-videotrack-label)
 
-### `label`
 The label for the track that will be shown to the user. For example, in a menu that lists the different captions available as alternate video tracks.
 
-### `language`
-The valid BCP 47 code for the language of the video track, e.g. `"en"` for English or `"es"` for Spanish. For supported language translations, please see the [Languages Folder (/lang)](https://github.com/videojs/video.js/tree/master/lang) folder located in the Video.js root.
+#### `language`
+> [standard definition](https://html.spec.whatwg.org/multipage/embedded-content.html#dom-videotrack-language)
 
-### `selected`
-Whether or not this track should be playing. Only one video track may be selected at a time.
+The valid [BCP 47](https://tools.ietf.org/html/bcp47) code for the language of the video track, e.g. `"en"` for English or `"es"` for Spanish.
+
+For supported language translations, please see the [languages folder (/lang)](https://github.com/videojs/video.js/tree/master/lang) folder located in the Video.js root and refer to the [languages guide](./languages.md) for more information on languages in Video.js.
 
-### Player Methods
-#### `player.videoTracks()`
-This is the main interface into the video tracks of the player. It returns a `VideoTrackList`, which is an array-like object that contains all the `VideoTrack`s associated with the player.
+#### `selected`
+> [standard definition](https://html.spec.whatwg.org/multipage/embedded-content.html#dom-videotrack-selected)
+
+Whether or not this track should be playing. Only one video track may be selected at a time.
 
-#### `player.videoTracks().addTrack(VideoTrack)`
-Add an `VideoTrack` object to the player's `VideoTrackList`.
 
-#### `player.videoTracks().removeTrack(VideoTrack)`
-Remove an `VideoTrack` from the player's `VideoTrackList`. If the track is not in the `VideoTrackList`, it is simply ignored.
+[spec-videotrack]: https://html.spec.whatwg.org/multipage/embedded-content.html#videotrack

From 79a6c30afd7f72bb52a83cb4440165da20001b43 Mon Sep 17 00:00:00 2001
From: Pat O'Neill <pgoneill@gmail.com>
Date: Thu, 3 Nov 2016 10:36:56 -0400
Subject: [PATCH 14/20] Move removing players to workflows guide

---
 docs/guides/player-workflows.md | 58 +++++++++++++++++++++++++++++++++
 docs/guides/removing-players.md | 41 -----------------------
 docs/guides/setup.md            |  4 +++
 docs/index.md                   |  3 +-
 4 files changed, 64 insertions(+), 42 deletions(-)
 create mode 100644 docs/guides/player-workflows.md
 delete mode 100644 docs/guides/removing-players.md

diff --git a/docs/guides/player-workflows.md b/docs/guides/player-workflows.md
new file mode 100644
index 0000000000..20e0449970
--- /dev/null
+++ b/docs/guides/player-workflows.md
@@ -0,0 +1,58 @@
+# Player Workflows
+
+This document outlines many considerations for using Video.js for advanced player workflows. Be sure to read [the setup guide](setup.md) first!
+
+## Removing Players
+
+No matter the term used for it, web applications are becoming common. Not everything is a static, load-once-and-done web page anymore! This means that developers need to be able to manage the full lifecycle of a video player - from creation to destruction. Video.js supports player removal through the `dispose()` method.
+
+### [`dispose()`](http://docs.videojs.com/docs/api/player.html#Methodsdispose)
+
+This method is available on all Video.js players and [components](http://docs.videojs.com/docs/api/component.html#Methodsdispose). It is _the only_ supported method of removing a Video.js player from both the DOM and memory. For example, the following code sets up a player and then disposes it when media playback is complete:
+
+```js
+var player = videojs('my-player');
+
+player.on('ended', function() {
+  this.dispose();
+});
+```
+
+Calling `dispose()` will have a few effects:
+
+1. Trigger a `"dispose"` event on the player, allowing for any custom cleanup tasks that need to be run by your integration.
+1. Remove all event listeners from the player.
+1. Remove the player's DOM element(s).
+
+Additionally, these actions are recursively applied to _all_ the player's child components.
+
+> **Note**: Do _not_ remove players via standard DOM removal methods: this will leave listeners and other objects in memory that you might not be able to clean up!
+
+### Signs of an Undisposed Player
+
+```
+TypeError: this.el_.vjs_getProperty is not a function
+```
+
+Seeing an error such as the above indicates that a player or component was removed from the DOM without using `dispose()`.
+
+## Showing and Hiding a Player
+
+It is not recommended that you attempt to toggle the visibility or display of a Video.js player. Doing so can be particularly problematic when it comes to the Flash tech. Instead, players should be created and [disposed](#removing-players) as needed.
+
+This is relevant to use cases such as displaying a player in a modal/overlay. Rather than keeping a hidden Video.js player in a DOM element, it's recommended that you create the player when the modal opens and dispose it when the modal closes.
+
+This is particularly relevant where memory/resource usage is concerned (e.g. mobile devices).
+
+Depending on the libraries/frameworks in use, an implementation might look something like this:
+
+```js
+modal.on('show', function() {
+  var videoEl = modal.findEl('video');
+  modal.player = videojs(videoEl);
+});
+
+modal.on('hide', function() {
+  modal.player.dispose();
+});
+```
diff --git a/docs/guides/removing-players.md b/docs/guides/removing-players.md
deleted file mode 100644
index 3cc7b404e4..0000000000
--- a/docs/guides/removing-players.md
+++ /dev/null
@@ -1,41 +0,0 @@
-Removing Players
-================
-
-Sometimes, you want to remove players after page load (in single page apps or modals, for instance). It's easy to manage, but there are some simple rules you need to follow.
-
-Call `.dispose()`
------------------
-
-To remove the html associated with your videojs player from the page always call the player's [`dispose()`](http://docs.videojs.com/docs/api/player.html#Methodsdispose) method:
-
-```js
-var oldPlayer = document.getElementById('my-player');
-videojs(oldPlayer).dispose();
-```
-
-This method will:
-
-  1. reset the internal state of videojs
-  2. remove the player's dom from the page
-
-Showing / Hiding a Player
--------------------------
-
-For instance, if you have a modal that a player appears in, you should create the player when the modal pops up. When the modal hides, dispose the player. If you try to hide the Flash tech, things will go poorly. Even with other tech, calling `dispose()` on a player that's not needed will free up resources for the browser.
-
-Why Is This Needed?
--------------------
-
-VideoJS internally tracks all players and their associated data by html id attribute. If you plan to create new players with the same id as previously created players, you'll need to call the player's dispose() method to clear VideoJS's internal state before creating the new player.
-
-Signs You Did It Wrong
--------------------------
-
-```
-TypeError: this.el_.vjs_getProperty is not a function
-"VIDEOJS:" "Video.js: buffered unavailable on Hls playback technology element." TypeError: this.el_.vjs_getProperty is not a function
-Stack trace:
-...
-```
-
-If you encounter a console error in the browser similar to the above, you've probably forgotten to `dispose()` a player before removing it from the dom. This would happen when using the [contrib-hls](https://github.com/videojs/videojs-contrib-hls) plugin.
diff --git a/docs/guides/setup.md b/docs/guides/setup.md
index 82edd98f0e..79d5d7ce6d 100644
--- a/docs/guides/setup.md
+++ b/docs/guides/setup.md
@@ -176,6 +176,10 @@ player.on('ready', function() {
 
 In each case, the callback is called asynchronously - _even if the player is already ready!_
 
+## Advanced Player Workflows
+
+For a discussion of more advanced player workflows, see the [player workflows guide](player-workflows.md).
+
 
 [boolean-attrs]: https://www.w3.org/TR/2011/WD-html5-20110525/common-microsyntaxes.html#boolean-attributes
 [getting-started]: http://videojs.com/getting-started/
diff --git a/docs/index.md b/docs/index.md
index b069445c1c..c5df3bf8e4 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -10,7 +10,7 @@ Guides explain general topics and use cases (e.g. setup). API docs are automatic
 
 #### [Setup][guides-setup]
 
-The setup guide covers all methods of setting up Video.js players.
+The setup guide covers all methods of setting up Video.js players. After mastering the basics, see the [player workflows guide][guides-workflow].
 
 #### [Options][guides-options]
 
@@ -60,4 +60,5 @@ You can refer to the [full list of API docs][api], but the most relevant API doc
 [guides-text-tracks]: ./guides/text-tracks.md
 [guides-tracks]: ./guides/tracks.md
 [guides-video-tracks]: ./guides/video-tracks.md
+[guides-workflow]: ./guides/player-workflows.md
 [vjs]: http://videojs.com

From 0a6ccbde3cc4b074559f252c98c1c9f328ed8db8 Mon Sep 17 00:00:00 2001
From: Pat O'Neill <pgoneill@gmail.com>
Date: Wed, 30 Nov 2016 16:54:28 -0500
Subject: [PATCH 15/20] Address some comments, add placeholders at bottom

---
 docs/guides/player-workflows.md | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

diff --git a/docs/guides/player-workflows.md b/docs/guides/player-workflows.md
index 20e0449970..777da08933 100644
--- a/docs/guides/player-workflows.md
+++ b/docs/guides/player-workflows.md
@@ -29,12 +29,19 @@ Additionally, these actions are recursively applied to _all_ the player's child
 > **Note**: Do _not_ remove players via standard DOM removal methods: this will leave listeners and other objects in memory that you might not be able to clean up!
 
 ### Signs of an Undisposed Player
+Seeing an error such as:
 
 ```
 TypeError: this.el_.vjs_getProperty is not a function
 ```
 
-Seeing an error such as the above indicates that a player or component was removed from the DOM without using `dispose()`.
+or
+
+```
+TypeError: Cannot read property 'vdata1234567890' of null
+```
+
+Suggests that a player or component was removed from the DOM without using `dispose()`. It usually means something tried to trigger an event on it or call a method on it.
 
 ## Showing and Hiding a Player
 
@@ -56,3 +63,11 @@ modal.on('hide', function() {
   modal.player.dispose();
 });
 ```
+
+## Using Video.js with...
+Coming soon...
+
+### jQuery
+### React
+### Ember
+### Angular

From e71c7a603884fc7e2072be11b16592762ef059b0 Mon Sep 17 00:00:00 2001
From: Pat O'Neill <pgoneill@gmail.com>
Date: Thu, 3 Nov 2016 16:46:11 -0400
Subject: [PATCH 16/20] Mostly complete components doc

---
 docs/guides/components.md | 132 ++++++++++++++++++++++----------------
 1 file changed, 77 insertions(+), 55 deletions(-)

diff --git a/docs/guides/components.md b/docs/guides/components.md
index 944e4c7044..2f3710a551 100644
--- a/docs/guides/components.md
+++ b/docs/guides/components.md
@@ -1,79 +1,90 @@
-Components
-===
-The Video.js player is built on top of a simple, custom UI components architecture. The player class and all control classes inherit from the `Component` class, or a subclass of `Component`.
+# Components
+The architecture of the Video.js player is centered around components. The `Player` class and all classes representing player controls and other UI elements inherit from the `Component` class. This architecture makes it easy to construct the user interface of the Video.js player in a tree-like structure that mirrors the DOM.
+
+## What is a Component?
+A component is a JavaScript object that has the following features:
+
+- An associated DOM element.
+- An association to a `Player` object.
+- The ability to manage any number of child components.
+- The ability to listen for and trigger events.
+- A lifecycle of initialization and disposal.
+
+For more specifics on the programmatic interface of a component, see [the component API docs](http://docs.videojs.com/docs/api/component.html).
+
+## Component Children
+When child component is added to a parent component, Video.js inserts the element of the child into the element of the parent. For example, adding a component like this:
 
 ```js
-videojs.registerComponent('Control', videojs.extend(Component));
-videojs.registerComponent('Button', videojs.extend(videojs.getComponent('Control')));
-videojs.registerComponent('PlayToggle', videojs.extend(videojs.getComponent('Button')));
+// Add a "BigPlayButton" component to the player. Its element will be appended to the player's element.
+player.addChild('BigPlayButton');
 ```
 
-The UI component architecture makes it easier to add child components to a parent component and build up an entire user interface, like the controls for the Video.js player.
+Results in a DOM that looks like this:
 
-```js
-// Adding a new control to the player
-myPlayer.addChild('BigPlayButton');
+```html
+<!-- Player Element -->
+<div class="video-js">
+  <!-- BigPlayButton Element -->
+  <div class="vjs-big-play-button"></div>
+</div>
 ```
 
-Every component has an associated DOM element, and when you add a child component, it inserts the element of that child into the element of the parent.
+Conversely, removing child components will remove the child component's element from the DOM:
 
 ```js
-myPlayer.addChild('BigPlayButton');
+player.removeChild('BigPlayButton');
 ```
 
-Results in:
+Results in a DOM that looks like this:
 
 ```html
-    <!-- Player Element -->
-    <div class="video-js">
-      <!-- BigPlayButton Element -->
-      <div class="vjs-big-play-button"></div>
-    </div>
+<!-- Player Element -->
+<div class="video-js">
+</div>
 ```
 
-The actual default component structure of the Video.js player looks something like this:
+Again, refer to [the component API docs](http://docs.videojs.com/docs/api/component.html) for complete details on methods available for managing component structures.
+
+## Default Component Tree
+The default component structure of the Video.js player looks something like this:
 
 ```
 Player
-    PosterImage
-    TextTrackDisplay
-    LoadingSpinner
-    BigPlayButton
-    ControlBar
-        PlayToggle
-        VolumeMenuButton
-        CurrentTimeDisplay (Hidden by default)
-        TimeDivider (Hidden by default)
-        DurationDisplay (Hidden by default)
-        ProgressControl
-            SeekBar
-              LoadProgressBar
-              MouseTimeDisplay
-              PlayProgressBar
-        LiveDisplay (Hidden by default)
-        RemainingTimeDisplay
-        CustomControlsSpacer (No UI)
-        ChaptersButton (Hidden by default)
-        SubtitlesButton (Hidden by default)
-        CaptionsButton (Hidden by default)
-        FullscreenToggle
-    ErrorDisplay
-    TextTrackSettings
+├── PosterImage
+├── TextTrackDisplay
+├── LoadingSpinner
+├── BigPlayButton
+├─┬ ControlBar
+│ ├── PlayToggle
+│ ├── VolumeMenuButton
+│ ├── CurrentTimeDisplay (hidden by default)
+│ ├── TimeDivider (hidden by default)
+│ ├── DurationDisplay (hidden by default)
+│ ├─┬ ProgressControl (hidden during live playback)
+│ │ └─┬ SeekBar
+│ │   ├── LoadProgressBar
+│ │   ├── MouseTimeDisplay
+│ │   └── PlayProgressBar
+│ ├── LiveDisplay (hidden during VOD playback)
+│ ├── RemainingTimeDisplay
+│ ├── CustomControlSpacer (has no UI)
+│ ├── PlaybackRateMenuButton (hidden, unless playback tech supports rate changes)
+│ ├── ChaptersButton (hidden, unless there are relevant tracks)
+│ ├── DescriptionsButton (hidden, unless there are relevant tracks)
+│ ├── SubtitlesButton (hidden, unless there are relevant tracks)
+│ ├── CaptionsButton (hidden, unless there are relevant tracks)
+│ ├── AudioTrackButton (hidden, unless there are relevant tracks)
+│ └── FullscreenToggle
+├── ErrorDisplay (hidden, until there is an error)
+└── TextTrackSettings
 ```
 
-## Progress Control
-The progress control is made up of the SeekBar. The seekbar contains the load progress bar
-and the play progress bar. In addition, it contains the Mouse Time Display which
-is used to display the time tooltip that follows the mouse cursor.
-The play progress bar also has a time tooltip that show the current time.
+## Specific Component Details
+### Progress Control
+The progress control has a grandchild component, the mouse time display, which shows a time tooltip that follows the mouse cursor.
 
-By default, the progress control is sandwiched between the volume menu button and
-the remaining time display inside the control bar, but in some cases, a skin would
-want to move the progress control above the control bar and have it span the full
-width of the player, in those cases, it is less than ideal to have the tooltips
-get cut off or leave the bounds of the player. This can be prevented by setting the
-`keepTooltipsInside` option on the progress control. This also makes the tooltips use 
-a real element instead of pseudo elements so targetting them with css will be different.
+By default, the progress control is sandwiched inside the control bar between the volume menu button and the remaining time display. Some skins attempt to move the it above the control bar and have it span the full width of the player. In these cases, it is less than ideal to have the tooltips leave the bounds of the player. This can be prevented by setting the `keepTooltipsInside` option on the progress control.
 
 ```js
 let player = videojs('myplayer', {
@@ -84,3 +95,14 @@ let player = videojs('myplayer', {
   }
 });
 ```
+
+> **Note:** This makes the tooltips use a real element instead of pseudo-elements so targeting them with CSS is different.
+
+## Creating a Component
+Video.js components can be inherited and registered with Video.js to add new features and UI to the player. Before diving into an example, there are a couple methods to know about:
+
+- `videojs.getComponent([String name])`: Retrieves component constructors from Video.js.
+- `videojs.registerComponent([String name], [Function component])`: Registers component constructors with Video.js.
+- `videojs.extend([Function component], [Object properties])`: Provides prototype inheritance. Can be used to extend a component's constructor, returning a new constructor with the given properties.
+
+For a working example, [we have a JSBin](http://jsbin.com/vobacas/edit?html,css,js,output) demonstrating the creation of a component for displaying a title across the top of the player.

From ca8e61308b6d78e03d606c449c7a9effc32eac82 Mon Sep 17 00:00:00 2001
From: Pat O'Neill <pgoneill@gmail.com>
Date: Wed, 30 Nov 2016 17:05:57 -0500
Subject: [PATCH 17/20] Minor reorganization

---
 docs/guides/components.md | 21 +++++++++++++--------
 1 file changed, 13 insertions(+), 8 deletions(-)

diff --git a/docs/guides/components.md b/docs/guides/components.md
index 2f3710a551..e9af4defd4 100644
--- a/docs/guides/components.md
+++ b/docs/guides/components.md
@@ -12,6 +12,17 @@ A component is a JavaScript object that has the following features:
 
 For more specifics on the programmatic interface of a component, see [the component API docs](http://docs.videojs.com/docs/api/component.html).
 
+## Creating a Component
+Video.js components can be inherited and registered with Video.js to add new features and UI to the player.
+
+For a working example, [we have a JSBin](http://jsbin.com/vobacas/edit?html,css,js,output) demonstrating the creation of a component for displaying a title across the top of the player.
+
+In addition, there are a couple methods worth recognizing:
+
+- `videojs.getComponent(String name)`: Retrieves component constructors from Video.js.
+- `videojs.registerComponent(String name, Function Comp)`: Registers component constructors with Video.js.
+- `videojs.extend(Function component, Object properties)`: Provides prototype inheritance. Can be used to extend a component's constructor, returning a new constructor with the given properties.
+
 ## Component Children
 When child component is added to a parent component, Video.js inserts the element of the child into the element of the parent. For example, adding a component like this:
 
@@ -98,11 +109,5 @@ let player = videojs('myplayer', {
 
 > **Note:** This makes the tooltips use a real element instead of pseudo-elements so targeting them with CSS is different.
 
-## Creating a Component
-Video.js components can be inherited and registered with Video.js to add new features and UI to the player. Before diving into an example, there are a couple methods to know about:
-
-- `videojs.getComponent([String name])`: Retrieves component constructors from Video.js.
-- `videojs.registerComponent([String name], [Function component])`: Registers component constructors with Video.js.
-- `videojs.extend([Function component], [Object properties])`: Provides prototype inheritance. Can be used to extend a component's constructor, returning a new constructor with the given properties.
-
-For a working example, [we have a JSBin](http://jsbin.com/vobacas/edit?html,css,js,output) demonstrating the creation of a component for displaying a title across the top of the player.
+### Text Track Settings
+The text track settings component is only available when using emulated text tracks.

From 5cfdcad5111e1c55328513081eb9291c1d523147 Mon Sep 17 00:00:00 2001
From: Pat O'Neill <pgoneill@gmail.com>
Date: Tue, 8 Nov 2016 12:40:34 -0500
Subject: [PATCH 18/20] Update languages.md

---
 docs/guides/languages.md | 216 ++++++++++++++++-----------------------
 1 file changed, 89 insertions(+), 127 deletions(-)

diff --git a/docs/guides/languages.md b/docs/guides/languages.md
index d018cf96c0..45a31f0661 100644
--- a/docs/guides/languages.md
+++ b/docs/guides/languages.md
@@ -1,15 +1,21 @@
-Languages
-=========
+# Languages
+Multiple language support allows for users of non-English locales to natively interact with the Video.js player.
 
-Multiple language support allows for users of non-English locales to natively interact with the displayed player. Video.js will compile multiple language files (see below) and instantiate with a global dictionary of language key/value support. Video.js player instances can be created with per-player language support that amends/overrides these default values. Player instances can also hard-set default languages to values other than English as of version 4.7.
+For an up-to-date list of the languages Video.js supports, see the [languages folder (`lang`)][lang-supported]. These JSON files are converted to JavaScript during the Video.js build process.
 
-Creating the Language File
---------------------------
-Video.js uses key/value object dictionaries in JSON form.
+## Using Video.js Languages
+Video.js ships with multiple translations (in `dist/lang/`) in JavaScript files. Each of these files can be included in a web page to provide support for that language in _all_ Video.js players:
 
-An English lang file is at [/lang/en.json](https://github.com/videojs/video.js/tree/master/lang/en.json) which should be used as a template for new files. This will be kept up to date with strings in the core player that need localizations.
+```
+<script src="//example.com/path/to/video.min.js"></script>
+<script src="//example.com/path/to/lang/es.js"></script>
+```
+
+## Contributing to Video.js Translations
+We welcome new translations and improvements to existing ones! Please see the [contributing document](../../CONTRIBUTING.md) to get started contributing to Video.js and continue reading for specifics on how to contribute to translations of Video.js...
 
-A sample dictionary for Spanish `['es']` would look as follows:
+### JSON Format
+Video.js uses a JSON object to describe a language, where the keys are English and the values are the target language. For example, a Spanish translation might look like this:
 
 ```JSON
 {
@@ -18,150 +24,106 @@ A sample dictionary for Spanish `['es']` would look as follows:
   "Current Time": "Tiempo reproducido",
   "Duration Time": "Duración total",
   "Remaining Time": "Tiempo restante",
-  "Stream Type": "Tipo de secuencia",
-  "LIVE": "DIRECTO",
-  "Loaded": "Cargado",
-  "Progress": "Progreso",
-  "Fullscreen": "Pantalla completa",
-  "Non-Fullscreen": "Pantalla no completa",
-  "Mute": "Silenciar",
-  "Unmute": "No silenciado",
-  "Playback Rate": "Velocidad de reproducción",
-  "Subtitles": "Subtítulos",
-  "subtitles off": "Subtítulos desactivados",
-  "Captions": "Subtítulos especiales",
-  "captions off": "Subtítulos especiales desactivados",
-  "Chapters": "Capítulos",
-  "Close Modal Dialog": "Cerca de diálogo modal",
-  "You aborted the video playback": "Ha interrumpido la reproducción del vídeo.",
-  "A network error caused the video download to fail part-way.": "Un error de red ha interrumpido la descarga del vídeo.",
-  "The video could not be loaded, either because the server or network failed or because the format is not supported.": "No se ha podido cargar el vídeo debido a un fallo de red o del servidor o porque el formato es incompatible.",
-  "The video playback was aborted due to a corruption problem or because the video used features your browser did not support.": "La reproducción de vídeo se ha interrumpido por un problema de corrupción de datos o porque el vídeo precisa funciones que su navegador no ofrece.",
-  "No compatible source was found for this video.": "No se ha encontrado ninguna fuente compatible con este vídeo."
+  ...
 }
 ```
 
-Notes:
-
-- The file name should always be in the format `XX.json`, where `XX` is the language code. This should be a two letter code (for options see the bottom of this document) except for cases where a more specific code with sub-code is appropriate, e.g. `zh-CN.lang`.
-- For automatic inclusion at build time, add your language file to the `/lang` directory (see 'Adding Languages to Video.js below').
-
-Adding Languages to Video.js
-----------------------------
-Additional language support can be added to Video.js in multiple ways.
-
-1. Create language scripts out of your JSON objects by using our custom grunt task `vjslanguages`. This task is automatically run as part of the default grunt task in Video.JS, but can be configured to match your `src`/`dist` directories if different. Once these scripts are created, just add them to your DOM like any other script.
-
-NOTE: These need to be added after the core Video.js script.
-
-
-2. Add your JSON objects via the videojs.addLanguage API. Preferably in the HEAD element of your DOM or otherwise prior to player instantiation.
-
-```html
-<head>
-<script>
-  videojs.options.flash.swf = '../node_modules/videojs-swf/dist/video-js.swf';
-  videojs.addLanguage('es', {
-    "Play": "Reproducción",
-    "Pause": "Pausa",
-    "Current Time": "Tiempo reproducido",
-    "Duration Time": "Duración total",
-    "Remaining Time": "Tiempo restante",
-    "Stream Type": "Tipo de secuencia",
-    "LIVE": "DIRECTO",
-    "Loaded": "Cargado",
-    "Progress": "Progreso",
-    "Fullscreen": "Pantalla completa",
-    "Non-Fullscreen": "Pantalla no completa",
-    "Mute": "Silenciar",
-    "Unmute": "No silenciado",
-    "Playback Rate": "Velocidad de reproducción",
-    "Subtitles": "Subtítulos",
-    "subtitles off": "Subtítulos desactivados",
-    "Captions": "Subtítulos especiales",
-    "captions off": "Subtítulos especiales desactivados",
-    "Chapters": "Capítulos",
-    "Close Modal Dialog": "Cerca de diálogo modal",
-    "You aborted the video playback": "Ha interrumpido la reproducción del vídeo.",
-    "A network error caused the video download to fail part-way.": "Un error de red ha interrumpido la descarga del vídeo.",
-    "The video could not be loaded, either because the server or network failed or because the format is not supported.": "No se ha podido cargar el vídeo debido a un fallo de red o del servidor o porque el formato es incompatible.",
-    "The video playback was aborted due to a corruption problem or because the video used features your browser did not support.": "La reproducción de vídeo se ha interrumpido por un problema de corrupción de datos o porque el vídeo precisa funciones que su navegador no ofrece.",
-    "No compatible source was found for this video.": "No se ha encontrado ninguna fuente compatible con este vídeo."
-});
-</script>
-</head>
-```
+### File Naming
+Translations are always found in the `lang/` directory.
+
+Each file's name should be the [standard language code][lang-codes] that is most appropriate. For example, "es" for Spanish or "zh-CN" for Chinese.
 
-3. During a Video.js player instantiation. Adding the languages to the configuration object provided in the `data-setup` attribute.
+Finally, each file's extension is always `.json`.
 
-```html
-<video id="example_video_1" class="video-js vjs-default-skin"
-  controls preload="auto" width="640" height="264"
-  data-setup='{"languages":{"es":{"Play":"Juego"}}}'>
- <source src="http://video-js.zencoder.com/oceans-clip.mp4" type='video/mp4' />
- <source src="http://video-js.zencoder.com/oceans-clip.webm" type='video/webm' />
- <source src="http://video-js.zencoder.com/oceans-clip.ogv" type='video/ogg' />
+### Updating an Existing Translation
 
- <track kind="captions" src="http://example.com/path/to/captions.vtt" srclang="en" label="English" default>
+If there is a [missing translation](../translations-needed.md), mistake, or room for improvement in an existing translation, don't hesitate to open a pull request!
 
-</video>
+1. Edit the relevant JSON file and make the necessary changes.
+1. Verify the language compiles by running `grunt dist`.
+1. Verify the translation appears properly in the player UI.
+1. Run `grunt check-translations` to update the [missing translation document](../translations-needed.md).
+1. Commit and open a pull request on GitHub.
+
+### Writing a New Translation
+The process for writing an entirely new translation is virtually identical to the process for [updating an existing translation](#updating-an-existing-translation) except that the new translation JSON file needs to be created.
+
+The template for new language files is the English file ([lang/en.json][lang-en]). This file is always up-to-date with strings that need translations.
+
+The first step to writing a new translation is to copy the English file:
+
+```sh
+$ cp lang/en.json lang/${NEW_LANG_CODE}.json
 ```
 
-Notes:
-- This will add your language key/values to the Video.js player instances individually. If these values already exist in the global dictionary via the process above, those will be overridden for the player instance in question.
+Otherwise, the process is the same as [updating an existing translation](#updating-an-existing-translation).
 
-Updating default translations
------------------------------
+## Advanced Language Usage
+The instructions above for [using Video.js languages](#using-videojs-languages) should be sufficient for the majority of use-cases. However, languages can be provided at runtime.
 
-A list of the current translations and any strings that need translation are at [docs/translations-needed.md](../translations-needed.md). After updating the language files in /lang/ running `grunt check-languages` will update that list.
+In each case, these custom language definitions _take precedence over any Video.js-provided languages!_
 
-Setting Default Language in a Video.js Player
----------------------------------------------
-During a Video.js player instantiation you can force it to localize to a specific language by including the locale value into the configuration object via the `data-setup` attribute. Valid options listed at the bottom of the page for reference.
+### Adding Languages via the API
+In addition to the stand-alone scripts provided by Video.js, the API supports manual definition of new languages via the `addLanguage` method. It takes two arguments: the [standard language code][lang-codes] and a [language definition object](#json-format).
 
-```html
-<video id="example_video_1" class="video-js vjs-default-skin"
-  controls preload="auto" width="640" height="264"
-  data-setup='{"language":"es"}'>
- <source src="http://video-js.zencoder.com/oceans-clip.mp4" type='video/mp4' />
- <source src="http://video-js.zencoder.com/oceans-clip.webm" type='video/webm' />
- <source src="http://video-js.zencoder.com/oceans-clip.ogv" type='video/ogg' />
+```js
+videojs.addLanguage('es', {
+  'Play': 'Reproducción',
+  'Pause': 'Pausa',
+  'Current Time': 'Tiempo reproducido',
+  'Duration Time': 'Duración total',
+  'Remaining Time': 'Tiempo restante',
+  ...
+});
+```
 
- <track kind="captions" src="http://example.com/path/to/captions.vtt" srclang="en" label="English" default>
+### Per-Player Languages
+In addition to providing languages to Video.js itself, individual `Player` instances can be provided custom language support via [the `languages` option](options.md#languages):
 
-</video>
+```js
+// Provide a custom definition of Spanish to this player.
+videojs('my-player', {
+  languages: {
+    es: {...}
+  }
+});
 ```
 
-Determining Player Language
----------------------------
+### Setting Default Player Language
 
-The player language is set to one of the following in descending priority:
+Player instances can also have a default language via [the `language` option](options.md#language):
+
+```js
+// Set the default language to Spanish for this player.
+videojs('my-player', {
+  language: 'es'
+});
+```
+
+Additionally, the `language` method of the player can be used to set the language after instantiation (e.g., `language('es')`). However, this is not recommended as it does not update the UI in place. _Setting the language via options is always preferred._
 
-* The language specified in setup options as above
-* The language specified by the closet element with a `lang` attribute. This could be the player itself or a parent element. Usually the document language is specified on the `html` tag.
-* Browser language preference (the first language if more than one is configured)
-* 'en'
+### Determining Player Language
 
-The player language can be change after instantiation with `language('fr')`. However localizable text will not be modified by doing this, for best results set the language beforehand.
+The player language is set to one of the following in descending priority:
 
-Language selection
-------------------
+- The language [specified in options](#setting-default-player-language)
+- The language specified by the closest element with a `lang` attribute. This could be the player itself or a parent element. Usually, the document language is specified on the `<html>` tag.
+- Browser language preference; the first language if more than one is configured
+- English
 
-* Language codes are considered case-insensitively (`en-US` == `en-us`).
-* If there is no match for a language code with a subcode (`en-us`), a match for the primary code (`en`) is used if available.
+#### Internal Language Selection
+- Language codes are considered case-insensitively (e.g. `en-US` == `en-us`).
+- If there is no match for a language code with a subcode (e.g. `en-us`), a match for the primary code (e.g. `en`) is used if available.
 
-Localization in Plugins
------------------------
+## References
 
-When you're developing a plugin, you can also introduce new localized strings. Simply wrap the string with the player's `localize` function:
+For information on translation/localization in plugins, see [the plugins guide](plugins.md).
 
-```js
-var details = '<div class="vjs-errors-details">' + player.localize('Technical details') + '</div>';
-```
+Standard languages codes [are defined by the IANA][lang-codes].
 
-Language Codes
---------------
-A list of languages codes can be found [here](http://www.iana.org/assignments/language-subtag-registry/language-subtag-registry)
+For all existing/supported languages, please see the [languages lolder (`lang/`)][lang-supported] folder located in the project root.
 
-For supported language translations, please see the [Languages Folder (/lang)](https://github.com/videojs/video.js/tree/master/lang) folder located in the project root.
 
+[lang-en]: https://github.com/videojs/video.js/tree/master/lang/en.json
+[lang-supported]: https://github.com/videojs/video.js/tree/master/lang
+[lang-codes]: http://www.iana.org/assignments/language-subtag-registry/language-subtag-registry

From e6a964af7fb79793b0460fee402a3aa5fd70c62f Mon Sep 17 00:00:00 2001
From: Pat O'Neill <pgoneill@gmail.com>
Date: Fri, 11 Nov 2016 09:43:13 -0500
Subject: [PATCH 19/20] Minor formatting cleanup

---
 docs/guides/player-workflows.md | 3 ---
 docs/guides/setup.md            | 9 ---------
 2 files changed, 12 deletions(-)

diff --git a/docs/guides/player-workflows.md b/docs/guides/player-workflows.md
index 777da08933..fc7688abe8 100644
--- a/docs/guides/player-workflows.md
+++ b/docs/guides/player-workflows.md
@@ -1,13 +1,10 @@
 # Player Workflows
-
 This document outlines many considerations for using Video.js for advanced player workflows. Be sure to read [the setup guide](setup.md) first!
 
 ## Removing Players
-
 No matter the term used for it, web applications are becoming common. Not everything is a static, load-once-and-done web page anymore! This means that developers need to be able to manage the full lifecycle of a video player - from creation to destruction. Video.js supports player removal through the `dispose()` method.
 
 ### [`dispose()`](http://docs.videojs.com/docs/api/player.html#Methodsdispose)
-
 This method is available on all Video.js players and [components](http://docs.videojs.com/docs/api/component.html#Methodsdispose). It is _the only_ supported method of removing a Video.js player from both the DOM and memory. For example, the following code sets up a player and then disposes it when media playback is complete:
 
 ```js
diff --git a/docs/guides/setup.md b/docs/guides/setup.md
index 79d5d7ce6d..4239dcd842 100644
--- a/docs/guides/setup.md
+++ b/docs/guides/setup.md
@@ -1,5 +1,4 @@
 # Video.js Setup
-
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
@@ -16,7 +15,6 @@
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
 ## Getting Video.js
-
 Video.js is officially available via CDN, npm, and Bower.
 
 Video.js works out of the box with not only HTML `<script>` and `<link>` tags, but also all major bundlers/packagers/builders, such as Browserify, Node, WebPack, etc.
@@ -24,7 +22,6 @@ Video.js works out of the box with not only HTML `<script>` and `<link>` tags, b
 Please refer to the [Getting Started][getting-started] document for details.
 
 ## Creating a Player
-
 > **Note:** Video.js works with `<video>` _and_ `<audio>` elements, but for simplicity we'll refer only to `<video>` elements going forward.
 
 Once you have Video.js [loaded on your page][getting-started], you're ready to create a player!
@@ -41,7 +38,6 @@ Video.js supports all attributes of the `<video>` element (such as `controls`, `
 ```
 
 ### Automatic Setup
-
 By default, when your web page finishes loading, Video.js will scan for media elements that have the `data-setup` attribute. The `data-setup` attribute is used to pass options to Video.js. A minimal example looks like this:
 
 ```html
@@ -54,7 +50,6 @@ By default, when your web page finishes loading, Video.js will scan for media el
 > **Note:** You _must_ use single-quotes with `data-setup` as it is expected to contain JSON.
 
 ### Manual Setup
-
 On the modern web, a `<video>` element often does not exist when the page finishes loading. In these cases, automatic setup is not possible, but manual setup is available via [the `videojs` function][videojs].
 
 One way to call this function is by providing it a string matching a `<video>` element's `id` attribute:
@@ -84,7 +79,6 @@ videojs(document.querySelector('.video-js'));
 ```
 
 ## Options
-
 > **Note:** This guide only covers how to pass options during player setup. For a complete reference on _all_ available options, see the [options guide](options.md).
 
 There are three ways to pass options to Video.js. Because Video.js decorates an HTML5 `<video>` element, many of the options available are also available as [standard `<video>` tag attributes][video-attrs]:
@@ -110,7 +104,6 @@ videojs('my-player', {
 ```
 
 ### Global Defaults
-
 Default options for all players can be found at `videojs.options` and can be changed directly. For example, to set `{autoplay: true}` for all future players:
 
 ```js
@@ -140,7 +133,6 @@ These are correct:
 ```
 
 ## Player Readiness
-
 Because Video.js techs have the potential to be loaded asynchronously, it isn't always safe to interact with a player immediately upon setup. For this reason, Video.js players have a concept of "readiness" which will be familiar to anyone who has used jQuery before.
 
 Essentially, any number of ready callbacks can be defined for a Video.js player. There are three ways to pass these callbacks. In each example, we'll add an identical class to the player:
@@ -177,7 +169,6 @@ player.on('ready', function() {
 In each case, the callback is called asynchronously - _even if the player is already ready!_
 
 ## Advanced Player Workflows
-
 For a discussion of more advanced player workflows, see the [player workflows guide](player-workflows.md).
 
 

From a36b6405f4d3e38d1416ace6db5603a1d8607bea Mon Sep 17 00:00:00 2001
From: Pat O'Neill <pgoneill@gmail.com>
Date: Fri, 11 Nov 2016 10:29:31 -0500
Subject: [PATCH 20/20] Skins guide and icons sandbox example update

---
 docs/guides/skins.md       | 105 ++++++++++++++++++++++---------------
 sandbox/icons.html.example |  32 +++++++++++
 2 files changed, 96 insertions(+), 41 deletions(-)

diff --git a/docs/guides/skins.md b/docs/guides/skins.md
index 2ecdcb47a2..382dd0438d 100644
--- a/docs/guides/skins.md
+++ b/docs/guides/skins.md
@@ -1,54 +1,77 @@
-Skins
-=====
-
-## Base Skin
-The base Video.js skin is made using HTML and CSS (although we use the [Sass preprocessor](http://sass-lang.com)),
-and by default these styles are added to the DOM for you!
-That means you can build a custom skin by simply taking advantage of the cascading aspect of CSS and overriding
-the styles you'd like to change.
-
-If you don't want Video.js to inject the base styles for you, you can disable it by setting `window.VIDEOJS_NO_BASE_THEME = true` before Video.js is loaded.
-Keep in mind that without these base styles enabled, you'll need to manually include them.
-
-Video.js does not currently include the base skin automatically yet, so, this option isn't necessary.
-
-## Default style elements
-Video.js uses a couple of style elements dynamically, specifically, there's a default styles element as well as a player dimensions style element.
-They are used to provide extra default flexiblity with styling the player. However, in some cases, like if a user has the HEAD tag managed by React, users do not want this.
-When `window.VIDEOJS_NO_DYNAMIC_STYLE` is set to `true`, video.js will *not* include these element in the page.
-This means that default dimensions and configured player dimensions will *not* be applied.
-For example, the following player will end up having a width and height of 0 when initialized if `window.VIDEOJS_NO_DYNAMIC_STYLE === true`:
+# Skins
+## Default Skin
+When you include the Video.js CSS file (`video-js.min.css`), the default Video.js skin is applied. That means that customizing the look of a Video.js player is a matter of taking advantage of the cascading aspect of CSS to override styles.
+
+## Additional `<style>` Elements
+In addition to the Video.js CSS file, there are some styles generated automatically by JavaScript and included in the `<head>` as `<style>` elements.
+
+- The `"vjs-styles-defaults"` element sets default dimensions for all Video.js players on the page.
+- A `"vjs-styles-dimensions"` element is created for _each_ player on the page and is used to adjust its size. This styling is handled in this manner to allow you to override it with custom CSS without relying on scripting or `!important` to overcome inline styles.
+
+### Disabling Additional `<style>` Elements
+In some cases, particularly with web applications using frameworks that may manage the `<head>` element (e.g. React, Ember, Angular, etc), these `<style>` elements are not desirable. They can be suppressed by setting `window.VIDEOJS_NO_DYNAMIC_STYLE = true` before including Video.js.
+
+_This disables all CSS-based player sizing. Players will have no `height` or `width` by default!_ Even dimensional attributes, such as `width="600" height="300"` will be _ignored_. When using this global, you will need to set their own dimensions in a way that makes sense for their website or web app.
+
+#### Effect on `Player#width()` and `Player#height()`
+When `VIDEOJS_NO_DYNAMIC_STYLE` is set, `Player#width()` and `Player#height()` will apply any width and height that is set directly to the `<video>` element (or whichever element the current tech uses).
+
+## Icons
+Video.js ships with a number of icons built into the skin via an icon font.
+
+You can view all of the icons available in the default skin by renaming [`sandbox/icons.html.example`](https://github.com/videojs/video.js/blob/master/sandbox/icons.html.example) to `sandbox/icons.html`, building Video.js with `npm run build`, and opening `sandbox/icons.html` in your browser of choice.
+
+## Creating a Skin
+The recommended process for creating a skin is to override the styles provided by the default skin. In this way, you don't need to start from scratch.
+
+### Add a Custom Class to the Player
+The most convenient way to create a hook in the player for your skin is to add a class to it. You can do this by adding a class to the initial `<video>` element:
+
 ```html
-<video width="600" height="300"></video>
+<video class="vjs-matrix video-js">...</video>
 ```
 
-### `Player#width` and `Player#height`
-When `VIDEOJS_NO_DYNAMIC_STYLE` is set, `Player#width` and `Player#height` will apply any width and height
-that is set directly to the video element (or whatever element the current tech uses).
+Or via JavaScript:
 
+```js
+var player = videojs('my-player');
 
-## Icons
+player.addClass('vjs-matrix');
+```
 
-You can view all of the icons available in the base theme by renaming and viewing
-[`icons.html.example`](https://github.com/videojs/video.js/blob/master/sandbox/icons.html.example) in the sandbox directory.
+> **Note:** The `vjs-` prefix is a convention for all classes that are contained in a Video.js player.
 
-## Customization
+### Customize Styles
+The first step in overriding default styles with custom ones is to determine which selectors and properties need overriding. As an example, let's say we don't like the default color of controls (white) and we want to change them to a bright green (say, `#00ff00`).
 
-When you create a new skin, the easiest way to get started is to simply override the base Video.js theme.
-You should include a new class matching the name of your theme, then just start overriding!
+To do this, we'll use your browser's developer tools to inspect the player and figure out which selectors we need to use to adjust those styles - and we'll add our custom `.vjs-matrix` selector to ensure our final selectors are specific enough to override the default skin.
+
+In this case, we'll need the following:
 
 ```css
-.vjs-skin-hotdog-stand { color: #FF0000; }
-.vjs-skin-hotdog-stand .vjs-control-bar { background: #FFFF00; }
-.vjs-skin-hotdog-stand .vjs-play-progress { background: #FF0000; }
+/* Change all text and icon colors in the player. */
+.vjs-matrix.video-js {
+  color: #00ff00;
+}
+
+/* Change the border of the big play button. */
+.vjs-matrix .vjs-big-play-button {
+  border-color: #00ff00;
+}
+
+/* Change the color of various "bars". */
+.vjs-matrix .vjs-volume-level,
+.vjs-matrix .vjs-play-progress,
+.vjs-matrix .vjs-slider-bar {
+  background: #00ff00;
+}
 ```
 
-This would take care of the major areas of the skin (play progress, the control bar background, and icon colors),
-but you can skin any other aspect.
-Our suggestion is to use a browser such as Firefox and Chrome,
-and use the developer tools to inspect the different elements and see what you'd like to change and what classes
-to target when you do so.
+Finally, we can save that as a `videojs-matrix.css` file and include it _after_ the Video.js CSS:
+
+```html
+<link rel="stylesheet" type="text/css" href="path/to/video-js.min.css">
+<link rel="stylesheet" type="text/css" href="path/to/videojs-matrix.css">
+```
 
-More custom skins will be available for download soon.
-If you have one you like you can share it by forking [this example on CodePen.io](http://codepen.io/heff/pen/EarCt),
-and adding a link on the [Skins wiki page](https://github.com/videojs/video.js/wiki/Skins).
+If you create a skin you're particularly proud of, you can share it by adding a link on the [Skins wiki page](https://github.com/videojs/video.js/wiki/Skins). One way to create shareable skins is by forking [this example on CodePen](http://codepen.io/heff/pen/EarCt).
diff --git a/sandbox/icons.html.example b/sandbox/icons.html.example
index 1f2669c7ea..a8a7a9e02e 100644
--- a/sandbox/icons.html.example
+++ b/sandbox/icons.html.example
@@ -33,6 +33,38 @@
     <li><span class="vjs-icon-circle"></span> <code>.vjs-icon-circle</code></li>
     <li><span class="vjs-icon-circle-outline"></span> <code>.vjs-icon-circle-outline</code></li>
     <li><span class="vjs-icon-circle-inner-circle"></span> <code>.vjs-icon-circle-inner-circle</code></li>
+
+          <li><span class="play"></span> <code>.vjs-icon-play</code></li>
+          <li><span class="play-circle"></span> <code>.vjs-icon-play</code></li>
+          <li><span class="pause"></span> <code>.vjs-icon-play</code></li>
+          <li><span class="volume-mute"></span> <code>.vjs-icon-play</code></li>
+          <li><span class="volume-low"></span> <code>.vjs-icon-play</code></li>
+          <li><span class="volume-mid"></span> <code>.vjs-icon-play</code></li>
+          <li><span class="volume-high"></span> <code>.vjs-icon-play</code></li>
+          <li><span class="fullscreen-enter"></span> <code>.vjs-icon-play</code></li>
+          <li><span class="fullscreen-exit"></span> <code>.vjs-icon-play</code></li>
+          <li><span class="square"></span> <code>.vjs-icon-play</code></li>
+          <li><span class="spinner"></span> <code>.vjs-icon-play</code></li>
+          <li><span class="subtitles"></span> <code>.vjs-icon-play</code></li>
+          <li><span class="captions"></span> <code>.vjs-icon-play</code></li>
+          <li><span class="chapters"></span> <code>.vjs-icon-play</code></li>
+          <li><span class="share"></span> <code>.vjs-icon-play</code></li>
+          <li><span class="cog"></span> <code>.vjs-icon-play</code></li>
+          <li><span class="circle"></span> <code>.vjs-icon-play</code></li>
+          <li><span class="circle-outline"></span> <code>.vjs-icon-play</code></li>
+          <li><span class="circle-inner-circle"></span> <code>.vjs-icon-play</code></li>
+          <li><span class="hd"></span> <code>.vjs-icon-play</code></li>
+          <li><span class="cancel"></span> <code>.vjs-icon-play</code></li>
+          <li><span class="replay"></span> <code>.vjs-icon-play</code></li>
+          <li><span class="facebook"></span> <code>.vjs-icon-play</code></li>
+          <li><span class="gplus"></span> <code>.vjs-icon-play</code></li>
+          <li><span class="linkedin"></span> <code>.vjs-icon-play</code></li>
+          <li><span class="twitter"></span> <code>.vjs-icon-play</code></li>
+          <li><span class="tumblr"></span> <code>.vjs-icon-play</code></li>
+          <li><span class="pinterest"></span> <code>.vjs-icon-play</code></li>
+          <li><span class="audio-description"></span> <code>.vjs-icon-play</code></li>
+          <li><span class="audio"></span> <code>.vjs-icon-play</code></li>
+
   </ul>
 </body>
 </html>