web/video.js
1
0
Fork 0
mirror of https://github.com/videojs/video.js.git synced 2024-12-21 01:39:04 +02:00
Code Releases Activity

chore(docs): Documentation Linting and TOC generation (#3841)

Browse Source 
Use remark to lint and generate TOC for markdown files.
This commit is contained in:
Brandon Casey 2016-12-20 16:55:59 -05:00 committed by Gary Katsevman
parent d20e9ce128
commit 0493f54d6f
24 changed files with 982 additions and 440 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.github/ISSUE_TEMPLATE.md vendored
View File

@ -4,7 +4,6 @@ Include a [reduced test case](https://css-tricks.com/reduced-test-cases/), we ha
## Steps to reproduce
Explain in detail the exact steps necessary to reproduce the issue.
1.
2.
3.

1
.github/PULL_REQUEST_TEMPLATE.md vendored
View File

@ -3,7 +3,6 @@ Please describe the change as necessary.
If it's a feature or enhancement please be as detailed as possible.
If it's a bug fix, please link the issue that it fixes or describe the bug in as much detail.
## Specific Changes proposed
Please list the specific changes involved in this pull request.

1
.remarkignore Normal file
View File

@ -0,0 +1 @@
CHANGELOG.md

84
.remarkrc.js Normal file
View File

@ -0,0 +1,84 @@
var remarkrc = {
settings: {
bullet: '*',
fence: '`',
strong: '*',
emphasis: '_',
listItemIndent: 1,
incrementListMarker: false
},
plugins: {
'toc': {
tight: true
},
}
};
var args = process.argv;
// only lint in non-output mode
if (args.indexOf('-o') === -1 && args.indexOf('--output') === -1) {
remarkrc['validate-links'] = {};
remarkrc.plugins.lint = {
'blockquote-indentation': ['error', 2],
'checkbox-character-style': ['warn'],
'checkbox-content-indent': ['error'],
'code-block-style': ['error', 'fenced'],
'definition-case': ['off'],
'definition-spacing': ['error'],
'emphasis-marker': ['error', '_'],
'fenced-code-flag': ['error'],
'fenced-code-marker': ['error', '`'],
'file-extension': ['error'],
'final-definition': ['error'],
'final-newline': ['off'],
'first-heading-level': ['warn', 1],
'hard-break-spaces': ['off'],
'heading-increment': ['error'],
'heading-style': ['error', 'atx'],
'link-title-style': ['warn', '"'],
'list-item-bullet-indent': ['error'],
'list-item-content-indent': ['warn'],
'list-item-indent': ['error', 'space'],
'list-item-spacing': ['off'],
'maximum-heading-length': ['off'],
'maximum-line-length': ['off'],
'no-auto-link-without-protocol': ['error'],
'no-blockquote-without-caret': ['error'],
'no-consecutive-blank-lines': ['error'],
'no-duplicate-definitions': ['error'],
'no-duplicate-headings-in-section': ['error'],
'no-duplicate-headings': ['off'],
'no-emphasis-as-heading': ['error'],
'no-file-name-articles': ['off'],
'no-file-name-consecutive-dashes': ['off'],
'no-file-name-irregular-characters': ['warn', '\\.a-zA-Z0-9-_'],
'no-file-name-mixed-case': ['error'],
'no-file-name-outer-dashes': ['error'],
'no-heading-content-indent': ['error'],
'no-heading-indent': ['error'],
'no-heading-punctuation': ['off'],
'no-html': ['off'],
'no-inline-padding': ['error'],
'no-literal-urls': ['off'],
'no-missing-blank-lines': ['off'],
'no-multiple-toplevel-headings': ['error'],
'no-reference-like-url': ['error'],
'no-shell-dollars': ['error'],
'no-shortcut-reference-iamge': ['off'],
'no-shortcut-reference-link': ['off'],
'no-table-indentation': ['error'],
'no-tabs': ['error'],
'no-undefined-references': ['error'],
'no-unused-definitions': ['error'],
'ordered-list-marker-style': ['error', '.'],
'ordered-list-marker-value': ['error', 'one'],
'rule-style': ['error', '***'],
'strong-marker': ['error', '*'],
'table-cell-padding': ['warn', 'padded'],
'table-cell-alignment': ['warn'],
'table-pipes': ['warn'],
'unordered-list-marker-style': ['warn', '*']
};
}
module.exports = remarkrc;

110
COLLABORATOR_GUIDE.md
View File

@ -1,28 +1,24 @@
# Collaborator Guide
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents**
## Table of Contents
- [Issues and Pull Requests](#issues-and-pull-requests)
- [Accepting changes](#accepting-changes)
- [Involving the TSC](#involving-the-tsc)
- [Landing a PR](#landing-a-pr)
- [Landing a PR manually](#landing-a-pr-manually)
- [Landing a PR manually with several changes](#landing-a-pr-manually-with-several-changes)
- [I just made a mistake](#i-just-made-a-mistake)
- [I accidentally pushed a broken commit or incorrect commit to master](#i-accidentally-pushed-a-broken-commit-or-incorrect-commit-to-master)
- [I lost changes](#i-lost-changes)
- [I accidentally committed a broken change to master](#i-accidentally-committed-a-broken-change-to-master)
- [video.js releases](#videojs-releases)
- [Getting dependencies](#getting-dependencies)
- [Install contrib](#install-contrib)
- [npm access](#npm-access)
- [GitHub personal access token](#github-personal-access-token)
- [Doing a release](#doing-a-release)
- [Doc credit](#doc-credit)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
* [Issues and Pull Requests](#issues-and-pull-requests)
* [Accepting changes](#accepting-changes)
* [Involving the TSC](#involving-the-tsc)
* [Landing a PR](#landing-a-pr)
* [Landing a PR manually](#landing-a-pr-manually)
* [Landing a PR manually with several changes](#landing-a-pr-manually-with-several-changes)
* [I just made a mistake](#i-just-made-a-mistake)
* [I accidentally pushed a broken commit or incorrect commit to master](#i-accidentally-pushed-a-broken-commit-or-incorrect-commit-to-master)
* [I lost changes](#i-lost-changes)
* [I accidentally committed a broken change to master](#i-accidentally-committed-a-broken-change-to-master)
* [video.js releases](#videojs-releases)
* [Getting dependencies](#getting-dependencies)
* [Install contrib](#install-contrib)
* [npm access](#npm-access)
* [GitHub personal access token](#github-personal-access-token)
* [Doing a release](#doing-a-release)
* [Doc credit](#doc-credit)
## Issues and Pull Requests
@ -77,7 +73,7 @@ The footer should contain things like whether this is a breaking change or what
Here's an example:
```
```commit
fix(html5): a regression with html5 tech
This is where you'd explain what the regression is.
@ -90,87 +86,91 @@ Fixes #123
_Optional:_ ensure you're not in a weird rebase or merge state:
```sh
$ git am --abort
$ git rebase --abort
git am --abort
git rebase --abort
```
Checkout and update the master branch:
```sh
$ git checkout master
$ git remote update
$ git rebase upstream/master
git checkout master
git remote update
git rebase upstream/master
```
Check out the PR:
```sh
$ git fetch upstream pull/{{PR Number}}/head:{{name of branch}}
$ git checkout -t {{name of branch}}
git fetch upstream pull/{{PR Number}}/head:{{name of branch}}
git checkout -t {{name of branch}}
```
> For example:
>
> ```sh
> $ git fetch upstream pull/123/head:gkatsev-html5-fix
> $ git checkout -t gkatsev-html5-fix
> git fetch upstream pull/123/head:gkatsev-html5-fix
> git checkout -t gkatsev-html5-fix
> ```
_Optional:_ If necessary, rebase against master. If you have multiple features in the PR, [landing a PR manually with several changes](#landing-a-pr-manually-with-several-changes)
```sh
$ git rebase master
git rebase master
```
Fix up any issues that arise from the rebase, change back to the master branch and squash merge:
```sh
$ git checkout master
$ git merge --squash --no-commit gkatsev-html5-fix
git checkout master
git merge --squash --no-commit gkatsev-html5-fix
```
The `--no-commit` tells git not to make a commit on your behalf. It does stage everything for you, so, you can instead it:
```sh
$ git diff --cached
git diff --cached
```
Now get the author from the original commit:
```sh
$ git log -n 1 --pretty=short gkatsev-html5-fix
git log -n 1 --pretty=short gkatsev-html5-fix
```
Which shows:
```
commit 433c58224f5be34480c8e067ca6c5406ba1c1e9c
Author: Gary Katsevman <git@gkatsev.com>
Update TOC
Which shows:
```txt
commit 433c58224f5be34480c8e067ca6c5406ba1c1e9c
Author: Gary Katsevman <git@gkatsev.com>
Update TOC
```
Now you can commit the change the change with the author, following our commit guidelines
```sh
$ git commit --author "Gary Katsevman <git@gkatsev.com>"
git commit --author "Gary Katsevman <git@gkatsev.com>"
```
Now that it's committed, push to master
```sh
$ git push upstream master
git push upstream master
```
Congratulate yourself for a job well done and the contributor for having his change landed in master.
#### Landing a PR manually with several changes
Follow the same steps as before but when you rebase against master, you want to do an interactive rebase and then squash the changes into just a few commits.
```sh
$ git rebase -i master
git rebase -i master
```
This will give you an output like the following:
```
```txt
pick b4dc15d Update CONTRIBUTING.md with latest info
pick 8592149 Add Dev certificate of origin
pick 259dee6 Add grunt and doctoc npm scripts
@ -201,10 +201,10 @@ pick 433c582 Update TOC
Replace `pick` to `fixup` or `edit` depending on how you want the output to look. You can also re-order the commits, if necessary.
> `fixup` will squash the commit it's infront of up into the commit above it
>
> `edit` will allow you to edit the commit message before continuing
```
```txt
edit b4dc15d Update CONTRIBUTING.md with latest info
fixup 8592149 Add Dev certificate of origin
fixup f12af12 Add conventional-changelog-videojs link
@ -216,17 +216,18 @@ edit 259dee6 Add grunt and doctoc npm scripts
When you get to the edit commits, git will give more information, but you'd want to run ammend the current commit while following our commit guidelines
```sh
$ git commit --amend
git commit --amend
```
After going through and making the commits you want, you want to change back to master and then rebase the branch onto master so we get a clean history
```sh
$ git rebase gkatsev-html5-fix
git rebase gkatsev-html5-fix
```
This will put our two commits into master:
```
```txt
b4dc15d chore(contributing.md): Update CONTRIBUTING.md with latest info <Gary Katsevman>
259dee6 chore(package.json): Add grunt and doctoc npm scripts <Gary Katsevman>
9e20386 v5.12.6 <Gary Katsevman>
@ -253,7 +254,7 @@ This is a great time to discover that something is broken. Because it hasn't bee
To do so, just reset the branch against master.
```sh
$ git reset --hard upstream/master
git reset --hard upstream/master
```
## video.js releases
@ -295,7 +296,7 @@ After generating one, make sure to keep it safe because GitHub will not show the
To do a release, check out the master branch
```sh
$ git checkout master
git checkout master
```
Then run the contrib command to do the next release. Don't forget to provide your GitHub token so the GitHub release goes through.
@ -312,7 +313,8 @@ After it's done, verify that the GitHub release has the correct changelog output
This collaborator guide was heavily inspired by [node.js's guide](https://github.com/nodejs/node/blob/master/COLLABORATOR_GUIDE.md)
[issue template]: /.github/ISSUE_TEMPLATE.md
[pr template]: /.github/PULL_REQUEST_TEMPLATE.md
[conventions]: https://github.com/videojs/conventional-changelog-videojs/blob/master/convention.md

175
CONTRIBUTING.md
View File

@ -2,56 +2,53 @@
So you want to help out? Great! There's a number of ways you can get involved.
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents**
## Table of Contents
- [Other repositories where issues could be filed](#other-repositories-where-issues-could-be-filed)
- [Filing issues](#filing-issues)
- [Reporting a Bug](#reporting-a-bug)
- [Requesting a Feature](#requesting-a-feature)
- [Contributing code](#contributing-code)
- [Building video.js locally](#building-videojs-locally)
- [Forking and cloning the repository](#forking-and-cloning-the-repository)
- [Installing local dependencies](#installing-local-dependencies)
- [Running tests](#running-tests)
- [Building videojs](#building-videojs)
- [Testing Locally](#testing-locally)
- [Sandbox test directory](#sandbox-test-directory)
- [Running a local web server](#running-a-local-web-server)
- [Watching source and test changes](#watching-source-and-test-changes)
- [Making Changes](#making-changes)
- [Step 1: Verify](#step-1-verify)
- [Step 2: Update remote](#step-2-update-remote)
- [Step 3: Branch](#step-3-branch)
- [Step 4: Commit](#step-4-commit)
- [Step 5: Test](#step-5-test)
- [Step 6: Push](#step-6-push)
- [Code Style Guide](#code-style-guide)
- [Developer's Certificate of Origin 1.1](#developers-certificate-of-origin-11)
- [Doc Credit](#doc-credit)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
* [Other repositories where issues could be filed](#other-repositories-where-issues-could-be-filed)
* [Filing issues](#filing-issues)
* [Reporting a Bug](#reporting-a-bug)
* [Requesting a Feature](#requesting-a-feature)
* [Contributing code](#contributing-code)
* [Building video.js locally](#building-videojs-locally)
* [Forking and cloning the repository](#forking-and-cloning-the-repository)
* [Installing local dependencies](#installing-local-dependencies)
* [Running tests](#running-tests)
* [Building videojs](#building-videojs)
* [Testing Locally](#testing-locally)
* [Sandbox test directory](#sandbox-test-directory)
* [Running a local web server](#running-a-local-web-server)
* [Watching source and test changes](#watching-source-and-test-changes)
* [Making Changes](#making-changes)
* [Step 1: Verify](#step-1-verify)
* [Step 2: Update remote](#step-2-update-remote)
* [Step 3: Branch](#step-3-branch)
* [Step 4: Commit](#step-4-commit)
* [Step 5: Test](#step-5-test)
* [Step 6: Push](#step-6-push)
* [Code Style Guide](#code-style-guide)
* [Developer's Certificate of Origin 1.1](#developers-certificate-of-origin-11)
* [Doc Credit](#doc-credit)
## Other repositories where issues could be filed
There's also other Video.js projects where you can help. (check the [video.js org](https://github.com/videojs) for an up-to-date list of projects)
* [Videojs.com](https://github.com/videojs/videojs.com)
* [Video.js flash player](https://github.com/videojs/videojs-flash)
* [HLS](https://github.com/videojs/videojs-contrib-hls)
* [DASH](https://github.com/videojs/videojs-contrib-dash)
* [Youtube Tech](https://github.com/videojs/videojs-youtube)
* [Vimeo Tech](https://github.com/videojs/videojs-vimeo)
* [Ads](https://github.com/videojs/videojs-contrib-ads)
* [Plugin generator](https://github.com/videojs/generator-videojs-plugin)
* [Linter][linter]
* [Videojs.com](https://github.com/videojs/videojs.com)
* [Video.js flash player](https://github.com/videojs/videojs-flash)
* [HLS](https://github.com/videojs/videojs-contrib-hls)
* [DASH](https://github.com/videojs/videojs-contrib-dash)
* [Youtube Tech](https://github.com/videojs/videojs-youtube)
* [Vimeo Tech](https://github.com/videojs/videojs-vimeo)
* [Ads](https://github.com/videojs/videojs-contrib-ads)
* [Plugin generator](https://github.com/videojs/generator-videojs-plugin)
* [Linter][linter]
## Filing issues
[GitHub Issues](https://github.com/videojs/video.js/issues) are used for all discussions around the codebase, including **bugs**, **features**, and other **enhancements**.
When filling out an issue, make sure to fill out the questions in the
When filling out an issue, make sure to fill out the questions in the
### Reporting a Bug
**A bug is a demonstrable problem** that is caused by the code in the repository. Good bug reports are extremely helpful. Thank You!
@ -59,16 +56,11 @@ When filling out an issue, make sure to fill out the questions in the
Guidelines for bug reports:
1. If your issue is with a particular video.js plugin or subproject, please open an issue against that project. See [list of some potential other projects above](#other-repositories-where-issues-could-be-filed)
1. Use the [GitHub issue search](https://github.com/videojs/video.js/issues) &mdash; check if the issue has already been reported.
1. Check if the issue has already been fixed &mdash; try to reproduce it using the latest `master` branch in the repository.
1. Isolate the problem &mdash; **create a [reduced test case](https://css-tricks.com/reduced-test-cases/)** with a live example. You can possibly use [this JSBin example](http://jsbin.com/axedog/edit) as a starting point -- don't forget to update it to the videojs version you use.
1. Use the [GitHub issue search](https://github.com/videojs/video.js/issues) — check if the issue has already been reported.
1. Check if the issue has already been fixed — try to reproduce it using the latest `master` branch in the repository.
1. Isolate the problem — **create a [reduced test case](https://css-tricks.com/reduced-test-cases/)** with a live example. You can possibly use [this JSBin example](http://jsbin.com/axedog/edit) as a starting point -- don't forget to update it to the videojs version you use.
1. Answer all questions in the [issue template][]. The questions in the issue template are designed to try and provide the maintainers with as much information possible to minimize back-and-forth to get the issue resolved.
A good bug report should be as detailed as possible, so that others won't have to follow up for the essential details.
**[File a bug report](https://github.com/videojs/video.js/issues/new)**
@ -76,12 +68,9 @@ A good bug report should be as detailed as possible, so that others won't have t
### Requesting a Feature
1. [Check the plugin list](http://videojs.com/plugins/) for any plugins that may already support the feature.
2. [Search the issues](https://github.com/videojs/video.js/issues) for any previous requests for the same feature, and give a thumbs up or +1 on existing requests.
2. If no previous requests exist, create a new issue. Please be as clear as possible about why the feautre is needed and the intended use case.
3. Once again, be as details as possible and follow the [issue template][]
1. [Search the issues](https://github.com/videojs/video.js/issues) for any previous requests for the same feature, and give a thumbs up or +1 on existing requests.
1. If no previous requests exist, create a new issue. Please be as clear as possible about why the feautre is needed and the intended use case.
1. Once again, be as details as possible and follow the [issue template][]
**[Request a feature](https://github.com/videojs/video.js/issues/new)**
@ -89,17 +78,18 @@ A good bug report should be as detailed as possible, so that others won't have t
To contibute code you'll need to be able to build a copy of Video.js and run tests locally. There are a few requirements before getting started.
- Node.js
Video.js uses Node for build and test automation. Node is available for Windows, Mac OS X, Linux, and SunOS, as well as source code if that doesn't scare you. [Download and install Node.js](http://nodejs.org/download/)
* Node.js
Video.js uses Node for build and test automation. Node is available for Windows, Mac OS X, Linux, and SunOS, as well as source code if that doesn't scare you. [Download and install Node.js](http://nodejs.org/download/)
* `grunt-cli`
Optionally, install `grunt-cli` globally to use grunt directly. It can always be run via an npm script:
- `grunt-cli`
Optionally, install `grunt-cli` globally to use grunt directly. It can always be run via an npm script:
```sh
$ npm run grunt
npm run grunt
```
```sh
$ npm install -g grunt-cli
npm install -g grunt-cli
```
Depending on how you have node and npm set up, you may need to run the global install (`-g`) as a superuser by prepending `sudo`.
@ -113,27 +103,27 @@ First, [fork](http://help.github.com/fork-a-repo/) the video.js git repository.
Clone your fork of the repo into your code directory
```sh
$ git clone https://github.com/<your-username>/video.js.git
git clone https://github.com/<your-username>/video.js.git
```
Navigate to the newly cloned directory
```sh
$ cd video.js
cd video.js
```
Assign the original repo to a remote called "upstream"
```
```sh
git remote add upstream https://github.com/videojs/video.js.git
```
> In the future, if you want to pull in updates to video.js that happened after you cloned the main repo, you can run:
>
> ```sh
> $ git remote update
> $ git checkout master
> $ git pull upstream master
> git remote update
> git checkout master
> git pull upstream master
> ```
#### Installing local dependencies
@ -141,7 +131,7 @@ git remote add upstream https://github.com/videojs/video.js.git
Install the required node.js modules using node package manager
```sh
$ npm install
npm install
```
> A note to Windows developers: If you run npm commands, and you find that your command prompt colors have suddenly reversed, you can configure npm to set color to false to prevent this from happening.
@ -153,7 +143,7 @@ $ npm install
To run the tests all you need to do is run
```sh
$ npm test
npm test
```
This will build video.js locally and run the tests using [Karma](https://karma-runner.github.io/1.0/index.html) which runs our tests in actual browsers.
@ -163,12 +153,11 @@ This will build video.js locally and run the tests using [Karma](https://karma-r
To build video.js, simply run
```sh
$ npm run build
npm run build
```
This outputs an `es5/` and `dist/` folder. The `es5/` folder is used by bundling tools like browserify and webpack to package video.js into projects. The `dist/` folder has pre-compiled versions of video.js, including a minified version and the CSS file. This file can be included in page via a `<script></script>` tag.
#### Testing Locally
Besides running automated tests, you often want to run video.js manually and play around with things as you're developing. A few things are provided to make it easier.
@ -178,7 +167,7 @@ Besides running automated tests, you often want to run video.js manually and pla
There's a sandbox directory where you can add any file and it won't get tracked in git. To start you can copy the example index file.
```sh
$ cp sandbox/index.html.example sandbox/index.html
cp sandbox/index.html.example sandbox/index.html
```
See [the following section](#running-a-local-web-server) for how to open the page in a browser.
@ -193,22 +182,27 @@ This ties in nicely with the sandbox directory. You can always open the `sandbox
To run the local webserver, you can run it in a couple of ways.
```sh
$ grunt connect
$ open http://localhost:9999/sandbox/index.html
grunt connect
open http://localhost:9999/sandbox/index.html
```
or
```sh
$ npm start
npm start
```
The latter does some extra work which will be described in the [next section]
The latter does some extra work which will be described in the next section.
#### Watching source and test changes
As you're developing, you want the build to re-run and update itself, and potentially re-run the tests. In addition, you want to launch a local web-server that you can open the `sandbox` directory in.
To do so, you just need to run
```sh
$ npm start
npm start
```
This sets up the local webserver using connect and then watches source files, test files, and CSS files for you and rebuilds things as they happen.
### Making Changes
@ -222,9 +216,9 @@ Whether you're adding something new, making something better, or fixing a bug, y
Before starting work, you want to update your local repository to have all the latest changes.
```sh
$ git remote update
$ git checkout master
$ git rebase upstream/master
git remote update
git checkout master
git rebase upstream/master
```
#### Step 3: Branch
@ -232,10 +226,11 @@ $ git rebase upstream/master
You want to do your work in a separate branch.
```sh
$ git checkout -b my-branch
git checkout -b my-branch
```
#### Step 4: Commit
Commit changes as you go. Write thorough descriptions of your changes in your commit messages.
For more information see our [conventional changelog guidelines for video.js](https://github.com/videojs/conventional-changelog-videojs/blob/master/convention.md)
Follow these guidelines:
@ -245,13 +240,16 @@ Follow these guidelines:
1. A footer can be added if this fixes a particular issue on GitHub.
```sh
$ git add src/js/player.js
$ git commit
git add src/js/player.js
git commit
```
An example commit message:
An example of the first line of a commit message: `fix: changed the footer to correctly display foo`
```
In the body of the commit message, we can talk about why we made the change. What the change entails.
Any testing considerations or things to think about when looking at the commit. For Example:
```txt
fix: one line commit explanation
In the body of the commit message, we can talk about why we made the change. What the change entails.
@ -264,8 +262,8 @@ Fixes #123. The footer can contain Fixes messages.
> Make sure that git knows your name and email:
>
> ```sh
> $ git config --global user.name "Random User"
> $ git config --global user.email "random.user@example.com"
> git config --global user.name "Random User"
> git config --global user.email "random.user@example.com"
> ```
#### Step 5: Test
@ -274,13 +272,13 @@ Any code change should come with corresponding test changes. Especially bug fixe
Tests attached to bug fixes should fail before the change and succeed with it.
```sh
$ npm test
npm test
```
#### Step 6: Push
```sh
$ git push origin my-branch
git push origin my-branch
```
Then go to the [repo page](http://github.com/videojs/video.js) and click the "Pull Request" button and fill out the [pull request template](/.github/PULL_REQUEST_TEMPLATE.md)
@ -315,8 +313,8 @@ By making a contribution to this project, I certify that:
maintained indefinitely and may be redistributed consistent with
this project or the open source license(s) involved.
## Doc Credit
This doc was inspired by some great contribution guide examples including [contribute.md template](https://github.com/contribute-md/contribute-md-template),
[grunt](https://github.com/gruntjs/grunt/wiki/Contributing),
[html5 boilerplate](https://github.com/h5bp/html5-boilerplate/blob/master/CONTRIBUTING.md),
@ -324,4 +322,5 @@ This doc was inspired by some great contribution guide examples including [contr
and [node.js](https://github.com/nodejs/node/blob/master/CONTRIBUTING.md).
[issue template]: /.github/ISSUE_TEMPLATE.md
[linter]: https://github.com/videojs/standard

25
README.md
View File

@ -83,25 +83,40 @@ _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
[builtwith]: 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
[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
[options]: docs/guides/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

92
docs/guides/audio-tracks.md
View File

@ -1,12 +1,37 @@
# 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 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.
## Table of Contents
* [Caveats](#caveats)
* [Working with Audio Tracks](#working-with-audio-tracks)
* [Add an Audio Track to the Player](#add-an-audio-track-to-the-player)
* [Listen for a Video Track Becoming Enabled](#listen-for-a-video-track-becoming-enabled)
* [Removing an Audio Track from the Player](#removing-an-audio-track-from-the-player)
* [API](#api)
* [videojs.AudioTrack](#videojsaudiotrack)
* [id](#id)
* [kind](#kind)
* [label](#label)
* [language](#language)
* [enabled](#enabled)
## Caveats
- 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.
* 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](http://github.com/videojs/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
```js
// Create a player.
var player = videojs('my-player');
@ -24,9 +49,12 @@ player.audioTracks().addTrack(track);
```
### 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.
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.
@ -48,7 +76,9 @@ audioTrackList.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:
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.
@ -59,53 +89,69 @@ 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`
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 is based on [the `AudioTrack` standard][spec-audiotrack] and can be used to create new audio track objects.
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`
> [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.
- `"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.
- `""` (default): No explicit kind, or the kind given by the track's metadata is not recognized by the user agent.
* `"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.
* `""` (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.
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`
> [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.
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.
For supported language translations, please see the [languages folder (/lang)](https://github.com/videojs/video.js/tree/master/lang)
located in the Video.js root and refer to the [languages guide](languages.md) for more
information on languages in Video.js.
#### `enabled`
> [standard definition](https://html.spec.whatwg.org/multipage/embedded-content.html#dom-audiotrack-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. 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.
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.
[spec-audiotrack]: https://html.spec.whatwg.org/multipage/embedded-content.html#audiotrack

36
docs/guides/components.md
View File

@ -1,29 +1,43 @@
# 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.
## Table of Contents
* [What is a Component?](#what-is-a-component)
* [Creating a Component](#creating-a-component)
* [Component Children](#component-children)
* [Default Component Tree](#default-component-tree)
* [Specific Component Details](#specific-component-details)
* [Progress Control](#progress-control)
* [Text Track Settings](#text-track-settings)
## 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.
* 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).
## 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.
* `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:
```js
@ -58,9 +72,10 @@ Results in a DOM that looks 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:
```
```tree
Player
├── PosterImage
├── TextTrackDisplay
@ -92,7 +107,9 @@ Player
```
## 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 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.
@ -110,4 +127,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.
### Text Track Settings
The text track settings component is only available when using emulated text tracks.

141
docs/guides/faq.md
View File

@ -1,73 +1,123 @@
# FAQ
## Table of Contents
* [Q: What is video.js?](#q-what-is-videojs)
* [Q: How do I install video.js?](#q-how-do-i-install-videojs)
* [Q: Is video.js on bower?](#q-is-videojs-on-bower)
* [Q: What do video.js version numbers mean?](#q-what-do-videojs-version-numbers-mean)
* [Q: How can I troubleshoot playback issues?](#q-how-can-i-troubleshoot-playback-issues)
* [Q: A video does not play in a specific browser. Why?](#q-a-video-does-not-play-in-a-specific-browser-why)
* [Q: Why does the entire video download before playback? Why does the video load for a long time?](#q-why-does-the-entire-video-download-before-playback-why-does-the-video-load-for-a-long-time)
* [Q: I see an error thrown that mentions vdata12345. What is that?](#q-i-see-an-error-thrown-that-mentions-vdata12345-what-is-that)
* [Q: I think I found a bug with video.js or I want to add a feature. What should I do?](#q-i-think-i-found-a-bug-with-videojs-or-i-want-to-add-a-feature-what-should-i-do)
* [if you think that you can fix the issue or add the feature](#if-you-think-that-you-can-fix-the-issue-or-add-the-feature)
* [If you don't think you can fix the issue or add the feature](#if-you-dont-think-you-can-fix-the-issue-or-add-the-feature)
* [Q: What is a reduced test case?](#q-what-is-a-reduced-test-case)
* [Q: What media formats does video.js support?](#q-what-media-formats-does-videojs-support)
* [Q: How can I hide the links to my video/subtitles/audio/tracks?](#q-how-can-i-hide-the-links-to-my-videosubtitlesaudiotracks)
* [Q: What is a plugin?](#q-what-is-a-plugin)
* [Q: How do I make a plugin for video.js?](#q-how-do-i-make-a-plugin-for-videojs)
* [Q: Where can I find a list of video.js plugins?](#q-where-can-i-find-a-list-of-videojs-plugins)
* [Q: How can I get my plugin listed on the website?](#q-how-can-i-get-my-plugin-listed-on-the-website)
* [Q: Where can I find a list of video.js skins?](#q-where-can-i-find-a-list-of-videojs-skins)
* [Q: Does video.js work as an audio only player?](#q-does-videojs-work-as-an-audio-only-player)
* [Q: Does video.js support audio tracks?](#q-does-videojs-support-audio-tracks)
* [Q: Does video.js support video tracks?](#q-does-videojs-support-video-tracks)
* [Q: Does video.js support text tracks (captions, subtitles, etc)?](#q-does-videojs-support-text-tracks-captions-subtitles-etc)
* [Q: Does video.js support HLS (HTTP Live streaming) video?](#q-does-videojs-support-hls-http-live-streaming-video)
* [Q: Does video.js support MPEG Dash video?](#q-does-videojs-support-mpeg-dash-video)
* [Q: Does video.js support live video?](#q-does-videojs-support-live-video)
* [Q: Can video.js wrap around YouTube videos?](#q-can-videojs-wrap-around-youtube-videos)
* [Q: Can video.js wrap around Vimeo videos?](#q-can-videojs-wrap-around-vimeo-videos)
* [Q: Does video.js support DRM video?](#q-does-videojs-support-drm-video)
* [Q: Does video.js have any support for advertisement integrations?](#q-does-videojs-have-any-support-for-advertisement-integrations)
* [Q: Can video.js be required in node.js?](#q-can-videojs-be-required-in-nodejs)
* [Q: Does video.js work with webpack?](#q-does-videojs-work-with-webpack)
## Q: What is video.js?
video.js is an extendable framework/library around the native video element. It does the following:
* Offers a plugin API so that different types of video can be handed to the native
video element (e.g. HLS, Flash, HTML5 video, etc).
* Unifies the native video api across browsers (polyfilling support for features
if necessary)
* Offers an extendable and themable UI
* Takes care of accessibility for the user (in-progress)
* Has a set of core plugins that offer support for tons of additional video formats.
* [videojs-contrib-hls][hls]
* [videojs-contrib-dash][dash]
* Support for DRM video via a core plugin
* [videojs-contrib-eme][eme]
* Lots of plugins which offer support for all kinds of features. See the [plugin list on videojs.com][plugin-list]
* Offers a plugin API so that different types of video can be handed to the native
video element (e.g. HLS, Flash, HTML5 video, etc).
* Unifies the native video api across browsers (polyfilling support for features
if necessary)
* Offers an extendable and themable UI
* Takes care of accessibility for the user (in-progress)
* Has a set of core plugins that offer support for tons of additional video formats.
* [videojs-contrib-hls][hls]
* [videojs-contrib-dash][dash]
* Support for DRM video via a core plugin
* [videojs-contrib-eme][eme]
* Lots of plugins which offer support for all kinds of features. See the [plugin list on videojs.com][plugin-list]
## Q: How do I install video.js?
Currently video.js can be installed using bower, npm, serving a release file from
a github tag, or even using a CDN hosted version. For information on doing any of those
see the [install guide][install-guide].
## Q: Is video.js on bower?
Yes! See the [install guide][install-guide] for more information.
## Q: What do video.js version numbers mean?
video.js follows [semver][semver] which means that the API should not change
out from under a user unless there is a major version increase.
## Q: How can I troubleshoot playback issues?
See the [troubleshooting guide][troubleshooting]. If troubleshooting does not
solve your issue, please submit a [pull request or an issue][pr-issue-question].
## Q: A video does not play in a specific browser. Why?
See the [troubleshooting guide][troubleshooting]. If troubleshooting does not
solve your issue, please submit a [pull request or an issue][pr-issue-question].
## Q: Why does the entire video download before playback? Why does the video load for a long time?
See the [troubleshooting guide][troubleshooting]. If troubleshooting does not
solve your issue, please submit a [pull request or an issue][pr-issue-question].
## Q: I see an error thrown that mentions `vdata12345`. What is that?
See the [troubleshooting guide][troubleshooting]. If troubleshooting does not
solve your issue, please submit a [pull request or an issue][pr-issue-question].
## Q: I think I found a bug with video.js or I want to add a feature. What should I do?
### if you think that you can fix the issue or add the feature
Submit a pull request to the [video.js repo][vjs-prs].
Make sure to follow the [contributing guide][contributing-prs] and
the [pull request template][pr-template].
### If you don't think you can fix the issue or add the feature
Open an [issue on the video.js repo][vjs-issues]. Make
sure that you follow the [issue template][issue-template] and the
[contributing guide][contributing-issues] so that we can better assist you
with your issue.
## Q: What is a reduced test case?
A reduced test case is an example of the problem that you are facing in isolation.
Think of it as example page that reproduces the issue in the least amount of possible code.
We have a [starter example][starter-example] for reduced test cases. To learn more
about reduced test cases visit: https://css-tricks.com/reduced-test-cases/
about reduced test cases visit [css-tricks](https://css-tricks.com/reduced-test-cases/)
## Q: What media formats does video.js support?
This depends on the formats supported by the browser's HTML5 video element, and the playback
techs made available to video.js. For example, video.js 5 includes the Flash tech by default which
enables the playback of FLV video where the Flash plugin is available. For more information
on media formats see the [troubleshooting guide][troubleshooting].
## Q: How can I hide the links to my video/subtitles/audio/tracks?
It's impossible to hide the network requests a browser makes and difficult to
sufficiently obfuscate URLs in the source. Techniques such as token authentication may
help but are outside of the scope of video.js.
@ -75,11 +125,13 @@ help but are outside of the scope of video.js.
For content that must be highly secure [videojs-contrib-eme][eme] adds DRM support.
## Q: What is a plugin?
A plugin is a group of reusable functionality that can be re-used by others. For instance a plugin could add
a button to video.js that makes the video replay 10 times in a row before it stops playback for good. If such
a plugin existed and was published users could include it on their page to share that functionality.
## Q: How do I make a plugin for video.js?
See the [plugin guide][plugin-guide] for information on making a plugin for video.js.
<!-- TODO: Once these is a button guide, add this back in
@ -88,92 +140,125 @@ See the [button guide][button-guide] for information on adding a button to video
-->
## Q: Where can I find a list of video.js plugins?
The official [list of plugins on videojs.com][plugin-list].
## Q: How can I get my plugin listed on the website?
Add the 'videojs-plugin' [keyword to your array in package.json][npm-keywords]
and publish your package to npm. If you use the [plugin generator][generator] this will be done automatically for you. See
the [plugins guide][plugin-guide] for more information.
## Q: Where can I find a list of video.js skins?
See the [video.js github wiki][skins-list].
## Q: Does video.js work as an audio only player?
Yes! It can be used to play audio only files in a `<video>` or `<audio>` tag. The
difference being that the `<audio>` tag will not have a blank display area and the `<video>`
tag will. Note that audio only will not work with the Flash playback tech.
## Q: Does video.js support audio tracks?
Yes! See the [audio tracks guide][audio-tracks] for information on using audio tracks.
## Q: Does video.js support video tracks?
The code for video tracks exists but it has not been tested. See the [video tracks guide][video-tracks]
for more information on using video tracks.
## Q: Does video.js support text tracks (captions, subtitles, etc)?
Yes! See the [text tracks guide][text-tracks] for information on using text tracks.
## Q: Does video.js support HLS (HTTP Live streaming) video?
video.js supports HLS video if the native HTML5 element supports HLS (e.g. Safari, Edge,
Chrome for Android, and iOS). For browsers without native support see the [videojs-contrib-hls][hls]
project which adds support.
## Q: Does video.js support MPEG Dash video?
video.js itself does not support MPEG DASH, however an offical project called [videojs-contrib-dash][dash]
adds support for MPEG DASH video.
## Q: Does video.js support live video?
Yes! Video.js adds support for live videos via the Flash tech which supports RTMP streams.
The official HLS tech, [videojs-contrib-hls][hls], will add support for live HLS video
if you add it to your page with video.js.
## Q: Can video.js wrap around YouTube videos?
No. There is an official plugin that adds support. It is called [videojs-youtube][youtube].
## Q: Can video.js wrap around Vimeo videos?
No. There is an official plugin that adds support. It is called [videojs-vimeo][vimeo].
## Q: Does video.js support DRM video?
No. There is an official plugin that adds support. It is called [videojs-contrib-eme][eme].
## Q: Does video.js have any support for advertisement integrations?
No. There is an official plugin that adds support. It is called [videojs-contrib-ads][ads].
## Q: Can video.js be required in node.js?
Yes! Please [submit an issue or open a pull request][pr-issue-question] if this does not work.
## Q: Does video.js work with webpack?
Yes! Please [submit an issue or open a pull request][pr-issue-question] if this does not work.
<!-- guides -->
[plugin-guide]: /docs/guides/plugins.md
[install-guide]: http://videojs.com/getting-started/
[troubleshooting]: /docs/guides/troubleshooting.md
[video-tracks]: /docs/guides/video-tracks.md
[audio-tracks]: /docs/guides/audio-tracks.md
[text-tracks]: /docs/guides/text-tracks.md
[pr-issue-question]: /docs/guides/faq.md#q-i-think-i-found-a-bug-with-videojs-or-i-want-to-add-a-feature-what-should-i-do
[plugin-guide]: plugins.md
[install-guide]: http://videojs.com/getting-started/
[troubleshooting]: troubleshooting.md
[video-tracks]: video-tracks.md
[audio-tracks]: audio-tracks.md
[text-tracks]: text-tracks.md
[pr-issue-question]: #q-i-think-i-found-a-bug-with-videojs-or-i-want-to-add-a-feature-what-should-i-do
<!-- official projects -->
[hls]: http://github.com/videojs/videojs-contrib-hls
[dash]: http://github.com/videojs/videojs-contrib-dash
[eme]: https://github.com/videojs/videojs-contrib-eme
[generator]: https://github.com/videojs/generator-videojs-plugin
[youtube]: https://github.com/videojs/videojs-youtube
[vimeo]: https://github.com/videojs/videojs-vimeo
[ads]: https://github.com/videojs/videojs-contrib-ads
<!-- website/github -->
[pr-template]: /.github/PULL_REQUEST_TEMPATLE.md
[issue-template]: /.github/ISSUE_TEMPLATE.md
[pr-template]: http://github.com/videojs/video.js/blob/master/.github/PULL_REQUEST_TEMPLATE.md
[issue-template]: http://github.com/videojs/video.js/blob/master/.github/ISSUE_TEMPLATE.md
[plugin-list]: http://videojs.com/plugins
[skins-list]: https://github.com/videojs/video.js/wiki/Skins
[contributing-issues]: /CONTRIBUTING.md#filing-issues
[contributing-prs]: /CONTRIBUTING.md#contributing-code
[contributing-issues]: http://github.com/videojs/video.js/blob/master/CONTRIBUTING.md#filing-issues
[contributing-prs]: http://github.com/videojs/video.js/blob/master/CONTRIBUTING.md#contributing-code
[vjs-issues]: https://github.com/videojs/video.js/issues
[vjs-prs]: https://github.com/videojs/video.js/pulls
<!-- external -->
[npm-keywords]: https://docs.npmjs.com/files/package.json#keywords
[semver]: http://semver.org/
[starter-example]: http://jsbin.com/axedog/edit?html,output

106
docs/guides/hooks.md
View File

@ -1,55 +1,74 @@
# Hooks
Hooks exist so that users can "hook" on to certain video.js player lifecycle
## Table of Contents
* [Current Hooks](#current-hooks)
* [beforesetup](#beforesetup)
* [setup](#setup)
* [Usage](#usage)
* [Adding](#adding)
* [Getting](#getting)
* [Removing](#removing)
## Current Hooks
Currently, the following hooks are avialable:
### beforesetup
`beforesetup` is called just before the player is created. This allows:
* modification of the options passed to the video.js function (`videojs('some-id, options)`)
* modification of the dom video element that will be used for the player
`beforesetup` hook functions should:
* take two arguments
1. videoEl: dom video element that video.js is going to use to create a player
2. options: options that video.js was intialized with and will later pass to the player during creation
1. videoEl: dom video element that video.js is going to use to create a player
1. options: options that video.js was intialized with and will later pass to the player during creation
* return options that will merge and override options that video.js with intialized with
Example: adding beforesetup hook
```js
var beforeSetup = function(videoEl, options) {
// videoEl.id will be some-id here, since that is what video.js
// was created with
var beforeSetup = function(videoEl, options) {
// videoEl.id will be some-id here, since that is what video.js
// was created with
videoEl.className += ' some-super-class';
videoEl.className += ' some-super-class';
// autoplay will be true here, since we passed in as such
(options.autoplay) {
options.autoplay = false
}
// autoplay will be true here, since we passed in as such
(options.autoplay) {
options.autoplay = false
}
// options that are returned here will be merged with old options
// in this example options will now be
// {autoplay: false, controls: true}
return options;
};
// options that are returned here will be merged with old options
// in this example options will now be
// {autoplay: false, controls: true}
return options;
};
videojs.hook('beforesetup', beforeSetup);
videojs('some-id', {autoplay: true, controls: true});
videojs.hook('beforesetup', beforeSetup);
videojs('some-id', {autoplay: true, controls: true});
```
### setup
`setup` is called just after the player is created. This allows:
* plugin or custom functionalify to intialize on the player
* changes to the player object itself
`setup` hook functions:
* Take one argument
* player: the player that video.js created
* player: the player that video.js created
* Don't have to return anything
Example: adding setup hook
```js
var setup = function(player) {
// initialize the foo plugin
@ -65,56 +84,63 @@ Example: adding setup hook
## Usage
### Adding
In order to use hooks you must first include video.js in the page or script that you are using. Then you add hooks using `videojs.hook(<name>, function)` before running the `videojs()` function.
Example: adding hooks
```js
videojs.hook('beforesetup', function(videoEl, options) {
// videoEl will be the element with id=vid1
// options will contain {autoplay: false}
});
videojs.hook('setup', function(player) {
// player will be the same player that is defined below
// as `var player`
});
var player = videojs('vid1', {autoplay: false});
videojs.hook('beforesetup', function(videoEl, options) {
// videoEl will be the element with id=vid1
// options will contain {autoplay: false}
});
videojs.hook('setup', function(player) {
// player will be the same player that is defined below
// as `var player`
});
var player = videojs('vid1', {autoplay: false});
```
After adding your hooks they will automatically be run at the correct time in the video.js lifecycle.
### Getting
To access the array of hooks that currently exists and will be run on the video.js object you can use the `videojs.hooks` function.
Example: getting all hooks attached to video.js
```js
var beforeSetupHooks = videojs.hooks('beforesetup');
var setupHooks = videojs.hooks('setup');
var beforeSetupHooks = videojs.hooks('beforesetup');
var setupHooks = videojs.hooks('setup');
```
### Removing
To stop hooks from being executed during the video.js lifecycle you will remove them using `videojs.removeHook`.
Example: remove a hook that was defined by you
```js
var beforeSetup = function(videoEl, options) {};
var beforeSetup = function(videoEl, options) {};
// add the hook
videojs.hook('beforesetup', beforeSetup);
// add the hook
videojs.hook('beforesetup', beforeSetup);
// remove that same hook
videojs.removeHook('beforesetup', beforeSetup);
// remove that same hook
videojs.removeHook('beforesetup', beforeSetup);
```
You can also use `videojs.hooks` in conjunction with `videojs.removeHook` but it may have unexpected results if used during an asynchronous callbacks as other plugins/functionality may have added hooks.
Example: using `videojs.hooks` and `videojs.removeHook` to remove a hook
```js
// add the hook
videojs.hook('setup', function(videoEl, options) {});
// add the hook
videojs.hook('setup', function(videoEl, options) {});
var setupHooks = videojs.hooks('setup');
var setupHooks = videojs.hooks('setup');
// remove the hook you just added
videojs.removeHook('setup', setupHooks[setupHooks.length - 1]);
// remove the hook you just added
videojs.removeHook('setup', setupHooks[setupHooks.length - 1]);
```

45
docs/guides/languages.md
View File

@ -1,20 +1,40 @@
# Languages
Multiple language support allows for users of non-English locales to natively interact with the Video.js player.
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.
## Table of Contents
* [Using Video.js Languages](#using-videojs-languages)
* [Contributing to Video.js Translations](#contributing-to-videojs-translations)
* [JSON Format](#json-format)
* [File Naming](#file-naming)
* [Updating an Existing Translation](#updating-an-existing-translation)
* [Writing a New Translation](#writing-a-new-translation)
* [Advanced Language Usage](#advanced-language-usage)
* [Adding Languages via the API](#adding-languages-via-the-api)
* [Per-Player Languages](#per-player-languages)
* [Setting Default Player Language](#setting-default-player-language)
* [Determining Player Language](#determining-player-language)
* [Internal Language Selection](#internal-language-selection)
* [References](#references)
## 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:
```
```html
<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...
### 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
@ -29,6 +49,7 @@ Video.js uses a JSON object to describe a language, where the keys are English a
```
### 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.
@ -46,6 +67,7 @@ If there is a [missing translation](../translations-needed.md), mistake, or room
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.
@ -53,17 +75,19 @@ The template for new language files is the English file ([lang/en.json][lang-en]
The first step to writing a new translation is to copy the English file:
```sh
$ cp lang/en.json lang/${NEW_LANG_CODE}.json
cp lang/en.json lang/${NEW_LANG_CODE}.json
```
Otherwise, the process is the same as [updating an existing translation](#updating-an-existing-translation).
## 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.
In each case, these custom language definitions _take precedence over any Video.js-provided languages!_
### 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).
```js
@ -78,6 +102,7 @@ videojs.addLanguage('es', {
```
### 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):
```js
@ -106,14 +131,15 @@ Additionally, the `language` method of the player can be used to set the languag
The player language is set to one of the following in descending priority:
- 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
* 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
#### 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.
* 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.
## References
@ -123,7 +149,8 @@ Standard languages codes [are defined by the IANA][lang-codes].
For all existing/supported languages, please see the [languages lolder (`lang/`)][lang-supported] 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

121
docs/guides/options.md
View File

@ -2,44 +2,49 @@
> **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 -->
## Table of Contents
- [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 -->
* [Standard &lt;video> Element Options](#standard-video-element-options)
* [autoplay](#autoplay)
* [controls](#controls)
* [height](#height)
* [loop](#loop)
* [muted](#muted)
* [poster](#poster)
* [preload](#preload)
* ['auto'](#auto)
* ['metadata'](#metadata)
* ['none'](#none)
* [src](#src)
* [width](#width)
* [Video.js-specific Options](#videojs-specific-options)
* [aspectRatio](#aspectratio)
* [children](#children)
* [fluid](#fluid)
* [inactivityTimeout](#inactivitytimeout)
* [language](#language)
* [languages](#languages)
* [nativeControlsForTouch](#nativecontrolsfortouch)
* [notSupportedMessage](#notsupportedmessage)
* [plugins](#plugins)
* [sourceOrder](#sourceorder)
* [sources](#sources)
* [techOrder](#techorder)
* [vtt.js](#vttjs)
* [Component Options](#component-options)
* [children](#children-1)
* [${componentName}](#componentname)
* [Tech Options](#tech-options)
* [${techName}](#techname)
* [nativeControlsForTouch](#nativecontrolsfortouch-1)
* [nativeTextTracks](#nativetexttracks)
## 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.
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 in the setup guide](setup.md#options). Typically, defaults are not listed as this is left to browser vendors.
### `autoplay`
> Type: `boolean`
If `true`/present as an attribute, begins playback when the player is ready.
@ -47,70 +52,85 @@ 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`
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`
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. Sometimes, the meta data will be loaded by downloading a few frames of 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|Object`
This option is inherited from the [`Component` base class](#component-options).
### `fluid`
> Type: `boolean`
When `true`, the Video.js player will have a fluid size. In other words, it will scale to fit its container.
@ -118,6 +138,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`
> 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.
@ -125,6 +146,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`
> 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.
@ -132,6 +154,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`
> 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.
@ -141,16 +164,19 @@ 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!
### `nativeControlsForTouch`
> Type: `boolean`
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.
@ -178,11 +204,12 @@ 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: `boolean`, Default: `false`
> 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.
Tells Video.js to prefer the order of [`sources`](#sources) over [`techOrder`](#techorder) in selecting a source and playback tech.
Given the following example:
@ -209,17 +236,18 @@ However, because the `sourceOrder` is `true`, Video.js flips that process around
In summary, the default algorithm is:
- for each tech:
- for each source:
- if tech can play source, use this tech/source combo
* 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
* for each source:
* for each tech:
* 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:
@ -246,11 +274,13 @@ Using `<source>` elements will have the same effect:
```
### `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`.
@ -264,6 +294,7 @@ 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 which children (by component name) and in which order they are created on a player (or other component):
@ -294,6 +325,7 @@ 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:
@ -307,7 +339,9 @@ 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"`).
@ -329,16 +363,19 @@ videojs.options.flash.swf = '//path/to/videojs.swf'
```
#### `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. 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/
[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

24
docs/guides/player-workflows.md
View File

@ -1,10 +1,25 @@
# 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!
## Table of Contents
* [Removing Players](#removing-players)
* [dispose()](#dispose)
* [Signs of an Undisposed Player](#signs-of-an-undisposed-player)
* [Showing and Hiding a Player](#showing-and-hiding-a-player)
* [Using Video.js with...](#using-videojs-with)
* [jQuery](#jquery)
* [React](#react)
* [Ember](#ember)
* [Angular](#angular)
## 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
@ -26,15 +41,16 @@ 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:
```
```console
TypeError: this.el_.vjs_getProperty is not a function
```
or
```
```console
TypeError: Cannot read property 'vdata1234567890' of null
```
@ -62,9 +78,13 @@ modal.on('hide', function() {
```
## Using Video.js with...
Coming soon...
### jQuery
### React
### Ember
### Angular

19
docs/guides/plugins.md
View File

@ -1,14 +1,13 @@
Plugins
=======
# Plugins
If you've built something cool with Video.js, you can easily share it with the rest of the world by creating a plugin. Although, you can roll your own, you can also use [generator-videojs-plugin](https://github.com/dmlap/generator-videojs-plugin), a [Yeoman](http://yeoman.io) generator that provides scaffolding for video.js plugins including:
* [Grunt](http://gruntjs.com) for build management
* [npm](https://www.npmjs.org) for dependency management
* [QUnit](http://qunitjs.com) for testing
## Step 1: Write Some Javascript
Step 1: Write Some Javascript
-----------------------------
You may have already done this step. Code up something interesting and then wrap it in a function. At the most basic level, that's all a video.js plugin is. By convention, plugins take a hash of options as their first argument:
```js
@ -21,8 +20,8 @@ You may have already done this step. Code up something interesting and then wrap
When it's activated, `this` will be the Video.js player your plugin is attached to. You can use anything you'd like in the [Video.js API](./api.md) when you're writing a plugin: change the `src`, mess up the DOM, or listen for and emit your own events.
Step 2: Registering A Plugin
-------------------------------
## Step 2: Registering A Plugin
It's time to give the rest of the world the opportunity to be awed by your genius. When your plugin is loaded, it needs to let Video.js know this amazing new functionality is now available:
```js
@ -31,8 +30,8 @@ It's time to give the rest of the world the opportunity to be awed by your geniu
From this point on, your plugin will be added to the Video.js prototype and will show up as a property on every instance created. Make sure you choose a unique name that doesn't clash with any of the properties already in Video.js. Which leads us to...
Step 3: Using A Plugin
----------------------
## Step 3: Using A Plugin
There are two ways to initialize a plugin. If you're creating your video tag dynamically, you can specify the plugins you'd like to initialize with it and any options you want to pass to them:
```js
@ -56,4 +55,4 @@ That's it. Head on over to the [Video.js wiki](https://github.com/videojs/video.
## How should I use the Video.js icons in my plugin?
If you'd like to use any of the icons available in the [Video.js icon set](http://videojs.github.io/font/), please target them via the CSS class names instead of codepoints. The codepoints *may* change between versions of the font, so using the class names ensures that your plugin will stay up to date with any font changes.
If you'd like to use any of the icons available in the [Video.js icon set](http://videojs.github.io/font/), please target them via the CSS class names instead of codepoints. The codepoints _may_ change between versions of the font, so using the class names ensures that your plugin will stay up to date with any font changes.

37
docs/guides/setup.md
View File

@ -1,20 +1,19 @@
# 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 -->
## Table of Contents
- [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 -->
* [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 &lt;video> Tag Attributes](#a-note-on-video-tag-attributes)
* [Player Readiness](#player-readiness)
* [Advanced Player Workflows](#advanced-player-workflows)
## 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.
@ -22,6 +21,7 @@ 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!
@ -38,6 +38,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 pass options to Video.js. A minimal example looks like this:
```html
@ -50,6 +51,7 @@ 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:
@ -79,6 +81,7 @@ 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]:
@ -104,6 +107,7 @@ 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
@ -133,6 +137,7 @@ 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:
@ -169,13 +174,19 @@ 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/
[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

24
docs/guides/skins.md
View File

@ -1,30 +1,49 @@
# Skins
## Table of Contents
* [Default Skin](#default-skin)
* [Additional &lt;style> Elements](#additional-style-elements)
* [Disabling Additional &lt;style> Elements](#disabling-additional-style-elements)
* [Effect on Player#width() and Player#height()](#effect-on-playerwidth-and-playerheight)
* [Icons](#icons)
* [Creating a Skin](#creating-a-skin)
* [Add a Custom Class to the Player](#add-a-custom-class-to-the-player)
* [Customize Styles](#customize-styles)
## 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.
* 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
@ -42,6 +61,7 @@ player.addClass('vjs-matrix');
> **Note:** The `vjs-` prefix is a convention for all classes that are contained in a Video.js player.
### 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`).
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.

89
docs/guides/tech.md
View File

@ -1,15 +1,15 @@
Playback Technology ("Tech")
============================
# Playback Technology ("Tech")
Playback Technology refers to the specific browser or plugin technology used to play the video or audio. When using HTML5, the playback technology is the video or audio element. When using Flash, the playback technology is the specific Flash player used, e.g. Flowplayer, YouTube Player, video-js.swf, etc. (not just "Flash"). This could also include Silverlight, Quicktime, or any other plugin that will play back video in the browser, as long as there is an API wrapper written for it.
Essentially we're using HTML5 and plugins only as video decoders, and using HTML and JavaScript to create a consistent API and skinning experience across all of them.
Building an API Wrapper
-----------------------
## Building an API Wrapper
We'll write a more complete guide on writing a wrapper soon, but for now the best resource is the [Video.js](https://github.com/zencoder/video-js/tree/master/src) source where you can see how both the HTML5 and video-js.swf API wrappers were created.
Required Methods
----------------
## Required Methods
canPlayType
play
pause
@ -19,8 +19,8 @@ duration
buffered
supportsFullScreen
Required Events
---------------
## Required Events
loadstart
play
pause
@ -30,37 +30,45 @@ volumechange
durationchange
error
Optional Events (include if supported)
--------------------------------------
## Optional Events (include if supported)
timeupdate
progress
enterFullScreen
exitFullScreen
Adding Playback Technology
==================
## Adding Playback Technology
When adding additional Tech to a video player, make sure to add the supported tech to the video object.
### Tag Method: ###
<video data-setup='{"techOrder": ["html5", "flash", "other supported tech"]}'
### Tag Method:
### Object Method: ###
videojs("videoID", {
techOrder: ["html5", "flash", "other supported tech"]
});
```html
<video data-setup='{"techOrder": ["html5", "flash", "other supported tech"]}'>
```
### Object Method:
```js
videojs("videoID", {
techOrder: ["html5", "flash", "other supported tech"]
});
```
## Technology Ordering
Technology Ordering
==================
By default Video.js performs "Tech-first" ordering when it searches for a source/tech combination to play videos. This means that if you have two sources and two techs, video.js will try to play each video with the first tech in the `techOrder` option property before moving on to try the next playback technology.
Tech-first ordering can present a problem if you have a `sourceHandler` that supports both `Html5` and `Flash` techs such as videojs-contrib-hls.
For example, given the following video element:
<video data-setup='{"techOrder": ["html5", "flash"]}'>
<source src="http://your.static.provider.net/path/to/video.m3u8" type="application/x-mpegURL">
<source src="http://your.static.provider.net/path/to/video.mp4" type="video/mp4">
</video>
```html
<video data-setup='{"techOrder": ["html5", "flash"]}'>
<source src="http://your.static.provider.net/path/to/video.m3u8" type="application/x-mpegURL">
<source src="http://your.static.provider.net/path/to/video.mp4" type="video/mp4">
</video>
```
There is a good chance that the mp4 source will be selected on platforms that do not have media source extensions. Video.js will try all sources against the first playback technology, in this case `Html5`, and select the first source that can play - in this case MP4.
@ -72,10 +80,12 @@ Video.js now provides another method of selecting the source - "Source-first" or
With a player setup as follows:
<video data-setup='{"techOrder": ["html5", "flash"], "sourceOrder": true}'>
<source src="http://your.static.provider.net/path/to/video.m3u8" type="application/x-mpegURL">
<source src="http://your.static.provider.net/path/to/video.mp4" type="video/mp4">
</video>
```html
<video data-setup='{"techOrder": ["html5", "flash"], "sourceOrder": true}'>
<source src="http://your.static.provider.net/path/to/video.m3u8" type="application/x-mpegURL">
<source src="http://your.static.provider.net/path/to/video.mp4" type="video/mp4">
</video>
```
The Flash-based HLS support will be tried before falling back to the MP4 source.
@ -83,23 +93,28 @@ In "Source-first" mode, the tests run something like this:
Can video.m3u8 play with Html5? No...
Can video.m3u8 play with Flash? Yes! Use the first source.
Flash Technology
==================
## Flash Technology
The Flash playback tech is a part of the default `techOrder`. You may notice undesirable playback behavior in browsers that are subject to using this playback tech, in particular when scrubbing and seeking within a video. This behavior is a result of Flash's progressive video playback.
Enabling Streaming Playback
--------------------------------
### Enabling Streaming Playback
In order to force the Flash tech to choose streaming playback, you need to provide a valid streaming source **before other valid Flash video sources**. This is necessary because of the source selection algorithm, where playback tech chooses the first possible source object with a valid type. Valid streaming `type` values include `rtmp/mp4` and `rtmp/flv`. The streaming `src` value requires valid connection and stream strings, separated by an `&`. An example of supplying a streaming source through your HTML markup might look like:
<source src="rtmp://your.streaming.provider.net/cfx/st/&mp4:path/to/video.mp4" type="rtmp/mp4">
<source src="http://your.static.provider.net/path/to/video.mp4" type="video/mp4">
<source src="http://your.static.provider.net/path/to/video.webm" type="video/webm">
```html
<source src="rtmp://your.streaming.provider.net/cfx/st/&mp4:path/to/video.mp4" type="rtmp/mp4">
<source src="http://your.static.provider.net/path/to/video.mp4" type="video/mp4">
<source src="http://your.static.provider.net/path/to/video.webm" type="video/webm">
```
You may optionally use the last `/` as the separator between connection and stream strings, for example:
<source src="rtmp://your.streaming.provider.net/cfx/st/mp4:video.mp4" type="rtmp/mp4">
```html
<source src="rtmp://your.streaming.provider.net/cfx/st/mp4:video.mp4" type="rtmp/mp4">
```
All four RTMP protocols are valid in the `src` (RTMP, RTMPT, RTMPE, and RTMPS).
### A note on sandboxing and security
#### A note on sandboxing and security
In some environments, such as Electron and NW.js apps, stricter policies are enforced, and `.swf` files won’t be able to communicate with the outside world out of the box. To stream media, you have to add them to a special manifest of trusted files. [nw-flash-trust](https://github.com/szwacz/nw-flash-trust) makes this job easy.

84
docs/guides/text-tracks.md
View File

@ -1,12 +1,36 @@
# 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 text tracks.
## Table of Contents
* [A Note on "Remote" Text Tracks](#a-note-on-remote-text-tracks)
* [Creating the Text File](#creating-the-text-file)
* [Adding Text Tracks to Video.js](#adding-text-tracks-to-videojs)
* [track Attributes](#track-attributes)
* [kind](#kind)
* [label](#label)
* [default](#default)
* [srclang](#srclang)
* [Text Tracks from Another Domain](#text-tracks-from-another-domain)
* [Working with Text Tracks](#working-with-text-tracks)
* [Showing Tracks Programmatically](#showing-tracks-programmatically)
* [Listen for a Cue Becoming Active](#listen-for-a-cue-becoming-active)
* [Emulated Text Tracks](#emulated-text-tracks)
* [Text Track Settings](#text-track-settings)
* [Text Track Precedence](#text-track-precedence)
* [API](#api)
* [Remote Text Tracks](#remote-text-tracks)
* [Text Tracks](#text-tracks-1)
## 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.
> **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 ]`).
@ -14,6 +38,7 @@ Timed text requires a text file in [WebVTT](http://dev.w3.org/html5/webvtt/) for
> 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 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
@ -33,23 +58,27 @@ Once you have your WebVTT files created, you can add them to your `video` elemen
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.
* `"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.
@ -57,6 +86,7 @@ The boolean `default` attribute can be used to indicate that a track's mode shou
> **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.
@ -64,6 +94,7 @@ The valid [BCP 47](https://tools.ietf.org/html/bcp47) code for the language of t
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.
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:
@ -78,7 +109,9 @@ In addition to enabling CORS, you will need to add the [`crossorigin` attribute]
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).
## 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.
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.
@ -100,6 +133,7 @@ for (var i = 0; i < tracks.length; i++) {
```
### 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.
@ -128,6 +162,7 @@ metadataTrack.addEventListener('cuechange', function() {
```
## 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.
@ -144,6 +179,7 @@ var 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 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.
@ -163,41 +199,45 @@ var player = videojs('myvideo', {
```
## Text Track Precedence
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.
* 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
For more complete information, refer to the [Video.js API docs](http://docs.videojs.com/docs/api/index.html).
### 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.
- `Player#remoteTextTracks()`
- `Player#remoteTextTrackEls()`
- `Player#addRemoteTextTrack(Object options)`
* `Player#remoteTextTracks()`
* `Player#remoteTextTrackEls()`
* `Player#addRemoteTextTrack(Object options)`
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.
- `Player#removeRemoteTextTrack(HTMLTrackElement|TextTrack)`
* `Player#removeRemoteTextTrack(HTMLTrackElement|TextTrack)`
### 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.
- `Player#textTracks()`
- `Player#addTextTrack(String kind, [String label [, String language]])`
* `Player#textTracks()`
* `Player#addTextTrack(String kind, [String label [, String language]])`
> **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!
- `TextTrackList()`
- `TextTrack()`
* `TextTrackList()`
* `TextTrack()`

10
docs/guides/tracks.md
View File

@ -1,11 +1,21 @@
# Tracks
There are currently three types of tracks:
## Table of Contents
* [Audio Tracks](#audio-tracks)
* [Video Tracks](#video-tracks)
* [Text Tracks](#text-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.

40
docs/guides/troubleshooting.md
View File

@ -1,18 +1,37 @@
Troubleshooting
# Troubleshooting
## Table of Contents
* [Problems with media formats](#problems-with-media-formats)
* [Choosing a video format](#choosing-a-video-format)
* [I want to have a single source and don't care about live/adaptive streaming:](#i-want-to-have-a-single-source-and-dont-care-about-liveadaptive-streaming)
* [I need adaptive streaming or live streaming](#i-need-adaptive-streaming-or-live-streaming)
* [Make sure you are using formats that video.js can play:](#make-sure-you-are-using-formats-that-videojs-can-play)
* [Make sure that the codec for that is being used in the file container is supported:](#make-sure-that-the-codec-for-that-is-being-used-in-the-file-container-is-supported)
* [If you are using Flash videos:](#if-you-are-using-flash-videos)
* [Problems when hosting media](#problems-when-hosting-media)
* [Problems with Fullscreen](#problems-with-fullscreen)
* [Problems with playback](#problems-with-playback)
* [video.js Errors](#videojs-errors)
* [vdata123456 errors](#vdata123456-errors)
## Problems with media formats
### Choosing a video format
#### I want to have a single source and don't care about live/adaptive streaming:
Most browsers now play MP4 with h264 video. If you want to have a single source, and neither live streaming
nor adaptive streaming is a consideration, MP4 is a good choice.
#### I need adaptive streaming or live streaming
Use HLS with [videojs-contrib-hls][hls] or
Use Dash with [videojs-contrib-dash][dash].
HLS is more convenient as mobile browsers have native support.
### Make sure you are using formats that video.js can play:
* Does your browser/OS support the type of media that you are trying to play?
* Do you have a video.js plugin that will add support for a media format to video.js? For Example:
* [videojs-youtube][youtube]
@ -22,16 +41,19 @@ HLS is more convenient as mobile browsers have native support.
This is used to determine if video.js can play a certain type of media.
### Make sure that the codec for that is being used in the file container is supported:
* MP4 in browsers typically only supports h264 video and MP3 or AAC audio
* Some low end phones save video in 3GP format but give it an MP4 extension. These files will not play.
### If you are using Flash videos:
* Make sure that Flash is installed
* Make sure the Flash tech is included with video.js (in `video.js >= v6.0.0` it won't be, see [videojs-flash][flash])
* Flash media include RTMP streams and FLV format media.
* SWF is not a media format
## Problems when hosting media
* Your server must support byte-range requests as Chrome and Safari rely on them:
* Most servers support this by default.
* If you are proxying the media files via a server side script (PHP), this script must implement ranges. PHP does not do this by default.
@ -42,12 +64,14 @@ HLS is more convenient as mobile browsers have native support.
* You are using [text tracks][text-tracks] (captions, subtitles, etc.) and they are being served from a different domain than your page.
## Problems with Fullscreen
* If your player is in an iframe, the parent iframes must have the following attributes for fullscreen to be allowed:
* `allowfullscreen`
* `webkitallowfullscreen`
* `mozallowfullscreen`
## Problems with playback
* Make sure that the media host supports byte-range requests, this could be breaking playback. See [Problems when Hosting media][hosting-media] for more info.
* If your media is taking a long time to start playback or the entire mediadownloads before playback:
* It is likely that metadata for the media has not been included at the start of the media. In MP4 terms this is called
@ -55,7 +79,9 @@ HLS is more convenient as mobile browsers have native support.
a "fast start" or "optimize for streaming" option.
## video.js Errors
### vdata123456 errors
This error is thrown when an element that is associated with a component is removed
from the DOM but the event handlers associated with the element are not removed. This
is almost always due to event listeners not being disposed when dispose is called on
@ -63,18 +89,18 @@ a component.
To fix this issue please make sure that all event listeners are cleaned up on dispose.
<!-- same-page -->
[hosting-problems]: #problems-when-hosting-media
[hosting-media]: #problems-when-hosting-media
<!-- guides -->
[text-tracks]: /docs/guides/text-tracks.md
[text-tracks]: text-tracks.md
<!-- official projects -->
[hls]: https://github.com/videojs/videojs-contrib-hls
[dash]: https://github.com/videojs/videojs-contrib-dash
[youtube]: https://github.com/videojs/videojs-youtube
[flash]: https://github.com/videojs/videojs-flash
<!-- External links -->
[media-types]: http://www.iana.org/assignments/media-types/media-types.xhtml#video
[cors]: http://enable-cors.org/

53
docs/guides/video-tracks.md
View File

@ -1,14 +1,33 @@
# 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.
## Table of Contents
* [Caveats](#caveats)
* [Working with Video Tracks](#working-with-video-tracks)
* [Add a Video Track to the Player](#add-a-video-track-to-the-player)
* [Listen for a Video Track Becoming Enabled](#listen-for-a-video-track-becoming-enabled)
* [Removing an Video Track from the Player](#removing-an-video-track-from-the-player)
* [API](#api)
* [videojs.VideoTrack](#videojsvideotrack)
* [id](#id)
* [kind](#kind)
* [label](#label)
* [language](#language)
* [selected](#selected)
## Caveats
- 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.
* 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
```js
// Create a player.
var player = videojs('my-player');
@ -26,6 +45,7 @@ player.videoTracks().addTrack(track);
```
### 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.
@ -50,6 +70,7 @@ videoTrackList.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
@ -61,41 +82,47 @@ 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`
* `Player#videoTracks`
* `VideoTrackList`
* `VideoTrack`
### `videojs.VideoTrack`
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.
#### `kind`
> [standard definition](https://html.spec.whatwg.org/multipage/embedded-content.html#dom-videotrack-kind)
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
- `"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.
- `""` (default): No explicit kind, or the kind given by the track's metadata is not recognized by the user agent.
* `"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.
* `""` (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-videotrack-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`
> [standard definition](https://html.spec.whatwg.org/multipage/embedded-content.html#dom-videotrack-language)
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.
@ -103,9 +130,9 @@ The valid [BCP 47](https://tools.ietf.org/html/bcp47) code for the language of t
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.
#### `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.
[spec-videotrack]: https://html.spec.whatwg.org/multipage/embedded-content.html#videotrack

93
docs/index.md
View File

@ -1,64 +1,95 @@
# [Video.js][vjs] Documentation
# [Video.js][vjs-website] Documentation
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.
## Guides
## Table of Contents
* [Resolving Issues](#resolving-issues)
* [FAQ](#faq)
* [Troubleshooting](#troubleshooting)
* [Guides](#guides)
* [Getting Started](#getting-started)
* [Setup](#setup)
* [Player Workflows](#player-workflows)
* [Options](#options)
* [Tracks](#tracks)
* [Customizing](#customizing)
* [Skins](#skins)
* [Plugins](#plugins)
* [Components](#components)
* [Tech](#tech)
* [Languages](#languages)
* [Hooks](#hooks)
* [API Docs](#api-docs)
## Resolving Issues
### [FAQ](guides/faq.md)
The frequently asked questions for video.js.
### [Troubleshooting](guides/troubleshooting.md)
Troubleshooting help for video.js.
## [Guides](guides)
### Getting Started
#### [Setup][guides-setup]
#### [Setup](guides/setup.md)
The setup guide covers all methods of setting up Video.js players. After mastering the basics, see the [player workflows guide][guides-workflow].
The setup guide covers all methods of setting up Video.js players.
#### [Options][guides-options]
#### [Player Workflows](guides/player-workflows.md)
After mastering the basics of setup move over to this guide for some more advanced player workflows.
#### [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.
#### [Tracks][guides-tracks]
#### [Tracks](guides/tracks.md)
Tracks are used for displaying text information over a video, selecting different audio tracks for a video, or selecting different video tracks.
### Customizing
#### [Skins][guides-skins]
#### [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.
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. For a list of skins you can check the [video.js wiki][skins-list].
#### [Plugins][guides-plugins]
#### [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](https://github.com/videojs/video.js/wiki/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][plugins-list].
#### [Components][guides-components]
#### [Components](guides/components.md)
Video.js is built around a collection of components. These are the building blocks of the player UI.
#### [Tech][guides-tech]
#### [Tech](guides/tech.md)
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
#### [Languages](guides/languages.md)
Video.js has multi-language support! Follow this guide to see how you can contribute to and use languages.
#### [Hooks](guides/hooks.md)
A "hook" is functionality that wants to do when videojs creates a player. Right now only `beforesetup` and `setup` are supported. See the guide for more information on that.
## [API Docs][api]
You can refer to the [full list of API docs][api], but the most relevant API doc is for the [Player][api-player].
[plugins-list]: http://videojs.com/plugins
[skins-list]: https://github.com/videojs/video.js/wiki/Skins
[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
[guides-workflow]: ./guides/player-workflows.md
[vjs]: http://videojs.com
[vjs-website]: http://videojs.com

11
package.json
View File

@ -24,8 +24,10 @@
"lint": "vjsstandard",
"start": "grunt watchAll",
"test": "grunt test",
"toc": "doctoc",
"docs": "jsdoc -r src/js -d docs/api -c .jsdoc.json"
"docs": "npm run docs:lint && npm run docs:api",
"docs:api": "jsdoc -r src/js -d docs/api -c .jsdoc.json",
"docs:lint": "remark -- './**/*.md'" ,
"docs:fix": "remark --output -- './**/*.md'"
},
"repository": {
"type": "git",
@ -59,7 +61,6 @@
"chg": "^0.3.2",
"conventional-changelog-cli": "^1.2.0",
"conventional-changelog-videojs": "^3.0.0",
"doctoc": "^1.2.0",
"es5-shim": "^4.1.3",
"es6-shim": "^0.35.1",
"ghooks": "^1.3.2",
@ -106,6 +107,10 @@
"npm-run": "^4.1.0",
"proxyquireify": "^3.0.0",
"qunitjs": "1.23.1",
"remark-cli": "^2.1.0",
"remark-lint": "^5.2.0",
"remark-toc": "^3.1.0",
"remark-validate-links": "^5.0.0",
"sinon": "^1.16.1",
"time-grunt": "^1.1.1",
"uglify-js": "~2.7.3",