Manual Documentation Improvements #3703
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][vjs] | ||
|
|
||
| [![Build Status][travis-icon]][travis-link] | ||
| [![Coverage Status][coveralls-icon]][coveralls-link] | ||
| [![Slack Status][slack-icon]][slack-link] | ||
|
|
||
| [![NPM][npm-icon]][npm-link] | ||
|
|
||
| > Video.js is a web video player built from the ground up for an HTML5 world. It supports HTML5 and Flash video, as well as YouTube and Vimeo (through [plugins][plugins]). It supports video playback on desktops and mobile devices. This project was started mid 2010, and the player is now used on over ~~50,000~~ ~~100,000~~ ~~200,000~~ [400,000 websites][builtwith]. | ||
|
|
||
| ## 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.11/video-js.min.css" rel="stylesheet"> | ||
| <script src="//vjs.zencdn.net/5.11/video.min.js"></script> | ||
| ``` | ||
|
|
||
| > 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="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> | ||
|
There was a problem hiding this comment. I'd be inclined to leave the old fake urls. There was a problem hiding this comment. Why is that? I feel like this gives people something they could copy/paste and see it working. There was a problem hiding this comment. I think using real urls is good, we just need to make sure we think about the docs if any of these urls change in the future. There was a problem hiding this comment. They shouldn't, they're on the CDN. |
||
| <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> | ||
| </p> | ||
| </video> | ||
| ``` | ||
|
|
||
| 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: | ||
|
|
||
| ```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() { | ||
| videojs.log('Awww...over so soon?!'); | ||
| }); | ||
| }); | ||
| ``` | ||
|
|
||
| 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 - 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 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. | ||
|
|
||
| ## 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. | ||
|
|
||
| ## 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' | ||
| }); | ||
|
|
||
| // 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) { | ||
| 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. | ||
|
|
||
| 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 |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
is there any way that we can prevent the docs from needing to be updated every time we update the video.js version?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Sure, we could do some kind of token replacement here. I'm hesitant to do that in this PR. I want to set up some tooling related to docs in a separate PR.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
maybe add an issue or story and link it here, sounds good though.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Added in #3779