From 45a709b22708a68476e8433b4abbf62a41d47eba Mon Sep 17 00:00:00 2001 From: Gary Katsevman Date: Wed, 13 Apr 2016 14:55:56 -0400 Subject: [PATCH 1/8] Move language codes to only be in languages.md --- docs/guides/languages.md | 318 ++++++++++++++++++--------------------- docs/guides/tracks.md | 155 +------------------ 2 files changed, 149 insertions(+), 324 deletions(-) diff --git a/docs/guides/languages.md b/docs/guides/languages.md index 1887f398bd..e1b0ce2edb 100644 --- a/docs/guides/languages.md +++ b/docs/guides/languages.md @@ -161,175 +161,153 @@ The following is a list of official language codes. - - - - +
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
abAbkhazian
aaAfar
afAfrikaans
sqAlbanian
amAmharic
arArabic
anAragonese
hyArmenian
asAssamese
ayAymara
azAzerbaijani
baBashkir
euBasque
bnBengali (Bangla)
dzBhutani
bhBihari
biBislama
brBreton
bgBulgarian
myBurmese
beByelorussian (Belarusian)
kmCambodian
caCatalan
zhChinese (Simplified)
zhChinese (Traditional)
coCorsican
hrCroatian
csCzech
daDanish
nlDutch
enEnglish
eoEsperanto
etEstonian
foFaeroese
faFarsi
fjFiji
fiFinnish
- - 		- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
frFrench
fyFrisian
glGalician
gdGaelic (Scottish)
gvGaelic (Manx)
kaGeorgian
deGerman
elGreek
klGreenlandic
gnGuarani
guGujarati
htHaitian Creole
haHausa
heHebrew
hiHindi
huHungarian
isIcelandic
ioIdo
idIndonesian
iaInterlingua
ieInterlingue
iuInuktitut
ikInupiak
gaIrish
itItalian
jaJapanese
jvJavanese
knKannada
ksKashmiri
kkKazakh
rwKinyarwanda (Ruanda)
kyKirghiz
rnKirundi (Rundi)
koKorean
kuKurdish
loLaothian
laLatin
- - 		- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
lvLatvian (Lettish)
liLimburgish ( Limburger)
lnLingala
ltLithuanian
mkMacedonian
mgMalagasy
msMalay
mlMalayalam
mtMaltese
miMaori
mrMarathi
moMoldavian
mnMongolian
naNauru
neNepali
noNorwegian
ocOccitan
orOriya
omOromo (Afan, Galla)
psPashto (Pushto)
plPolish
ptPortuguese
paPunjabi
quQuechua
rmRhaeto-Romance
roRomanian
ruRussian
smSamoan
sgSangro
saSanskrit
srSerbian
shSerbo-Croatian
stSesotho
tnSetswana
snShona
iiSichuan Yi
sdSindhi
- - 		- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
siSinhalese
ssSiswati
skSlovak
slSlovenian
soSomali
esSpanish
suSundanese
swSwahili (Kiswahili)
svSwedish
tlTagalog
tgTajik
taTamil
ttTatar
teTelugu
thThai
boTibetan
tiTigrinya
toTonga
tsTsonga
trTurkish
tkTurkmen
twTwi
ugUighur
ukUkrainian
urUrdu
uzUzbek
viVietnamese
voVolapük
waWallon
cyWelsh
woWolof
xhXhosa
yiYiddish
yoYoruba
zuZulu
- -
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
abAbkhazian
aaAfar
afAfrikaans
sqAlbanian
amAmharic
arArabic
anAragonese
hyArmenian
asAssamese
ayAymara
azAzerbaijani
baBashkir
euBasque
bnBengali (Bangla)
dzBhutani
bhBihari
biBislama
brBreton
bgBulgarian
myBurmese
beByelorussian (Belarusian)
kmCambodian
caCatalan
zhChinese (Simplified)
zhChinese (Traditional)
coCorsican
hrCroatian
csCzech
daDanish
nlDutch
enEnglish
eoEsperanto
etEstonian
foFaeroese
faFarsi
fjFiji
fiFinnish
frFrench
fyFrisian
glGalician
gdGaelic (Scottish)
gvGaelic (Manx)
kaGeorgian
deGerman
elGreek
klGreenlandic
gnGuarani
guGujarati
htHaitian Creole
haHausa
heHebrew
hiHindi
huHungarian
isIcelandic
ioIdo
idIndonesian
iaInterlingua
ieInterlingue
iuInuktitut
ikInupiak
gaIrish
itItalian
jaJapanese
jvJavanese
knKannada
ksKashmiri
kkKazakh
rwKinyarwanda (Ruanda)
kyKirghiz
rnKirundi (Rundi)
koKorean
kuKurdish
loLaothian
laLatin
lvLatvian (Lettish)
liLimburgish ( Limburger)
lnLingala
ltLithuanian
mkMacedonian
mgMalagasy
msMalay
mlMalayalam
mtMaltese
miMaori
mrMarathi
moMoldavian
mnMongolian
naNauru
neNepali
noNorwegian
ocOccitan
orOriya
omOromo (Afan, Galla)
psPashto (Pushto)
plPolish
ptPortuguese
paPunjabi
quQuechua
rmRhaeto-Romance
roRomanian
ruRussian
smSamoan
sgSangro
saSanskrit
srSerbian
shSerbo-Croatian
stSesotho
tnSetswana
snShona
iiSichuan Yi
sdSindhi
siSinhalese
ssSiswati
skSlovak
slSlovenian
soSomali
esSpanish
suSundanese
swSwahili (Kiswahili)
svSwedish
tlTagalog
tgTajik
taTamil
ttTatar
teTelugu
thThai
boTibetan
tiTigrinya
toTonga
tsTsonga
trTurkish
tkTurkmen
twTwi
ugUighur
ukUkrainian
urUrdu
uzUzbek
viVietnamese
voVolapük
waWallon
cyWelsh
woWolof
xhXhosa
yiYiddish
yoYoruba
zuZulu
diff --git a/docs/guides/tracks.md b/docs/guides/tracks.md index 4652fb0919..43c8b69495 100644 --- a/docs/guides/tracks.md +++ b/docs/guides/tracks.md @@ -52,157 +52,4 @@ The default attribute can be used to have a track default to showing. Otherwise NOTE: For chapters, default is required if you want the chapters menu to show. ### srclang -The two-letter code (valid BCP 47 language tag) for the language of the text track, for example "en" for English. Here's a list of available language codes. - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
abAbkhazian
aaAfar
afAfrikaans
sqAlbanian
amAmharic
arArabic
anAragonese
hyArmenian
asAssamese
ayAymara
azAzerbaijani
baBashkir
euBasque
bnBengali (Bangla)
dzBhutani
bhBihari
biBislama
brBreton
bgBulgarian
myBurmese
beByelorussian (Belarusian)
kmCambodian
caCatalan
zhChinese (Simplified)
zhChinese (Traditional)
coCorsican
hrCroatian
csCzech
daDanish
nlDutch
enEnglish
eoEsperanto
etEstonian
foFaeroese
faFarsi
fjFiji
fiFinnish
frFrench
fyFrisian
glGalician
gdGaelic (Scottish)
gvGaelic (Manx)
kaGeorgian
deGerman
elGreek
klGreenlandic
gnGuarani
guGujarati
htHaitian Creole
haHausa
heHebrew
hiHindi
huHungarian
isIcelandic
ioIdo
idIndonesian
iaInterlingua
ieInterlingue
iuInuktitut
ikInupiak
gaIrish
itItalian
jaJapanese
jvJavanese
knKannada
ksKashmiri
kkKazakh
rwKinyarwanda (Ruanda)
kyKirghiz
rnKirundi (Rundi)
koKorean
kuKurdish
loLaothian
laLatin
lvLatvian (Lettish)
liLimburgish ( Limburger)
lnLingala
ltLithuanian
mkMacedonian
mgMalagasy
msMalay
mlMalayalam
mtMaltese
miMaori
mrMarathi
moMoldavian
mnMongolian
naNauru
neNepali
noNorwegian
ocOccitan
orOriya
omOromo (Afan, Galla)
psPashto (Pushto)
plPolish
ptPortuguese
paPunjabi
quQuechua
rmRhaeto-Romance
roRomanian
ruRussian
smSamoan
sgSangro
saSanskrit
srSerbian
shSerbo-Croatian
stSesotho
tnSetswana
snShona
iiSichuan Yi
sdSindhi
siSinhalese
ssSiswati
skSlovak
slSlovenian
soSomali
esSpanish
suSundanese
swSwahili (Kiswahili)
svSwedish
tlTagalog
tgTajik
taTamil
ttTatar
teTelugu
thThai
boTibetan
tiTigrinya
toTonga
tsTsonga
trTurkish
tkTurkmen
twTwi
ugUighur
ukUkrainian
urUrdu
uzUzbek
viVietnamese
voVolapük
waWallon
cyWelsh
woWolof
xhXhosa
yiYiddish
yoYoruba
zuZulu
- - +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). From c0fa1eb48377e3c176c535d49349eb2bf87d4454 Mon Sep 17 00:00:00 2001 From: Gary Katsevman Date: Wed, 13 Apr 2016 16:49:46 -0400 Subject: [PATCH 2/8] Add blurb about the crossorigin attribute --- docs/guides/tracks.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/guides/tracks.md b/docs/guides/tracks.md index 43c8b69495..a5b60e3f6f 100644 --- a/docs/guides/tracks.md +++ b/docs/guides/tracks.md @@ -36,6 +36,15 @@ 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 + +``` +One thing to be aware of is that in this case the video files themselves will *also* needs CORS headers applied to it. Since 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 ---------------- From 8ee89d9cd1850982884d997185c9e0ad8a4e2444 Mon Sep 17 00:00:00 2001 From: Gary Katsevman Date: Wed, 13 Apr 2016 17:03:43 -0400 Subject: [PATCH 3/8] log a warning if we think text tracks may not load due to crossorigin. --- src/js/tech/html5.js | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/src/js/tech/html5.js b/src/js/tech/html5.js index e8bb1f9b5b..f30a470bbe 100644 --- a/src/js/tech/html5.js +++ b/src/js/tech/html5.js @@ -9,6 +9,8 @@ import * as Dom from '../utils/dom.js'; import * as Url from '../utils/url.js'; import * as Fn from '../utils/fn.js'; import log from '../utils/log.js'; +import tsml from 'tsml'; +import TextTrack from '../../../src/js/tracks/text-track.js'; import * as browser from '../utils/browser.js'; import document from 'global/document'; import window from 'global/window'; @@ -29,6 +31,7 @@ class Html5 extends Tech { super(options, ready); const source = options.source; + let crossoriginTracks = false; // Set the source if one is provided // 1) Check if the source is new (if not, we want to keep the original so playback isn't interrupted) @@ -61,6 +64,11 @@ class Html5 extends Tech { // store HTMLTrackElement and TextTrack to remote list this.remoteTextTrackEls().addTrackElement_(node); this.remoteTextTracks().addTrack_(node.track); + if (!crossoriginTracks && + !this.el_.hasAttribute('crossorigin') && + Url.isCrossOrigin(node.src)) { + crossoriginTracks = true; + } } } } @@ -71,6 +79,11 @@ class Html5 extends Tech { } if (this.featuresNativeTextTracks) { + if (crossoriginTracks) { + log.warn(tsml`Text Tracks are being loaded from another origin but the crossorigin attribute isn't used. + This may prevent text tracks from loading.`); + } + this.handleTextTrackChange_ = Fn.bind(this, this.handleTextTrackChange); this.handleTextTrackAdd_ = Fn.bind(this, this.handleTextTrackAdd); this.handleTextTrackRemove_ = Fn.bind(this, this.handleTextTrackRemove); From 61c6cfaf848aeac6b3dfdeef19a1444978082a40 Mon Sep 17 00:00:00 2001 From: Gary Katsevman Date: Wed, 13 Apr 2016 17:35:48 -0400 Subject: [PATCH 4/8] add API, emulated tracks, and track settings sections --- docs/guides/tracks.md | 94 +++++++++++++++++++++++++++++++++++-------- 1 file changed, 78 insertions(+), 16 deletions(-) diff --git a/docs/guides/tracks.md b/docs/guides/tracks.md index a5b60e3f6f..0aa700a03a 100644 --- a/docs/guides/tracks.md +++ b/docs/guides/tracks.md @@ -1,39 +1,37 @@ -Tracks -====== +# Tracks Text Tracks are a function of HTML5 video for providing time triggered text to the viewer. Video.js makes tracks work across all browsers. There are currently five types of tracks: - **Subtitles**: Translations of the dialogue in the video for when audio is available but not understood. Subtitles are shown over the video. - **Captions**: Transcription of the dialogue, sound effects, musical cues, and other audio information for when the viewer is deaf/hard of hearing, or the video is muted. Captions are also shown over the video. - **Chapters**: Chapter titles that are used to create navigation within the video. Typically they're in the form of a list of chapters that the viewer can click on to go to a specific chapter. -- **Descriptions** (not supported yet): 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** (not supported yet): Tracks that have data meant for javascript to parse and do something with. These aren't shown to the user. +- **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. Captions and Subtitles take precedence of Descriptions when they are selected. +- **Metadata**: Tracks that have data meant for javascript to parse and do something with. These aren't shown to the user. -Creating the Text File ----------------------- +## 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. 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. -Adding to Video.js ------------------- +## 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. ```html - ``` -Subtitles from Another Domain ------------------------------ +You can also add tracks [programatically](#api). + +## 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. @@ -46,8 +44,7 @@ It can be added to the video element like so: ``` One thing to be aware of is that in this case the video files themselves will *also* needs CORS headers applied to it. Since 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 ----------------- +## Track Attributes Additional settings for track tags. ### kind @@ -62,3 +59,68 @@ NOTE: For chapters, default is required if you want the chapters menu to show. ### 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). + +## API + +### `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. + +### `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.remoteTextTrackEls() -> HTMLTrackElementList` +Another helper method, this is a list of all the `track` elements associates with the player. Both emulated or otherwise. + +### `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.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 `` element for you, or emulate that depending on whether native text tracks are supported or not. +The options available are: +* `kind` +* `label` +* `language` (also `srclang`) +* `id` +* `src` + +### `player.removeRemoteTextTrack(HTMLTrackElement|TextTrack)` +This function takes either an HTMLTrackElement or a TextTrack object and removes it from the player. + +## 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. + +If you wanted to disable native text track functionality and force video.js to use emulated text tracks always, you can supply the `nativeTextTrack` option to the tech like so: +```js +let player = videojs('myvideo', { + html5: { + nativeTextTrack: false + } +}); +``` + +### 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. + +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 + textTrackSettings: false +}); +``` +```css +/* hide the captions settings item from the captions menu */ +.vjs-texttrack-settings { + display: none; +} +``` From c8fe53f3e97d71cd4835449f9e80b66123ebac20 Mon Sep 17 00:00:00 2001 From: Gary Katsevman Date: Wed, 13 Apr 2016 17:46:08 -0400 Subject: [PATCH 5/8] Add a section about interacting with text tracks --- docs/guides/tracks.md | 45 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/docs/guides/tracks.md b/docs/guides/tracks.md index 0aa700a03a..5182123b10 100644 --- a/docs/guides/tracks.md +++ b/docs/guides/tracks.md @@ -124,3 +124,48 @@ let player = videojs('myvideo', { display: none; } ``` + +## 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(); + +for (let i = 0; i < tracks.length; i++) { + let track = tracks[i]; + + // find the captions track that's in english + 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: +```js +let tracks = player.textTracks(); +let metadataTrack; + +for (let i = 0; i < tracks.length; i++) { + let track = tracks[i]; + + // find the metadata track that's labeled ads + if (track.kind === 'captions' && track.label === 'ads') { + track.mode = 'hidden'; + // store it for usage outside of the loop + metadataTrack = track; + } +} + +metadataTrack.addEventListener('cuechange', function() { + player.ads.startLinearAdMode(); +}); +``` From e0f34c074769719a0ea0a1d4816d839c02afdc73 Mon Sep 17 00:00:00 2001 From: Gary Katsevman Date: Thu, 14 Apr 2016 15:56:31 -0400 Subject: [PATCH 6/8] minor changes --- docs/guides/tracks.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/guides/tracks.md b/docs/guides/tracks.md index 5182123b10..f234847185 100644 --- a/docs/guides/tracks.md +++ b/docs/guides/tracks.md @@ -5,7 +5,7 @@ Text Tracks are a function of HTML5 video for providing time triggered text to t - **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. Captions and Subtitles take precedence of Descriptions when they are selected. +- **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. Captions or Subtitles take precedence over Descriptions when they are selected. - **Metadata**: Tracks that have data meant for javascript to parse and do something with. These aren't shown to the user. ## Creating the Text File @@ -42,7 +42,7 @@ It can be added to the video element like so: ``` -One thing to be aware of is that in this case the video files themselves will *also* needs CORS headers applied to it. Since 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). +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. @@ -70,7 +70,7 @@ It return a TextTrackList which lists all the tracks on the player. 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.remoteTextTrackEls() -> HTMLTrackElementList` -Another helper method, this is a list of all the `track` elements associates with the player. Both emulated or otherwise. +Another helper method, this is a list of all the `track` elements associated with the player. Both emulated or otherwise. ### `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. From c6e98f503e5bdb7cd0fb3bc308a808e0f90145ed Mon Sep 17 00:00:00 2001 From: Gary Katsevman Date: Tue, 19 Apr 2016 12:14:35 -0400 Subject: [PATCH 7/8] Re-order doc --- docs/guides/tracks.md | 128 +++++++++++++++++++++--------------------- 1 file changed, 65 insertions(+), 63 deletions(-) diff --git a/docs/guides/tracks.md b/docs/guides/tracks.md index f234847185..524b788e18 100644 --- a/docs/guides/tracks.md +++ b/docs/guides/tracks.md @@ -60,37 +60,50 @@ NOTE: For chapters, default is required if you want the chapters menu to show. ### 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). -## API +## 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(); -### `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. +for (let i = 0; i < tracks.length; i++) { + let track = tracks[i]; -### `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. + // find the captions track that's in english + if (track.kind === 'captions' && track.language === 'en') { + track.mode = 'showing'; + } +} +``` -### `player.remoteTextTrackEls() -> HTMLTrackElementList` -Another helper method, this is a list of all the `track` elements associated with the player. Both emulated or otherwise. +### 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: +```js +let tracks = player.textTracks(); +let metadataTrack; -### `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. +for (let i = 0; i < tracks.length; i++) { + let track = tracks[i]; -### `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 `` 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` + // find the metadata track that's labeled ads + if (track.kind === 'captions' && track.label === 'ads') { + track.mode = 'hidden'; + // store it for usage outside of the loop + metadataTrack = track; + } +} -### `player.removeRemoteTextTrack(HTMLTrackElement|TextTrack)` -This function takes either an HTMLTrackElement or a TextTrack object and removes it from the player. +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. @@ -125,47 +138,36 @@ let player = videojs('myvideo', { } ``` -## 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(); -for (let i = 0; i < tracks.length; i++) { - let track = tracks[i]; - // find the captions track that's in english - if (track.kind === 'captions' && track.language === 'en') { - track.mode = 'showing'; - } -} -``` +## API -### 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: -```js -let tracks = player.textTracks(); -let metadataTrack; +### `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. -for (let i = 0; i < tracks.length; i++) { - let track = tracks[i]; +### `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. - // find the metadata track that's labeled ads - if (track.kind === 'captions' && track.label === 'ads') { - track.mode = 'hidden'; - // store it for usage outside of the loop - metadataTrack = track; - } -} +### `player.remoteTextTrackEls() -> HTMLTrackElementList` +Another helper method, this is a list of all the `track` elements associated with the player. Both emulated or otherwise. -metadataTrack.addEventListener('cuechange', function() { - player.ads.startLinearAdMode(); -}); -``` +### `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.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 `` element for you, or emulate that depending on whether native text tracks are supported or not. +The options available are: +* `kind` +* `label` +* `language` (also `srclang`) +* `id` +* `src` + +### `player.removeRemoteTextTrack(HTMLTrackElement|TextTrack)` +This function takes either an HTMLTrackElement or a TextTrack object and removes it from the player. From 33a7bca01a56b8c91277507165809671361354e4 Mon Sep 17 00:00:00 2001 From: Gary Katsevman Date: Tue, 19 Apr 2016 12:15:01 -0400 Subject: [PATCH 8/8] Add a Text Track Precedence section --- docs/guides/tracks.md | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/docs/guides/tracks.md b/docs/guides/tracks.md index 524b788e18..5ab6afb12a 100644 --- a/docs/guides/tracks.md +++ b/docs/guides/tracks.md @@ -5,7 +5,7 @@ Text Tracks are a function of HTML5 video for providing time triggered text to t - **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. Captions or Subtitles take precedence over Descriptions when they are selected. +- **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. ## Creating the Text File @@ -138,7 +138,18 @@ let player = videojs('myvideo', { } ``` - +## 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. ## API