web/video.js
1
0
Fork 0
mirror of https://github.com/videojs/video.js.git synced 2025-09-16 09:26:56 +02:00
Code Releases Activity

docs(guides): Manual Documentation Improvements (#3703)

Browse Source
This commit is contained in:
Pat O'Neill
2016-12-02 14:27:59 -05:00
committed by Gary Katsevman
parent b4ebd9ba00
commit d24fe409e8
16 changed files with 1278 additions and 849 deletions
Download Patch File Download Diff File Expand all files Collapse all files

114
README.md
View File

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

44
docs/guides/api.md
View File

@@ -1,44 +0,0 @@
API
===
The Video.js API allows you to interact with the video through JavaScript, whether the browser is playing the video through HTML5 video, Flash, or any other supported playback technologies.
Referencing the Player
----------------------
To use the API functions, you need access to the player object. Luckily this is easy to get. You just need to make sure your video tag has an ID. The example embed code has an ID of "example\_video_1". If you have multiple videos on one page, make sure every video tag has a unique ID.
```js
var myPlayer = videojs('example_video_1');
```
(If the player hasn't been initialized yet via the data-setup attribute or another method, this will also initialize the player.)
Wait Until the Player is Ready
------------------------------
The time it takes Video.js to set up the video and API will vary depending on the playback technology being used (HTML5 will often be much faster to load than Flash). For that reason we want to use the player's 'ready' function to trigger any code that requires the player's API.
```js
videojs("example_video_1").ready(function(){
var myPlayer = this;
// EXAMPLE: Start playing the video.
myPlayer.play();
});
```
API Methods
-----------
Now that you have access to a ready player, you can control the video, get values, or respond to video events. The Video.js API function names follow the [HTML5 media API](http://www.whatwg.org/specs/web-apps/current-work/multipage/the-video-element.html). The main difference is that getter/setter functions are used for video properties.
```js
// setting a property on a bare HTML5 video element
myVideoElement.currentTime = "120";
// setting a property on a Video.js player
myPlayer.currentTime(120);
```
The full list of player API methods and events can be found in the [player API docs](http://docs.videojs.com/docs/api/index.html).

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

@@ -1,69 +1,111 @@
# Audio Tracks
Audio tracks are a feature of HTML5 video for providing alternate audio track selections to the user, so that a track other than the main track can be played. Video.js offers a cross-browser implementation of audio tracks.
Audio Tracks are a function of HTML5 video for providing alternative audio track selections to the user, so that a track other than the main track can be played. Video.js makes audio tracks work across all browsers. There are currently five types of tracks:
## Caveats
- It is not possible to add audio tracks through HTML 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.
- **Alternative**: alternative audio for the main video track
- **Descriptions**: descriptions of what is happening in the video track
- **Main**: the main audio track for this video
- **Translation**: a translation of the main audio track
- **Commentary**: commentary on the video, usually the director of the content talking about design choices
## Missing Funtionality
- It is currently impossible to add AudioTracks in a non-programtic way
- Literal switching of AudioTracks for playback is not handled by video.js and must be handled by something else. video.js only stores the track representation
## Adding to Video.js
> Right now adding audio tracks in the HTML is unsupported. Audio Tracks must be added programatically.
You must add audio tracks [programatically](#api) for the time being.
## Attributes
Audio Track propertites and settings
### kind
One of the five track types listed above. Kind defaults to empty string if no kind is included, or an invalid kind is used.
### label
The label for the track that will be show to the user, for example in a menu that list the different languages available for audio tracks.
### language
The two-letter code (valid BCP 47 language tag) for the language of the audio track, for example "en" for English. A list of language codes is [available here](languages.md#language-codes).
### enabled
If this track should be playing or not. In video.js we only allow one track to be enabled at a time. so if you enable more than one the last one to be enabled will end up being the only one.
## Interacting with Audio Tracks
### Doing something when a track becomes enabled
When a new track is enabled (other than the main track) an event is fired on the `AudioTrackList` called `change` you can listen to that event and do something with it.
Here's an example:
## Working with Audio Tracks
### Add an Audio Track to the Player
```js
// get the current players AudioTrackList object
let tracks = player.audioTracks();
// Create a player.
var player = videojs('my-player');
// listen to the change event
tracks.addEventListener('change', function() {
// Create a track object.
var track = new videojs.AudioTrack({
id: 'my-spanish-audio-track',
kind: 'translation',
label: 'Spanish',
language: 'es'
});
// print the currently enabled AudioTrack label
for (let i = 0; i < tracks.length; i++) {
let track = tracks[i];
// Add the track to the player's audio track list.
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.
```js
// Get the current player's AudioTrackList object.
var audioTrackList = player.audioTracks();
// Listen to the "change" event.
audioTrackList.addEventListener('change', function() {
// Log the currently enabled AudioTrack label.
for (var i = 0; i < audioTrackList.length; i++) {
var track = audioTrackList[i];
if (track.enabled) {
console.log(track.label);
videojs.log(track.label);
return;
}
}
});
```
### Removing an Audio Track from the Player
Assuming a player already exists and has an audio track that you want to remove, you might do something like the following:
```js
// Get the track we created in an earlier example.
var track = player.audioTracks().getTrackById('my-spanish-audio-track');
// Remove it from the audio track list.
player.audioTracks().removeTrack(track);
```
## API
For more complete information, refer to the [Video.js API docs](http://docs.videojs.com/docs/api/index.html), specifically:
### `player.audioTracks() -> AudioTrackList`
This is the main interface into the audio tracks of the player.
It returns an AudioTrackList which is an array like object that contains all the `AudioTrack` on the player.
- `Player#audioTracks`
- `AudioTrackList`
- `AudioTrack`
### `player.audioTracks().addTrack(AudioTrack)`
Add an existing AudioTrack to the players internal list of AudioTracks.
### `videojs.AudioTrack`
This class is based on [the `AudioTrack` standard][spec-audiotrack] and can be used to create new audio track objects.
### `player.audioTracks().removeTrack(AudioTrack)`
Remove a track from the AudioTrackList currently on the player. if no track exists this will do nothing.
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.
#### `label`
> [standard definition](https://html.spec.whatwg.org/multipage/embedded-content.html#dom-audiotrack-label)
The label for the track that will be shown to the user. For example, in a menu that lists the different languages available as alternate audio tracks.
#### `language`
> [standard definition](https://html.spec.whatwg.org/multipage/embedded-content.html#dom-audiotrack-language)
The valid [BCP 47](https://tools.ietf.org/html/bcp47) code for the language of the audio track, e.g. `"en"` for English or `"es"` for Spanish.
For supported language translations, please see the [languages folder (/lang)](https://github.com/videojs/video.js/tree/master/lang) folder located in the Video.js root and refer to the [languages guide](./languages.md) for more information on languages in Video.js.
#### `enabled`
> [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.
[spec-audiotrack]: https://html.spec.whatwg.org/multipage/embedded-content.html#audiotrack

151
docs/guides/components.md
View File

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

39
docs/guides/glossary.md
View File

@@ -1,39 +0,0 @@
Glossary
========
Terms related to web video.
### DOM (Document Object Model)
The container of elements on the page that must be loaded before you can interact with the elements with through Javascript.
http://en.wikipedia.org/wiki/Document_Object_Model
### Flash Fallback
The Flash video player (SWF) used to play a video when HTML5 isn't supported.
### TimeRange
### HTML5 Video
HTML is the markup language that makes up every page on the web. The newest version, HTML5, includes specifications for a video tag, that is meant to allow website developers to add a video to a page the same way they would add an image. In order for this to work, web browser developers (Mozilla, Apple, Microsoft, Google, Opera, etc.) have to build the video playback functionality into their browsers. The W3C has created directions on how video should work in browsers, and it’s up to browser developers to follow those directions, so that video works the same across all browsers. This doesn’t always happen thanks to technology, legal, and financial choices made by browser developers, but so far no one’s varying too far from the specifications. However the specifications are still being changed and refined, so browsers developers have to keep up with that as well.
Playing video in a web page may not seem so special since you can already view video on a web page through plugins like Flash Player, Quicktime, Silverlight, and RealPlayer, however this is a big step forward for standardizing video playback across web browsers and devices. The goal is that in the future, developers will only need to use one method for embedding a video, that’s based on open standards (not controlled by one company), and it will work everywhere.
A prime example of this is the iPhone and iPad. Apple has decided not to support Flash on their mobile devices, but they do support HTML5 video. Since Flash is currently the most common way video is added to web pages, most web video (aside from YouTube who has a special relationship with Apple) can’t be viewed on the iPhone or iPad. These devices are very popular, so many web sites are switching to hybrid HTML5/Flash player setups (like VideoJS).
### Video Tag
There are a number of great resources that will give you an introduction to the video tag an how it is used including:
- [Dive into HTML5](http://diveintohtml5.org/video.html)
- Lynda.com's ['HTML5 Video and Audio in Depth'](http://www.lynda.com/HTML-5-tutorials/HTML5-Video-and-Audio-in-Depth/80781-2.html) video tutorials created by yours truly.
An if you really want to dig in, you can read the (W3C Spec)[http://www.w3.org/TR/html5/video.html]. (Warning - not for the faint of heart)
### Skin
"Skin" refers to the design of the player's controls, also sometimes called the chrome. With VideoJS, new skins can be built simply by creating a new stylesheet.
### Content Delivery Network (CDN)
A network of servers around the world that host copies of a file. When your browser requests one of these files, the CDN automatically determines which server is closest to your location and delivers the file from there. This drastically increases delivery time, especially internationally.

212
docs/guides/languages.md
View File

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

452
docs/guides/options.md
View File

@@ -1,138 +1,344 @@
Options
=======
# Video.js Options Reference
Setting Options
---------------
> **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).
The Video.js embed code is simply an HTML5 video tag, so for many of the options you can use the standard tag attributes to set the options.
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
```html
<video controls autoplay preload="auto" ...>
```
Alternatively, you can use the data-setup attribute to provide options in the [JSON](http://json.org/example.html) format. This is also how you would set options that aren't standard to the video tag.
- [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)
```html
<video data-setup='{ "controls": true, "autoplay": false, "preload": "auto" }'...>
```
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
Finally, if you're not using the data-setup attribute to trigger the player setup, you can pass in an object with the player options as the second argument in the javascript setup function.
## Standard `<video>` Element Options
Each of these options is also available as a [standard `<video>` element attribute][video-attrs]; so, they can be defined in all three manners [outlined above](#setting-options). Typically, defaults are not listed as this is left to browser vendors.
### `autoplay`
> Type: `boolean`
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.
Also, if the `<video>` element has the `"vjs-fluid"`, this option is automatically set to `true`.
### `inactivityTimeout`
> Type: `number`
Video.js indicates that the user is interacting with the player by way of the `"vjs-user-active"` and `"vjs-user-inactive"` classes and the `"useractive"` event.
The `inactivityTimeout` determines how many milliseconds of inactivity is required before declaring the user inactive. 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.
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.
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.
```js
videojs("example_video_1", { "controls": true, "autoplay": false, "preload": "auto" });
```
Individual Options
------------------
> ### Note on Video Tag Attributes ###
> With HTML5 video tag attributes that can only be true or false (boolean), you simply include the attribute (no equals sign) to turn it on, or exclude it to turn it off. For example, to turn controls on:
WRONG
```html
<video controls="true" ...>
```
RIGHT
```html
<video controls ...>
```
> The biggest issue people run into is trying to set these values to false using false as the value (e.g. controls="false") which actually does the opposite and sets the value to true because the attribute is still included. If you need the attribute to include an equals sign for XHTML validation, you can set the attribute's value to the same as its name (e.g. controls="controls").
### controls ###
The controls option sets whether or not the player has controls that the user can interact with. Without controls the only way to start the video playing is with the autoplay attribute or through the API.
```html
<video controls ...>
or
{ "controls": true }
```
### autoplay ###
If autoplay is true, the video will start playing as soon as page is loaded (without any interaction from the user).
NOT SUPPORTED BY APPLE iOS DEVICES. Apple blocks the autoplay functionality in an effort to protect its customers from unwillingly using a lot of their (often expensive) monthly data plans. A user touch/click is required to start the video in this case.
```html
<video autoplay ...>
or
{ "autoplay": true }
```
### preload ###
The preload attribute informs the browser whether or not the video data should begin downloading as soon as the video tag is loaded. The options are auto, metadata, and none.
'auto': Start loading the video immediately (if the browser agrees). Some mobile devices like iPhones and iPads will not preload the video in order to protect their users' bandwidth. This is why the value is called 'auto' and not something more final like 'true'.
'metadata': Load only the meta data of the video, which includes information like the duration and dimensions of the video.
'none': Don't preload any of the video data. This will wait until the user clicks play to begin downloading.
```html
<video preload ...>
or
{ "preload": "auto" }
```
### poster ###
The poster attribute sets the image that displays before the video begins playing. This is often a frame of the video or a custom title screen. As soon as the user clicks play the image will go away.
```html
<video poster="myPoster.jpg" ...>
or
{ "poster": "myPoster.jpg" }
```
### loop ###
The loop attribute causes the video to start over as soon as it ends. This could be used for a visual effect like clouds in the background.
```html
<video loop ...>
or
{ "loop": true }
```
### width ###
The width attribute sets the display width of the video.
```html
<video width="640" ...>
or
{ "width": 640 }
```
### height ###
The height attribute sets the display height of the video.
```html
<video height="480" ...>
or
{ "height": 480 }
```
Component Options
-----------------
You can set the options for any single player component. For instance, if you wanted to remove the `muteToggle` button, which
is a child of `controlBar`, you can just set that component to false:
```js
var player = videojs('video-id', {
controlBar: {
muteToggle: false
videojs('my-player', {
plugins: {
foo: {bar: true},
boo: {baz: false}
}
});
```
This also works using the `data-setup` attribute on the video element, just remember the options need to use proper JSON
notation.
The above is roughly equivalent to:
```html
<video ... data-setup='{ "controlBar": { "muteToggle": false } }'></video>
```js
var player = videojs('my-player');
player.foo({bar: true});
player.boo({baz: false});
```
The [components guide](./components.md) has an excellent breakdown of the structure of a player, you
just need to remember to nest child components in a `children` array for each level.
Although, since the `plugins` option is an object, the order of initialization is not guaranteed!
See [the plugins guide](plugins.md) for more information on Video.js plugins.
### `sourceOrder`
> 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.
Given the following example:
```js
videojs('my-player', {
sourceOrder: true,
sources: [{
src: '//path/to/video.flv',
type: 'video/x-flv'
}, {
src: '//path/to/video.mp4',
type: 'video/mp4'
}, {
src: '//path/to/video.webm',
type: 'video/webm'
}],
techOrder: ['html5', 'flash']
});
```
Normally, the fact that HTML5 comes before Flash in the `techOrder` would mean Video.js would look for a compatible _source_ for HTML5 and would pick either the MP4 or WebM video (depending on browser support) only falling back to Flash if no compatible source for HTML5 was found.
However, because the `sourceOrder` is `true`, Video.js flips that process around. It will look for a compatible _tech_ for each source in order. Presumably, it would first find a match between the FLV (since it's first in the source order) and the Flash tech.
In summary, the default algorithm is:
- for each tech:
- for each source:
- if tech can play source, use this tech/source combo
With `sourceOrder: true`, the algorithm becomes:
- for each source:
- for each tech:
- if tech can play source, use this tech/source combo
### `sources`
> Type: `Array`
An array of objects that mirror the native `<video>` element's capability to have a series of child `<source>` elements. This should be an array of objects with the `src` and `type` properties. For example:
```js
videojs('my-player', {
sources: [{
src: '//path/to/video.mp4',
type: 'video/mp4'
}, {
src: '//path/to/video.webm',
type: 'video/webm'
}]
});
```
Using `<source>` elements will have the same effect:
```html
<video ...>
<source src="//path/to/video.mp4" type="video/mp4">
<source src="//path/to/video.webm" type="video/webm">
</video>
```
### `techOrder`
> Type: `Array`, Default: `['html5', 'flash']`
Defines the order in which Video.js techs are preferred. By default, this means that the `Html5` tech is preferred, but Video.js will fall back to `Flash` if no `Html5`-compatible source can be found.
### `vtt.js`
> Type: `string`
Allows overriding the default URL to vtt.js, which may be loaded asynchronously to polyfill support for `WebVTT`.
This option will be used in the "novtt" build of video.js (i.e. `video.novtt.js`). Otherwise, vtt.js is bundled with video.js.
## Component Options
The Video.js player is a component. Like all components, you can define what children it includes, what order they appear in, and what options are passed to them.
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):
```js
// The following code creates a player with ONLY bigPlayButton and
// controlBar child components.
videojs('my-player', {
children: [
'bigPlayButton',
'controlBar'
]
});
```
The `children` options can also be passed as an `Object`. In this case, it is used to provide `options` for any/all children, including disabling them with `false`:
```js
// This player's ONLY child will be the controlBar. Clearly, this is not the
// ideal method for disabling a grandchild!
videojs('my-player', {
children: {
controlBar: {
fullscreenControl: false
}
}
});
```
### `${componentName}`
> Type: `Object`
Components can be given custom options via the _lower-camel-case variant of the component name_ (e.g. `controlBar` for `ControlBar`). These can be nested in a representation of grandchild relationships. For example, to disable the fullscreen control:
```js
videojs('my-player', {
controlBar: {
fullscreenControl: false
}
});
```
## 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"`).
This is not used in most implementations, but one case where it may be is dictating where the Video.js SWF file is located for the `Flash` tech:
```js
videojs('my-player', {
flash: {
swf: '//path/to/videojs.swf'
}
});
```
However, this is a case where changing the global defaults is more useful:
```js
videojs.options.flash.swf = '//path/to/videojs.swf'
```
#### `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

70
docs/guides/player-workflows.md Normal file
View File

@@ -0,0 +1,70 @@
# Player Workflows
This document outlines many considerations for using Video.js for advanced player workflows. Be sure to read [the setup guide](setup.md) first!
## Removing Players
No matter the term used for it, web applications are becoming common. Not everything is a static, load-once-and-done web page anymore! This means that developers need to be able to manage the full lifecycle of a video player - from creation to destruction. Video.js supports player removal through the `dispose()` method.
### [`dispose()`](http://docs.videojs.com/docs/api/player.html#Methodsdispose)
This method is available on all Video.js players and [components](http://docs.videojs.com/docs/api/component.html#Methodsdispose). It is _the only_ supported method of removing a Video.js player from both the DOM and memory. For example, the following code sets up a player and then disposes it when media playback is complete:
```js
var player = videojs('my-player');
player.on('ended', function() {
this.dispose();
});
```
Calling `dispose()` will have a few effects:
1. Trigger a `"dispose"` event on the player, allowing for any custom cleanup tasks that need to be run by your integration.
1. Remove all event listeners from the player.
1. Remove the player's DOM element(s).
Additionally, these actions are recursively applied to _all_ the player's child components.
> **Note**: Do _not_ remove players via standard DOM removal methods: this will leave listeners and other objects in memory that you might not be able to clean up!
### Signs of an Undisposed Player
Seeing an error such as:
```
TypeError: this.el_.vjs_getProperty is not a function
```
or
```
TypeError: Cannot read property 'vdata1234567890' of null
```
Suggests that a player or component was removed from the DOM without using `dispose()`. It usually means something tried to trigger an event on it or call a method on it.
## Showing and Hiding a Player
It is not recommended that you attempt to toggle the visibility or display of a Video.js player. Doing so can be particularly problematic when it comes to the Flash tech. Instead, players should be created and [disposed](#removing-players) as needed.
This is relevant to use cases such as displaying a player in a modal/overlay. Rather than keeping a hidden Video.js player in a DOM element, it's recommended that you create the player when the modal opens and dispose it when the modal closes.
This is particularly relevant where memory/resource usage is concerned (e.g. mobile devices).
Depending on the libraries/frameworks in use, an implementation might look something like this:
```js
modal.on('show', function() {
var videoEl = modal.findEl('video');
modal.player = videojs(videoEl);
});
modal.on('hide', function() {
modal.player.dispose();
});
```
## Using Video.js with...
Coming soon...
### jQuery
### React
### Ember
### Angular

41
docs/guides/removing-players.md
View File

@@ -1,41 +0,0 @@
Removing Players
================
Sometimes, you want to remove players after page load (in single page apps or modals, for instance). It's easy to manage, but there are some simple rules you need to follow.
Call `.dispose()`
-----------------
To remove the html associated with your videojs player from the page always call the player's [`dispose()`](http://docs.videojs.com/docs/api/player.html#Methodsdispose) method:
```js
var oldPlayer = document.getElementById('my-player');
videojs(oldPlayer).dispose();
```
This method will:
1. reset the internal state of videojs
2. remove the player's dom from the page
Showing / Hiding a Player
-------------------------
For instance, if you have a modal that a player appears in, you should create the player when the modal pops up. When the modal hides, dispose the player. If you try to hide the Flash tech, things will go poorly. Even with other tech, calling `dispose()` on a player that's not needed will free up resources for the browser.
Why Is This Needed?
-------------------
VideoJS internally tracks all players and their associated data by html id attribute. If you plan to create new players with the same id as previously created players, you'll need to call the player's dispose() method to clear VideoJS's internal state before creating the new player.
Signs You Did It Wrong
-------------------------
```
TypeError: this.el_.vjs_getProperty is not a function
"VIDEOJS:" "Video.js: buffered unavailable on Hls playback technology element." TypeError: this.el_.vjs_getProperty is not a function
Stack trace:
...
```
If you encounter a console error in the browser similar to the above, you've probably forgotten to `dispose()` a player before removing it from the dom. This would happen when using the [contrib-hls](https://github.com/videojs/videojs-contrib-hls) plugin.

261
docs/guides/setup.md
View File

@@ -1,124 +1,181 @@
Setup
=====
# 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 -->
Video.js is pretty easy to set up. It can take a matter of seconds to get the player up and working on your web page.
Step 1: Include the Video.js Javascript and CSS files in the head of your page.
------------------------------------------------------------------------------
- [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)
You can download the Video.js source and host it on your own servers, or use the free CDN hosted version. As of Video.js 5.0, the source is [transpiled from ES2015](http://babeljs.io/) (formerly known as ES6) to [ES5](https://es5.github.io/), but IE8 only supports ES3. In order to continue to support IE8, we've bundled an [ES5 shim and sham](https://github.com/es-shims/es5-shim) together and hosted it on the CDN.
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
## Getting Video.js
Video.js is officially available via CDN, npm, and Bower.
Video.js works out of the box with not only HTML `<script>` and `<link>` tags, but also all major bundlers/packagers/builders, such as Browserify, Node, WebPack, etc.
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!
The core strength of Video.js is that it decorates a [standard `<video>` element][w3c-video] and emulates its associated [events and APIs][w3c-media-events], while providing a customizable DOM-based UI.
Video.js supports all attributes of the `<video>` element (such as `controls`, `preload`, etc), but it also supports [its own options](#options). There are two ways to create a Video.js player and pass it options, but they both start with a standard `<video>` element with the attribute `class="video-js"`:
```html
<script src="//vjs.zencdn.net/ie8/1.1.1/videojs-ie8.min.js"></script>
```
### CDN Version ###
```html
<link href="//vjs.zencdn.net/5.4.6/video-js.min.css" rel="stylesheet">
<script src="//vjs.zencdn.net/5.4.6/video.min.js"></script>
```
Alternatively you can always [go here](http://videojs.com/getting-started/) to get the latest URL for videojs CDN.
We include a stripped down Google Analytics pixel that tracks a random percentage (currently 1%) of players loaded from the CDN. This allows us to see (roughly) what browsers are in use in the wild, along with other useful metrics such as OS and device. If you'd like to disable analytics, you can simply include the following global **before** including Video.js:
```js
window.HELP_IMPROVE_VIDEOJS = false;
```
## Install via package manager
### NPM
```
$ npm install --save video.js
```
### Bower
```
$ bower install --save video.js
```
### Self Hosted. ###
To entirely self-host, you'll need to pull in the font files and let Video.js know where the swf is located. If you simply copy the dist folder or zip file contents into your project everything
should Just Work™, but the paths can easily be changed by editing the LESS file and re-building, or by modifying the generated CSS file. Additionally include the [videojs-vtt.js](https://www.npmjs.com/package/videojs-vtt.js) source, which adds the `WebVTT` object to the global scope.
```html
<link href="//example.com/path/to/video-js.min.css" rel="stylesheet">
<script src="//example.com/path/to/videojs-vtt.js"></script>
<script src="//example.com/path/to/video.min.js"></script>
<script>
videojs.options.flash.swf = "http://example.com/path/to/video-js.swf"
</script>
```
Step 2: Add an HTML5 video tag to your page.
--------------------------------------------
With Video.js you just use an HTML5 video tag to embed a video. Video.js will then read the tag and make it work in all browsers, not just ones that support HTML5 video. Beyond the basic markup, Video.js needs a few extra pieces.
> Note: The `data-setup` attribute described here should not be used if you use the alternative setup described in the next section.
1. The 'data-setup' Attribute tells Video.js to automatically set up the video when the page is ready, and read any options (in JSON format) from the attribute (see [options](./options.md)). There are other methods for initializing the player, but this is the easiest.
2. The 'id' Attribute: Should be used and unique for every video on the same page.
3. The 'class' attribute contains two classes:
- `video-js` applies styles that are required for Video.js functionality, like fullscreen and subtitles.
- `vjs-default-skin` applies the default skin to the HTML controls, and can be removed or overridden to create your own controls design.
Otherwise include/exclude attributes, settings, sources, and tracks exactly as you would for HTML5 video.*
```html
<video id="example_video_1" class="video-js vjs-default-skin"
controls preload="auto" width="640" height="264"
poster="http://video-js.zencoder.com/oceans-clip.png"
data-setup='{"example_option":true}'>
<source src="http://video-js.zencoder.com/oceans-clip.mp4" type="video/mp4" />
<source src="http://video-js.zencoder.com/oceans-clip.webm" type="video/webm" />
<source src="http://video-js.zencoder.com/oceans-clip.ogv" type="video/ogg" />
<p class="vjs-no-js">To view this video please enable JavaScript, and consider upgrading to a web browser that <a href="http://videojs.com/html5-video-support/" target="_blank">supports HTML5 video</a></p>
<video class="video-js">
<source src="//vjs.zencdn.net/v/oceans.mp4" type="video/mp4">
<source src="//vjs.zencdn.net/v/oceans.webm" type="video/webm">
</video>
```
By default, the big play button is located in the upper left hand corner so it doesn't cover up the interesting parts of the poster. If you'd prefer to center the big play button, you can add an additional `vjs-big-play-centered` class to your video element. For example:
### 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
<video id="example_video_1" class="video-js vjs-default-skin vjs-big-play-centered"
controls preload="auto" width="640" height="264"
poster="http://video-js.zencoder.com/oceans-clip.png"
data-setup='{"example_option":true}'>
...
<video class="video-js" data-setup='{}'>
<source src="//vjs.zencdn.net/v/oceans.mp4" type="video/mp4">
<source src="//vjs.zencdn.net/v/oceans.webm" type="video/webm">
</video>
```
Alternative Setup for Dynamically Loaded HTML
---------------------------------------------
If your web page or application loads the video tag dynamically (ajax, appendChild, etc.), so that it may not exist when the page loads, you'll want to manually set up the player instead of relying on the data-setup attribute. To do this, first remove the data-setup attribute from the tag so there's no confusion around when the player is initialized. Next, run the following javascript some time after the Video.js javascript library has loaded, and after the video tag has been loaded into the DOM.
```js
videojs("example_video_1", {}, function(){
// Player (this) is initialized and ready.
});
```
> **Note:** You _must_ use single-quotes with `data-setup` as it is expected to contain JSON.
The first argument in the `videojs` function is the ID of your video tag. Replace it with your own.
### 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].
The second argument is an options object. It allows you to set additional options like you can with the data-setup attribute.
One way to call this function is by providing it a string matching a `<video>` element's `id` attribute:
The third argument is a 'ready' callback. Once Video.js has initialized it will call this function.
Instead of using an element ID, you can also pass a reference to the element itself.
```js
videojs(document.getElementById('example_video_1'), {}, function() {
// This is functionally the same as the previous example.
});
```html
<video id="my-player" class="video-js">
<source src="//vjs.zencdn.net/v/oceans.mp4" type="video/mp4">
<source src="//vjs.zencdn.net/v/oceans.webm" type="video/webm">
</video>
```
```js
videojs(document.getElementsByClassName('awesome_video_class')[0], {}, function() {
// You can grab an element by class if you'd like, just make sure
// if it's an array that you pick one (here we chose the first).
videojs('my-player');
```
However, using an `id` attribute isn't always practical; so, the `videojs` function accepts a DOM element instead:
```html
<video class="video-js">
<source src="//vjs.zencdn.net/v/oceans.mp4" type="video/mp4">
<source src="//vjs.zencdn.net/v/oceans.webm" type="video/webm">
</video>
```
```js
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]:
```html
<video controls autoplay preload="auto" ...>
```
Alternatively, you can use the `data-setup` attribute to pass options as [JSON][json]. This is also how you would set options that aren't standard to the `<video>` element:
```html
<video data-setup='{"controls": true, "autoplay": false, "preload": "auto"}'...>
```
Finally, if you're not using the `data-setup` attribute to trigger the player setup, you can pass in an object of player options as the second argument to the `videojs` function:
```js
videojs('my-player', {
controls: true,
autoplay: false,
preload: 'auto'
});
```
\* If you have trouble playing back content you know is in the [correct format](http://blog.zencoder.com/2013/09/13/what-formats-do-i-need-for-html5-video/), your HTTP server might not be delivering the content with the correct [MIME type](http://en.wikipedia.org/wiki/Internet_media_type#Type_video). Please double check your content's headers before opening an [issue](/CONTRIBUTING.md).
### Global Defaults
Default options for all players can be found at `videojs.options` and can be changed directly. For example, to set `{autoplay: true}` for all future players:
```js
videojs.options.autoplay = true;
```
### A Note on `<video>` Tag Attributes
Many attributes are so-called [boolean attributes][boolean-attrs]. This means they are either on or off. In these cases, the attribute _should have no value_ (or should have its name as its value) - its presence implies a true value and its absence implies a false value.
_These are incorrect:_
```html
<video controls="true" ...>
<video loop="true" ...>
<video controls="false" ...>
```
> **Note:** The example with `controls="false"` can be a point of confusion for new developers - it will actually turn controls _on_!
These are correct:
```html
<video controls ...>
<video loop="loop" ...>
<video ...>
```
## Player Readiness
Because Video.js techs have the potential to be loaded asynchronously, it isn't always safe to interact with a player immediately upon setup. For this reason, Video.js players have a concept of "readiness" which will be familiar to anyone who has used jQuery before.
Essentially, any number of ready callbacks can be defined for a Video.js player. There are three ways to pass these callbacks. In each example, we'll add an identical class to the player:
Pass a callback to the `videojs()` function as a third argument:
```js
// Passing `null` for the options argument.
videojs('my-player', null, function() {
this.addClass('my-example');
});
```
Pass a callback to a player's `ready()` method:
```js
var player = videojs('my-player');
player.ready(function() {
this.addClass('my-example');
});
```
Listen for the player's `"ready"` event:
```js
var player = videojs('my-player');
player.on('ready', function() {
this.addClass('my-example');
});
```
In each case, the callback is called asynchronously - _even if the player is already ready!_
## 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

103
docs/guides/skins.md
View File

@@ -1,54 +1,77 @@
Skins
=====
# Skins
## Default Skin
When you include the Video.js CSS file (`video-js.min.css`), the default Video.js skin is applied. That means that customizing the look of a Video.js player is a matter of taking advantage of the cascading aspect of CSS to override styles.
## Base Skin
The base Video.js skin is made using HTML and CSS (although we use the [Sass preprocessor](http://sass-lang.com)),
and by default these styles are added to the DOM for you!
That means you can build a custom skin by simply taking advantage of the cascading aspect of CSS and overriding
the styles you'd like to change.
## 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.
If you don't want Video.js to inject the base styles for you, you can disable it by setting `window.VIDEOJS_NO_BASE_THEME = true` before Video.js is loaded.
Keep in mind that without these base styles enabled, you'll need to manually include them.
- 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.
Video.js does not currently include the base skin automatically yet, so, this option isn't necessary.
### 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.
## Default style elements
Video.js uses a couple of style elements dynamically, specifically, there's a default styles element as well as a player dimensions style element.
They are used to provide extra default flexiblity with styling the player. However, in some cases, like if a user has the HEAD tag managed by React, users do not want this.
When `window.VIDEOJS_NO_DYNAMIC_STYLE` is set to `true`, video.js will *not* include these element in the page.
This means that default dimensions and configured player dimensions will *not* be applied.
For example, the following player will end up having a width and height of 0 when initialized if `window.VIDEOJS_NO_DYNAMIC_STYLE === true`:
```html
<video width="600" height="300"></video>
```
### `Player#width` and `Player#height`
When `VIDEOJS_NO_DYNAMIC_STYLE` is set, `Player#width` and `Player#height` will apply any width and height
that is set directly to the video element (or whatever element the current tech uses).
_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 base theme by renaming and viewing
[`icons.html.example`](https://github.com/videojs/video.js/blob/master/sandbox/icons.html.example) in the sandbox directory.
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.
## Customization
## 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.
When you create a new skin, the easiest way to get started is to simply override the base Video.js theme.
You should include a new class matching the name of your theme, then just start overriding!
### 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:
```css
.vjs-skin-hotdog-stand { color: #FF0000; }
.vjs-skin-hotdog-stand .vjs-control-bar { background: #FFFF00; }
.vjs-skin-hotdog-stand .vjs-play-progress { background: #FF0000; }
```html
<video class="vjs-matrix video-js">...</video>
```
This would take care of the major areas of the skin (play progress, the control bar background, and icon colors),
but you can skin any other aspect.
Our suggestion is to use a browser such as Firefox and Chrome,
and use the developer tools to inspect the different elements and see what you'd like to change and what classes
to target when you do so.
Or via JavaScript:
More custom skins will be available for download soon.
If you have one you like you can share it by forking [this example on CodePen.io](http://codepen.io/heff/pen/EarCt),
and adding a link on the [Skins wiki page](https://github.com/videojs/video.js/wiki/Skins).
```js
var player = videojs('my-player');
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.
In this case, we'll need the following:
```css
/* Change all text and icon colors in the player. */
.vjs-matrix.video-js {
color: #00ff00;
}
/* Change the border of the big play button. */
.vjs-matrix .vjs-big-play-button {
border-color: #00ff00;
}
/* Change the color of various "bars". */
.vjs-matrix .vjs-volume-level,
.vjs-matrix .vjs-play-progress,
.vjs-matrix .vjs-slider-bar {
background: #00ff00;
}
```
Finally, we can save that as a `videojs-matrix.css` file and include it _after_ the Video.js CSS:
```html
<link rel="stylesheet" type="text/css" href="path/to/video-js.min.css">
<link rel="stylesheet" type="text/css" href="path/to/videojs-matrix.css">
```
If you create a skin you're particularly proud of, you can share it by adding a link on the [Skins wiki page](https://github.com/videojs/video.js/wiki/Skins). One way to create shareable skins is by forking [this example on CodePen](http://codepen.io/heff/pen/EarCt).

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

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

13
docs/guides/tracks.md
View File

@@ -1,6 +1,11 @@
# Tracks
There are currently three types of tracks
There are currently three types of tracks:
* [AudioTracks](./audio-tracks.md) - allows the selection of alternative AudioTracks for a video
* [VideoTracks](./video-tracks.md) - allows the selection of an alternative VideoTrack for a video
* [TextTracks](./text-tracks.md) - Text Tracks are used to display subtitles and captions, and add a menu for navigating between chapters in a video.
## [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.

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

@@ -1,70 +1,111 @@
# 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 function of HTML5 video for providing a selection of alternative video tracks to the user, so that they can change type of video they want to watch. Video.js makes video tracks work across all browsers. There are currently six types of tracks:
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.
- **Alternative**: an alternative video representation of the main video track
- **Captions**: The main video track with burned in captions
- **Main**: the main video track
- **Sign**: the main video track with added sign language overlay
- **Subtitles**: the main video track with burned in subtitles
- **Commentary**: the main video track with burned in commentary
## 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.
## Missing Funtionality
- It is currently impossible to add VideoTracks in a non-programtic way
- Literal switching of VideoTracks for playback is not handled by video.js and must be handled by something else. video.js only stores the track representation
- There is currently no UI implementation of VideoTracks
## Adding to Video.js
> Right now adding video tracks in the HTML is unsupported. Video Tracks must be added programatically.
You must add video tracks [programatically](#api) for the time being.
## Attributes
Video Track propertites and settings
### kind
One of the five track types listed above. Kind defaults to empty string if no kind is included, or an invalid kind is used.
### label
The label for the track that will be show to the user, for example in a menu that list the different languages available for video tracks.
### language
The two-letter code (valid BCP 47 language tag) for the language of the video track, for example "en" for English. A list of language codes is [available here](languages.md#language-codes).
### selected
If this track should be playing or not. Trying to select more than one track will cause other tracks to be deselected.
## Interacting with Video Tracks
### Doing something when a track becomes enabled
When a new track is enabled (other than the main track) an event is fired on the `VideoTrackList` called `change` you can listen to that event and do something with it.
Here's an example:
## Working with Video Tracks
### Add a Video Track to the Player
```js
// get the current players VideoTrackList object
let tracks = player.videoTracks();
// Create a player.
var player = videojs('my-player');
// listen to the change event
tracks.addEventListener('change', function() {
// get the currently selected track
let index = tracks.selectedIndex;
let track = tracks[index];
// Create a track object.
var track = new videojs.VideoTrack({
id: 'my-alternate-video-track',
kind: 'commentary',
label: 'Director\'s Commentary',
language: 'en'
});
// print the currently selected track
console.log(track.label);
// Add the track to the player's video track list.
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.
```js
// Get the current player's VideoTrackList object.
var videoTrackList = player.videoTracks();
// Listen to the "change" event.
videoTrackList.addEventListener('change', function() {
// Log the currently enabled VideoTrack label.
for (var i = 0; i < videoTrackList.length; i++) {
var track = videoTrackList[i];
if (track.enabled) {
videojs.log(track.label);
return;
}
}
});
```
### Removing an Video Track from the Player
Assuming a player already exists and has an video track that you want to remove, you might do something like the following:
```js
// Get the track we created in an earlier example.
var track = player.videoTracks().getTrackById('my-alternate-video-track');
// Remove it from the video track list.
player.videoTracks().removeTrack(track);
```
## API
For more complete information, refer to the [Video.js API docs](http://docs.videojs.com/docs/api/index.html), specifically:
### `player.videoTracks() -> VideoTrackList`
This is the main interface into the video tracks of the player.
It returns an VideoTrackList which is an array like object that contains all the `VideoTrack` on the player.
- `Player#videoTracks`
- `VideoTrackList`
- `VideoTrack`
### `player.videoTracks().addTrack(VideoTrack)`
Add an existing VideoTrack to the players internal list of VideoTracks.
### `videojs.VideoTrack`
This class is based on [the `VideoTrack` standard][spec-videotrack] and can be used to create new video track objects.
### `player.videoTracks().removeTrack(VideoTrack)`
Remove a track from the VideoTrackList currently on the player. if no track exists this will do nothing.
Each property below is available as an option to the `VideoTrack` constructor.
### `player.videoTracks().selectedIndex`
The current index for the selected track
#### `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.
#### `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.
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

61
docs/index.md
View File

@@ -1,37 +1,64 @@
[Video.js homepage](http://videojs.com)
# [Video.js][vjs] Documentation
<h1>Video.js Documentation</h1>
There are two categories of docs: [Guides][guides] and [API docs][api].
There are two categories of docs: [Guides](./guides/) and [API docs](./api/). Guides explain general topics and use cases (e.g. setup). API docs are automatically generated from the codebase and give specific details about functions, properties, and events.
(Corrections and additions welcome)
Guides explain general topics and use cases (e.g. setup). API docs are automatically generated from the codebase and give specific details about functions, properties, and events.
## Guides
### Getting Started
* [Setup](./guides/setup.md) - The setup documentation gives a deeper view of the additional methods you can use to trigger the player setup.
#### [Setup][guides-setup]
* [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.
The setup guide covers all methods of setting up Video.js players. After mastering the basics, see the [player workflows guide][guides-workflow].
* [Tracks](./guides/tracks.md) - Tracks are used for displaying text information over a video, selecting different audio tracks for a video, or selected different video tracks for a video.
#### [Options][guides-options]
There are a number of options that can be used to change how the player behaves, starting with the HTML5 media options like autoplay and preload, and expanding to Video.js specific options.
#### [Tracks][guides-tracks]
Tracks are used for displaying text information over a video, selecting different audio tracks for a video, or selecting different video tracks.
### Customizing
* [API](./guides/api.md) - The Video.js API allows you to control the video through javascript or trigger event listeners, whether the video is playing through HTML5, flash, or another playback technology.
#### [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.
* [Tech](./guides/tech.md) - A 'playback technology' is the term we're using to represent HTML5 video, Flash, and other video plugins, as well as other players like the YouTube player. Basically anything that has a unique API to audio or video. Additional playback technologies can be added relatively easily.
#### [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.
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).
### Resources
#### [Components][guides-components]
* [Glossary](./guides/glossary.md) - Some helpful definitions.
Video.js is built around a collection of components. These are the building blocks of the player UI.
* [Removing Players](./guides/removing-players.md) - Helpful for using VideoJS in single page apps.
#### [Tech][guides-tech]
A "tech" is the shorthand we're using to describe any video playback technology - be it HTML5 video, Flash, . Basically anything that has a unique API to audio or video. Additional playback technologies can be added relatively easily.
## API Docs
- The most relevant API doc is the [player API doc](http://docs.videojs.com/docs/api/player.html)
- [Full list of API Docs](http://docs.videojs.com/docs/api/index.html)
You can refer to the [full list of API docs][api], but the most relevant API doc is for the [Player][api-player].
[api]: http://docs.videojs.com/docs/api/index.html
[api-player]: http://docs.videojs.com/docs/api/player.html
[guides]: ./guides/
[guides-api]: ./guides/api.md
[guides-audio]: ./guides/audio.md
[guides-components]: ./guides/components.md
[guides-glossary]: ./guides/glossary.md
[guides-languages]: ./guides/languages.md
[guides-options]: ./guides/options.md
[guides-plugins]: ./guides/plugins.md
[guides-removing]: ./guides/removing.md
[guides-setup]: ./guides/setup.md
[guides-skins]: ./guides/skins.md
[guides-tech]: ./guides/tech.md
[guides-text-tracks]: ./guides/text-tracks.md
[guides-tracks]: ./guides/tracks.md
[guides-video-tracks]: ./guides/video-tracks.md
[guides-workflow]: ./guides/player-workflows.md
[vjs]: http://videojs.com

32
sandbox/icons.html.example
View File

@@ -33,6 +33,38 @@
<li><span class="vjs-icon-circle"></span> <code>.vjs-icon-circle</code></li>
<li><span class="vjs-icon-circle-outline"></span> <code>.vjs-icon-circle-outline</code></li>
<li><span class="vjs-icon-circle-inner-circle"></span> <code>.vjs-icon-circle-inner-circle</code></li>
<li><span class="play"></span> <code>.vjs-icon-play</code></li>
<li><span class="play-circle"></span> <code>.vjs-icon-play</code></li>
<li><span class="pause"></span> <code>.vjs-icon-play</code></li>
<li><span class="volume-mute"></span> <code>.vjs-icon-play</code></li>
<li><span class="volume-low"></span> <code>.vjs-icon-play</code></li>
<li><span class="volume-mid"></span> <code>.vjs-icon-play</code></li>
<li><span class="volume-high"></span> <code>.vjs-icon-play</code></li>
<li><span class="fullscreen-enter"></span> <code>.vjs-icon-play</code></li>
<li><span class="fullscreen-exit"></span> <code>.vjs-icon-play</code></li>
<li><span class="square"></span> <code>.vjs-icon-play</code></li>
<li><span class="spinner"></span> <code>.vjs-icon-play</code></li>
<li><span class="subtitles"></span> <code>.vjs-icon-play</code></li>
<li><span class="captions"></span> <code>.vjs-icon-play</code></li>
<li><span class="chapters"></span> <code>.vjs-icon-play</code></li>
<li><span class="share"></span> <code>.vjs-icon-play</code></li>
<li><span class="cog"></span> <code>.vjs-icon-play</code></li>
<li><span class="circle"></span> <code>.vjs-icon-play</code></li>
<li><span class="circle-outline"></span> <code>.vjs-icon-play</code></li>
<li><span class="circle-inner-circle"></span> <code>.vjs-icon-play</code></li>
<li><span class="hd"></span> <code>.vjs-icon-play</code></li>
<li><span class="cancel"></span> <code>.vjs-icon-play</code></li>
<li><span class="replay"></span> <code>.vjs-icon-play</code></li>
<li><span class="facebook"></span> <code>.vjs-icon-play</code></li>
<li><span class="gplus"></span> <code>.vjs-icon-play</code></li>
<li><span class="linkedin"></span> <code>.vjs-icon-play</code></li>
<li><span class="twitter"></span> <code>.vjs-icon-play</code></li>
<li><span class="tumblr"></span> <code>.vjs-icon-play</code></li>
<li><span class="pinterest"></span> <code>.vjs-icon-play</code></li>
<li><span class="audio-description"></span> <code>.vjs-icon-play</code></li>
<li><span class="audio"></span> <code>.vjs-icon-play</code></li>
</ul>
</body>
</html>