Формат Web Video Text Tracks (WebVTT)это формат для отображения синхронизированных текстовых треков (такие как субтитры или подписи) с помощью элементов {{HTMLElement("track")}}. Основная цель файлов WebVTT — добавить текстовые наложения к элементам {{HTMLElement("video")}}. WebVTT является текстовым форматом, который должен быть закодирован с использованием {{Glossary("UTF-8")}}. В этих файлах вы можете использовать пробелы и табы для отступов. Существует также небольшой API для представления и управления этими дорожками и данными, необходимыми для отображения текста в нужное время.
MIME тип файлов WebVTT — text/vtt.
Файл WebVTT (.vtt) содержит реплики (cues), которые могут быть одной строкой или несколькими строками, как показано ниже:
WEBVTT 00:01.000 --> 00:04.000 Никогда не пейте жидкий азот. 00:05.000 --> 00:09.000 - Это пробьёт ваш желудок. - Вы можете умереть.
Структура WebVTT состоит из следующих компонентов, некоторые из которых являются необязательными, в следующем порядке:
WEBVTT".WEBVTT.
WEBVTT.-->".WEBVTT
WEBVTT - Этот файл не содержит реплик.
WEBVTT - Этот файл содержит реплики. 14 00:01:14.815 --> 00:01:18.114 - Что? - Где мы сейчас? 15 00:01:18.171 --> 00:01:20.991 - Это большая страна летучих мышей. 16 00:01:21.058 --> 00:01:23.868 - [ Визг летучих мышей ] - Они не попадут в твои волосы. They're after the bugs.
Давайте вернёмся к одному из наших предыдущих примеров и рассмотрим структуру реплик более подробно.
WEBVTT 00:01.000 --> 00:04.000 - Never drink liquid nitrogen. 00:05.000 --> 00:09.000 - It will perforate your stomach. - You could die. NOTE Это последняя строка в файле
В данном случае каждая реплика:
-->.Мы также можем разместить комментарии в нашем файле .vtt, чтобы помочь нам запомнить важную информацию о частях нашего файла. Они должны быть в отдельных строках, начинающихся со слова NOTE. Подробнее об этом сказано в следующем разделе.
Важно не использовать дополнительные пустые строки в реплике, например, между строкой синхронизации и текстом реплики. WebVTT использует строчные разделители, поэтому пустая строка обозначит окончание реплики.
Comments are an optional component that can be used to add information to a WebVTT file. Comments are intended for those reading the file and are not seen by users. Comments may contain newlines but cannot contain a blank line, which is equivalent to two consecutive newlines. A blank line signifies the end of a comment.
A comment cannot contain the string "-->", the ampersand character (&), or the less-than sign (<). If you wish to use such characters, you need to escape them using for example & for ampersand and < for less-than. It is also recommended that you use the greater-than escape sequence (>) instead of the greater-than character (>) to avoid confusion with tags.
A comment consists of three parts:
NOTE.NOTE This is a comment
NOTE Another comment that is spanning more than one line. NOTE You can also make a comment across more than one line this way.
WEBVTT - Translation of that film I like NOTE This translation was done by Kyle so that some friends can watch it with their parents. 1 00:02:15.000 --> 00:02:20.000 - Ta en kopp varmt te. - Det är inte varmt. 2 00:02:20.000 --> 00:02:25.000 - Har en kopp te. - Det smakar som te. NOTE This last line may not translate well. 3 00:02:25.000 --> 00:02:30.000 - Ta en kopp
Реплики WebVTT можно стилизовать, используя псевдоэлемент {{cssxref("::cue")}}.
video::cue {
background-image: linear-gradient(to bottom, dimgray, lightgray);
color: papayawhip;
}
video::cue(b) {
color: peachpuff;
}
В данном примере фоном видео будет серый градиент, с цветом текста papayawhip. Также, текст, выделенный жирным шрифтом с помощью элемента {{HTMLElement("b")}}, имеет цвет peachpuff.
Фрагмент HTML, приведённый ниже, отображает видео.
<video controls autoplay src="video.webm"> <track default src="track.vtt"> </video>
You can also define the style directly in the WebVTT file. In this case, you insert your CSS rules into the file with each rule preceded by the string "STYLE" all by itelf on a line of text, as shown below:
WEBVTT
STYLE
::cue {
background-image: linear-gradient(to bottom, dimgray, lightgray);
color: papayawhip;
}
/* Style blocks cannot use blank lines nor "dash dash greater than" */
NOTE comment blocks can be used between style blocks.
STYLE
::cue(b) {
color: peachpuff;
}
00:00:00.000 --> 00:00:10.000
- Hello <b>world</b>.
NOTE style blocks cannot appear after the first cue.
We can also use identifiers inside WebVTT file, which can be used for defining a new style for some particular cues in the file. The example where we wanted the transcription text to be red highlighted and the other part to remain normal, we can define it as follows using CSS. Where it must be noted that the CSS uses escape sequences the way they are used in HTML pages:
WEBVTT 1 00:00.000 --> 00:02.000 That’s an, an, that’s an L! crédit de transcription 00:04.000 --> 00:05.000 Transcrit par Célestes™
::cue(#\31) { color: lime; }
::cue(#crédit\ de\ transcription) { color: red; }
Positioning of text tracks is also supported, by including positioning information after the timings in a cue, as seen below (see {{anch("Cue settings")}} for more information):
WEBVTT 00:00:00.000 --> 00:00:04.000 position:10%,line-left align:left size:35% Where did he go? 00:00:03.000 --> 00:00:06.500 position:90% align:right size:35% I think he went down this lane. 00:00:04.000 --> 00:00:06.500 position:45%,line-right align:center size:35% What are you waiting for?
A cue is a single subtitle block that has a single start time, end time, and textual payload. Example 6 consists of the header, a blank line, and then five cues separated by blank lines. A cue consists of five components:
1 - Title Crawl 00:00:05.000 --> 00:00:10.000 line:0 position:20% size:60% align:start Some time ago in a place rather distant....
The identifier is a name that identifies the cue. It can be used to reference the cue from a script. It must not contain a newline and cannot contain the string "-->". It must end with a single newline. They do not have to be unique, although it is common to number them (e.g., 1, 2, 3, ...).
1 - Title Crawl
WEBVTT 1 00:00:22.230 --> 00:00:24.606 This is the first subtitle. 2 00:00:30.739 --> 00:00:34.074 This is the second. 3 00:00:34.159 --> 00:00:35.743 Third
A cue timing indicates when the cue is shown. It has a start and end time which are represented by timestamps. The end time must be greater than the start time, and the start time must be greater than or equal to all previous start times. Cues may have overlapping timings.
If the WebVTT file is being used for chapters ({{HTMLElement("track")}} {{htmlattrxref("kind")}} is chapters) then the file cannot have overlapping timings.
Each cue timing contains five components:
-->".The timestamps must be in one of two formats:
mm:ss.ttthh:mm:ss.tttWhere the components are defined as follows:
hh is hours.
mm is minutes.
ss is seconds.
ttt is miliseconds.
00:22.230 --> 00:24.606 00:30.739 --> 00:00:34.074 00:00:34.159 --> 00:35.743 00:00:35.827 --> 00:00:40.122
00:00:00.000 --> 00:00:10.000 00:00:05.000 --> 00:01:00.000 00:00:30.000 --> 00:00:50.000
00:00:00.000 --> 00:00:10.000 00:00:10.000 --> 00:01:00.581 00:01:00.581 --> 00:02:00.100 00:02:01.000 --> 00:02:01.000
Cue settings are optional components used to position where the cue payload text will be displayed over the video. This includes whether the text is displayed horizontally or vertically. There can be zero or more of them, and they can be used in any order so long as each setting is used no more than once.
The cue settings are added to the right of the cue timings. There must be one or more spaces between the cue timing and the first setting and between each setting. A setting's name and value are separated by a colon. The settings are case sensitive so use lower case as shown. There are five cue settings:
| Table 1 - vertical values | |
|---|---|
vertical:rl |
writing direction is right to left |
vertical:lr |
writing direction is left to right |
| Table 2 - line examples | |||
|---|---|---|---|
vertical omitted |
vertical:rl |
vertical:lr |
|
line:0 |
top | right | left |
line:-1 |
bottom | left | right |
line:0% |
top | right | left |
line:100% |
bottom | left | right |
| Table 3 - position examples | |||
|---|---|---|---|
vertical omitted |
vertical:rl |
vertical:lr |
|
position:0% |
left | top | top |
position:100% |
right | bottom | bottom |
| Table 4 - size examples | |||
|---|---|---|---|
vertical omitted |
vertical:rl |
vertical:lr |
|
size:100% |
full width | full height | full height |
size:50% |
half width | half height | half height |
| Table 5 - align values | |||
|---|---|---|---|
vertical omitted |
vertical:rl |
vertical:lr |
|
align:start |
left | top | top |
align:middle |
centred horizontally | centred vertically | centred vertically |
align:end |
right | bottom | bottom |
The first line demonstrates no settings. The second line might be used to overlay text on a sign or label. The third line might be used for a title. The last line might be used for an Asian language.
00:00:05.000 --> 00:00:10.000 00:00:05.000 --> 00:00:10.000 line:63% position:72% align:start 00:00:05.000 --> 00:00:10.000 line:0 position:20% size:60% align:start 00:00:05.000 --> 00:00:10.000 vertical:rt line:-1 align:end
The payload is where the main information or content is located. In normal usage the payload contains the subtitles to be displayed. The payload text may contain newlines but it cannot contain a blank line, which is equivalent to two consecutive newlines. A blank line signifies the end of a cue.
A cue text payload cannot contain the string "-->", the ampersand character (&), or the less-than sign (<). Instead use the escape sequence "&" for ampersand and "<" for less-than. It is also recommended that you use the greater-than escape sequence ">" instead of the greater-than character (>) to avoid confusion with tags. If you are using the WebVTT file for metadata these restrictions do not apply.
In addition to the three escape sequences mentioned above, there are fours others. They are listed in the table below.
| Table 6 - Escape sequences | ||
|---|---|---|
| Name | Character | Escape Sequence |
| Ampersand | & | & |
| Less-than | < | < |
| Greater-than | > | > |
| Left-to-right mark | ‎ |
|
| Right-to-left mark | ‏ |
|
| Non-breaking space | |
|
There are a number of tags, such as <bold>, that can be used. However, if the WebVTT file is used in a {{HTMLElement("track")}} element where the attribute {{htmlattrxref("kind")}} is chapters then you cannot use tags.
1 00:16.500 --> 00:18.500 When the moon <00:17.500>hits your eye 1 00:00:18.500 --> 00:00:20.500 Like a <00:19.000>big-a <00:19.500>pizza <00:20.000>pie 1 00:00:20.500 --> 00:00:21.500 That's <00:00:21.000>amore
The following tags are the HTML tags allowed in a cue and require opening and closing tags (e.g., <b>text</b>).
<c></c>)
<c.classname>text</c>
<i></i>)
<i>text</i>
<b></b>)
<b>text</b>
<u></u>)
<u>text</u>
<ruby></ruby>)
<ruby>WWW<rt>World Wide Web</rt>oui<rt>yes</rt></ruby>
<rt></rt>)
<ruby>WWW<rt>World Wide Web</rt>oui<rt>yes</rt></ruby>
<v></v>)
<v Bob>text</v>
There are two interfaces or APIs used in WebVTT which are:
It is used for providing an interface in Document Object Model API, where different attributes supported by it can be used to prepare and alter the cues in number of ways.
Constructor is the first point for starting the Cue which is defined using the default constructor VTTCue(startTime, endTime, text) where starting time, ending time and text for cue can be adjusted. After that we can set the region for that particular cue to which this cue belongs using cue.region. Vertical, horizontal, line, lineAlign, Position, positionAlign, text, size and Align can be used to alter the cue and its formation, just like we can alter the objects form, shape and visibility in HTML using CSS. But the VTTCue interface is within the WebVTT provides the vast range of adjustment variables which can be used directly to alter the Cue. Following interface can be used to expose WebVTT cues in DOM API:
enum AutoKeyword { "auto" };
enum DirectionSetting { "" /* horizontal */, "rl", "lr" };
enum LineAlignSetting { "start", "center", "end" };
enum PositionAlignSetting { "line-left", "center", "line-right", "auto" };
enum AlignSetting { "start", "center", "end", "left", "right" };
[Constructor(double startTime, double endTime, DOMString text)]
interface VTTCue : TextTrackCue {
attribute VTTRegion? region;
attribute DirectionSetting vertical;
attribute boolean snapToLines;
attribute (double or AutoKeyword) line;
attribute LineAlignSetting lineAlign;
attribute (double or AutoKeyword) position;
attribute PositionAlignSetting positionAlign;
attribute double size;
attribute AlignSetting align;
attribute DOMString text;
DocumentFragment getCueAsHTML();
};
This is the second interface in WebVTT API.
The new keyword can be used for defining a new VTTRegion object which can then be used for containing the multiple cues. There are several properties of VTTRegion which are width, lines, regionAnchorX, RegionAnchorY, viewportAnchorX, viewportAnchorY and scroll that can be used to specify the look and feel of this VTT region. The interface code is given below which can be used to expose the WebVTT regions in DOM API:
enum ScrollSetting { "" /* none */, "up" };
[Constructor]
interface VTTRegion {
attribute double width;
attribute long lines;
attribute double regionAnchorX;
attribute double regionAnchorY;
attribute double viewportAnchorX;
attribute double viewportAnchorY;
attribute ScrollSetting scroll;
};
The methods used in WebVTT are those which are used to alter the cue or region as the attributes for both interfaces are different. We can categorize them for better understanding relating to each interface in WebVTT:
There are few steps that can be followed to write a simple webVTT file. Before start, it must be noted that you can make use of a notepad and then save the file as ‘.vtt’ file. Steps are given below:
WEBVTT
3. Leave the second line blank, and on the third line the time for first cue is to be specified. For example, for a first cue starting at time 1 second and ending at 5 seconds, it is written as:
00:01.000 --> 00:05.000
CSS pseudo classes allow us to classify the type of object which we want to differentiate from other types of objects. It works in similar manner in WebVTT files as it works in HTML file.
It is one of the good features supported by WebVTT is the localization and use of class elements which can be used in same way they are used in HTML and CSS to classify the style for particular type of objects, but here these are used for styling and classifying the Cues as shown below:
WEBVTT 04:02.500 --> 04:05.000 J’ai commencé le basket à l'âge de 13, 14 ans 04:05.001 --> 04:07.800 Sur les <i.foreignphrase><lang en>playground</lang></i>, ici à Montpellier
In the above example it can be observed that we can use the identifier and pseudo class name for defining the language of caption, where <i> tag is for italics.
The type of pseudo class is determined by the selector it is using and working is similar in nature as it works in HTML. Following CSS pseudo classes can be used:
Where p and a are the tags which are used in HTML for paragraph and link, respectively and they can be replaced by identifiers which are used for Cues in WebVTT file.
| Specification | Status | Comment |
|---|---|---|
| {{SpecName("WebVTT")}} | {{Spec2("WebVTT")}} | Initial definition |
VTTCue interface{{Compat("api.VTTCue", 0)}}
TextTrack interface{{Compat("api.TextTrack", 0)}}
Prior to Firefox 50, the AlignSetting enum (representing possible values for {{domxref("VTTCue.align")}}) incorrectly included the value "middle" instead of "center". This has been corrected.
WebVTT was implemented in Firefox 24 behind the preference {{pref("media.webvtt.enabled")}}, which is disabled by default; you can enable it by setting this preference to true. WebVTT is enabled by default starting in Firefox 31 and can be disabled by setting the preference to false.
Prior to Firefox 58, the REGION keyword was creating {{domxref("VTTRegion")}} objects, but they were not being used. Firefox 58 now fully supports VTTRegion and its use; however, this feature is disabled by default behind the preference media.webvtt.regions.enabled; set it to true to enable region support in Firefox 58. Regions are enabled by default starting in Firefox 59 (see bugs {{bug(1338030)}} and {{bug(1415805)}}).