-
Notifications
You must be signed in to change notification settings - Fork 7.4k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs(guides): Manual Documentation Improvements (#3703)
- Loading branch information
1 parent
b4ebd9b
commit d24fe40
Showing
16 changed files
with
1,202 additions
and
773 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,65 +1,107 @@ | ||
|  | ||
| ![Video.js logo][logo] | ||
|
|
||
| # [Video.js - HTML5 Video Player](http://videojs.com) | ||
| [](https://travis-ci.org/videojs/video.js) | ||
| [](https://coveralls.io/github/videojs/video.js?branch=master) | ||
| [](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] | ||
|
|
||
| [](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. | ||
|
|
||
| If you don't want to use automatic setup, you can leave off the `data-setup` attribute and initialize a `<video>` element manually using the `videojs` function: | ||
|
|
||
| ```js | ||
| var player = videojs('my-player'); | ||
| ``` | ||
|
|
||
| The `videojs` function also accepts an `options` object and a callback to be invoked | ||
| when the player is ready: | ||
|
|
||
| ```javascript | ||
| var player = videojs('really-cool-video', { /* Options */ }, function() { | ||
| console.log('Good to go!'); | ||
| ```js | ||
| var options = {}; | ||
|
|
||
| this.play(); // if you don't trust autoplay for some reason | ||
| 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 licensed under the Apache License, Version 2.0. [View the license file](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 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 |
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. | ||
| ## Working with Audio Tracks | ||
| ### Add an Audio Track to the Player | ||
| ```js | ||
| // Create a player. | ||
| var player = videojs('my-player'); | ||
|
|
||
| // Create a track object. | ||
| var track = new videojs.AudioTrack({ | ||
| id: 'my-spanish-audio-track', | ||
| kind: 'translation', | ||
| label: 'Spanish', | ||
| language: 'es' | ||
| }); | ||
|
|
||
| ### 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. | ||
| // Add the track to the player's audio track list. | ||
| player.audioTracks().addTrack(track); | ||
| ``` | ||
|
|
||
| ### 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). | ||
| ### 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. | ||
|
|
||
| ### 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. | ||
| > NOTE: The initial `AudioTrack` selection (usually the main track that is selected) should not fire a `change` event. | ||
| ## Interacting with Audio Tracks | ||
| ### Doing something when a track becomes enabled | ||
| When a new track is enabled (other than the main track) an event is fired on the `AudioTrackList` called `change` you can listen to that event and do something with it. | ||
| Here's an example: | ||
| ```js | ||
| // get the current players AudioTrackList object | ||
| let tracks = player.audioTracks(); | ||
| // Get the current player's AudioTrackList object. | ||
| var audioTrackList = player.audioTracks(); | ||
|
|
||
| // listen to the change event | ||
| tracks.addEventListener('change', function() { | ||
| // Listen to the "change" event. | ||
| audioTrackList.addEventListener('change', function() { | ||
|
|
||
| // print the currently enabled AudioTrack label | ||
| for (let i = 0; i < tracks.length; i++) { | ||
| let track = tracks[i]; | ||
| // Log the currently enabled AudioTrack label. | ||
| for (var i = 0; i < 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` | ||
| - `AudioTrack` | ||
|
|
||
| ### `videojs.AudioTrack` | ||
| This class is based on [the `AudioTrack` standard][spec-audiotrack] and can be used to create new audio track objects. | ||
|
|
||
| Each property below is available as an option to the `AudioTrack` constructor. | ||
|
|
||
| #### `id` | ||
| > [standard definition](https://html.spec.whatwg.org/multipage/embedded-content.html#dom-audiotrack-id) | ||
| A unique identifier for this track. Video.js will generate one if not given. | ||
|
|
||
| #### `kind` | ||
| > [standard definition](https://html.spec.whatwg.org/multipage/embedded-content.html#dom-audiotrack-kind) | ||
| Video.js supports standard `kind` values for `AudioTracks`: | ||
|
|
||
| - `"alternative"`: A possible alternative to the main track. | ||
| - `"descriptions"`: An audio description of a video track. | ||
| - `"main"`: The primary audio track for this video. | ||
| - `"main-desc"`: The primary audio track, mixed with audio descriptions. | ||
| - `"translation"`: A translated version of the main audio track. | ||
| - `"commentary"`: Commentary on the primary audio track, e.g. a director's commentary. | ||
| - `""` (default): No explicit kind, or the kind given by the track's metadata is not recognized by the user agent. | ||
|
|
||
| #### `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. | ||
|
|
||
| ### `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. | ||
| In Video.js, we only allow one track to be enabled at a time; so, if you enable more than one, the last one to be enabled will end up being the only one. While the spec allows for more than one track to be enabled, Safari and most implementations only allow one audio track to be enabled at a time. | ||
|
|
||
| ### `player.audioTracks().addTrack(AudioTrack)` | ||
| Add an existing AudioTrack to the players internal list of AudioTracks. | ||
|
|
||
| ### `player.audioTracks().removeTrack(AudioTrack)` | ||
| Remove a track from the AudioTrackList currently on the player. if no track exists this will do nothing. | ||
| [spec-audiotrack]: https://html.spec.whatwg.org/multipage/embedded-content.html#audiotrack |
Oops, something went wrong.