--- title: Formato de pistas de texto para la web (WebVTT) slug: Web/API/WebVTT_API translation_of: Web/API/WebVTT_API ---

El formato de pistas de texto para la web (WebVTT) es un formato para mostrar pistas de texto en le tiempo (como subtítulos) usando el elemento {{HTMLElement("track")}}. El propósito principal de los archivos de WebVTT es superponer pistas de texto a un elemento {{HTMLElement("video")}}. WebVTT es un formato basado en el texto, que debe de ser codificado usando {{Glossary("UTF-8")}}. Donde puedes usar espacios también puedes usar tabulaciones. También hay una pequeña API disponible para representar y manejar estas pistas de texto y los datos necesarios para realizar la reproducción del texto en los momentos correctos.

Archivos WebVTT

El tipo MIME de los archivos WebVTT es text/vtt.

Un archivo WebVTT (.vtt) contiene apuntes, que pueden ser tanto de una línea como de varias, como se muestra debajo:

WEBVTT

00:01.000 --> 00:04.000
- Nunca bebas nitrógeno líquido.

00:05.000 --> 00:09.000
- Podría perforar tu estómago.
- Podrías morir.

NOTE Esta es la última línea en el archivo

Estructura WebVTT

La estructura de un archivo WevWTT consiste de los siguientes componentes, algunos de ellos opcionales, en este orden:

Una marca de orden de bytes (BOM) opcional.
La cadena de texto "WEBVTT".
Un encabezado de texto opcional a la derecha de WEBVTT.
- Debe haber al menos un espacio después de WEBVTT.
- Podrías usarlo para añadir una descripción al archivo.
- Puedes usar cualquier cosa en el encabezado de texto excepto saltos de línea o la cadena "-->".
Una línea en blanco, que es equivalente a dos saltos de línea consecutivos.
Cero o más apuntes o comentarios.
Cero o más líneas en blanco.

Ejemplo 1 - El archivo WebVTT más simple posible

WEBVTT

Ejemplo 2 - Archivo WebVTT muy simple con un encabezado de texto

WEBVTT - Este archivo no tiene anotaciones.

Ejemplo 3 - Ejemplo de un archivo WebVTT común con encabezado y anotaciones

WEBVTT - Este archivo tiene anotaciones.

14
00:01:14.815 --> 00:01:18.114
- ¿Qué?
- ¿Dónde estamos ahora?

15
00:01:18.171 --> 00:01:20.991
- Este es el país de los murciélagos grandes.

16
00:01:21.058 --> 00:01:23.868
- [ Murciélagos chillando ]
- Ellos no se pondrán entu pelo. Ellos están persiguiendo a los bichos.

Estructura interna de un archivo WebVTT

Vamos a reexaminar uno de nuestros ejemplos previos, y mirar la estructura de las anotaciones con un poco más de detalle.

WEBVTT

00:01.000 --> 00:04.000
- Nunca bebas nitrógeno líquido.

00:05.000 --> 00:09.000
- Podría perforar tu estómago.
- Podrías morir.

NOTE Esta es la última línea en el archivo

En el caso de cada anotación:

La primera línea se empieza con un tiempo, que es el tiempo en el que se empieza a mostrar el téxto que aparece debajo.
En la misma línea, tenemos una cadena de texto "-->".
Acabamos la línea con un segundo tiempo, que es el tiempo en el que se termina de mostrar el texto asociado.
Nosotros podemos entonces tener una o más líneas que empiezan con un guión, cada una de ellas conteniendo parte de la pista de texto para mostrar.

También podemos poner comentarios en nuestro archivo .vtt, para ayudarnos a recorddar información importante sobre las partes de nuestro archivo. Estas deben estar en líneas separadas empezando con la cadena NOTE. Aprenderas más sobre eso en la siguiente sección.

Es importante no usar líneas en blanco extras dentro de una anotación, por ejemplo entre las líneas de tiempo y las anotaciones. WebVTT está basado en líneas, una línea en blanco finalizará la anotación.

Comentarios en WebVTT

Los comentarios son un componente opcional que se puede usar para añadir informacion a un archivo WebVTT. Los comentarios estan pensados para aquellos que leen el archivo y no se muestran con las pistas de texto. Los comentarios pueden contener saltos de línea pero no una línea en blanco, que es equivalente a dos saltos de línea consecutivos. Una línea en blanco indica el fin de un comentario.

Un comentario no puede contener la cadena de texto "-->", el símbolo &, o el signo de menor que (<). Si quisieses usar esos caracteres necesitarías hacer un escape usando por ejemplo & para el símbolo &, y < para menor que (<). Tambien es recomendado que uses la secuencia de escape de mayor que > en vez de el simbo de mayor que (>) para evitar la confusión con etiquetas.

Un comentario consiste en tres partes:

La cadena de texto NOTE.
Un espacio o un salto de línea.
Cero o más caracteres que no sean los indicados arriba.

Ejemplo 4 - Ejemplo común de WebVTT

NOTE Esto es un comentario

Ejemplo 5 - Comentario multilínea

NOTE
Un comentario que está ocupando
más de una línea.

NOTE También puedes hacer un comentario
que ocupe más de una línea de esta manera.

Ejemplo 6 - Uso común de comentarios

WEBVTT - Traducción de la película que me gusta

NOTE
Esta traducción esta hecha por Kyle para que
Algunos amigos puedan verla con sus padres.

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 Esta ultima línea puede no estar bien traducida.

3
00:02:25.000 --> 00:02:30.000
- Ta en kopp

Estilizando anotaciones WebVTT

Tu puedes estilizar anotaciones WebVTT buscado elementos que coincidan con el pseudoelemento {{cssxref("::cue")}}.

Dentro del CSS del sitio

video::cue {
  background-image: linear-gradient(to bottom, dimgray, lightgray);
  color: papayawhip;
}

video::cue(b) {
  color: peachpuff;
}

Aquí, todos los elementos de video estan estilizados para usar un gradiente gris como fondo, con "papayawhip" como color principal. Además el texto en negrita usando el elemento {{HTMLElement("b")}} tiene el color "peachpuff".

El ejemplo HTML de abajo actualemte se encarga de mostrar los archivos multimedia él solo.

<video controls autoplay src="video.webm">
 <track default src="track.vtt">
</video>

Within the WebVTT file itself

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?

WebVTT cues

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:

An optional cue identifier followed by a newline.
Cue timings.
Optional cue settings with at least one space before the first and between each setting.
One or more newlines.
The cue payload text.

Example 7 - Example of a cue

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....

Cue identifier

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, ...).

Example 8 - Cue identifier from Example 7

1 - Title Crawl

Example 9 - Common usage of identifiers

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

Cue timings

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:

Timestamp for start time.
At least one space.
The string "-->".
At least one space.
Timestamp for end time.
- Which must be greater than the start time.

The timestamps must be in one of two formats:

mm:ss.ttt
hh:mm:ss.ttt

Where the components are defined as follows:

hh is hours.
- Must be at least two digits.
- Hours can be greater than two digits (e.g., 9999:00:00.000).
mm is minutes.
- Must be between 00 and 59 inclusive.
ss is seconds.
- Must be between 00 and 59 inclusive.
ttt is miliseconds.
- Must be between 000 and 999 inclusive.

Example 10 - Basic cue timing examples

00:00:22.230 --> 00:00:24.606
00:00:30.739 --> 00:00:34.074
00:00:34.159 --> 00:00:35.743
00:00:35.827 --> 00:00:40.122

Example 11 - Overlapping cue timing examples

00:00:00.000 --> 00:00:10.000
00:00:05.000 --> 00:01:00.000
00:00:30.000 --> 00:00:50.000

Example 12 - Non-overlapping cue timing examples

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

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:

vertical
- Indicates that the text will be displayed vertically rather than horizontally, such as in some Asian languages.
Table 1 - vertical values

vertical:rl writing direction is right to left

vertical:lr writing direction is left to right

Table 1 - vertical values
`vertical:rl`	writing direction is right to left
`vertical:lr`	writing direction is left to right

line

Specifies where text appears vertically. If vertical is set, line specifies where text appears horizontally.
Value can be a line number.
- The line height is the height of the first line of the cue as it appears on the video.
- Positive numbers indicate top down.
- Negative numbers indicate bottom up.
Or value can be a percentage.
- Must be an integer (i.e., no decimals) between 0 and 100 inclusive.
- Must be followed by a percent sign (%).

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

position

Specifies where the text will appear horizontally. If vertical is set, position specifies where the text will appear vertically.
Value is a percentage.
Must be an integer (no decimals) between 0 and 100 inclusive.
Must be followed by a percent sign (%).

Table 3 - position examples
	`vertical` omitted	`vertical:rl`	`vertical:lr`
`position:0%`	left	top	top
`position:100%`	right	bottom	bottom

size

Specifies the width of the text area. If vertical is set, size specifies the height of the text area.
Value is a percentage.
Must be an integer (i.e., no decimals) between 0 and 100 inclusive.
Must be followed by a percent sign (%).

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

align

Specifies the alignment of the text. Text is aligned within the space given by the size cue setting if it is set.

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

Example 13 - Cue setting examples

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

Cue payload

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		`&lrm;`
Right-to-left mark		`&rlm;`
Non-breaking space		` `

Cue payload text tags

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.

Timestamp tag
- The timestamp must be greater that the cue's start timestamp, greater than any previous timestamp in the cue payload, and less than the cue's end timestamp. The active text is the text between the timestamp and the next timestamp or to the end of the payload if there is not another timestamp in the payload. Any text before the active text in the payload is previous text . Any text beyond the active text is future text . This enables karaoke style captions.
Example 12 - Karaoke style text
```
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., text).

Class tag (<c></c>)
- Style the contained text using a CSS class.
Example 14 - Class tag
```
<c.classname>text</c>
```
Italics tag ()
- Italicize the contained text.
Example 15 - Italics tag
```
text
```
Bold tag ()
- Bold the contained text.
Example 16 - Bold tag
```
text
```
Underline tag ()
- Underline the contained text.
Example 17 - Underline tag
```
text
```
Ruby tag (<ruby></ruby>)
- Used with ruby text tags to display ruby characters (i.e., small annotative characters above other characters).
Example 18 - Ruby tag
```
<ruby>WWW<rt>World Wide Web</rt>oui<rt>yes</rt></ruby>
```
Ruby text tag (<rt></rt>)
- Used with ruby tags to display ruby characters (i.e., small annotative characters above other characters).
Example 19 - Ruby text tag
```
<ruby>WWW<rt>World Wide Web</rt>oui<rt>yes</rt></ruby>
```
Voice tag (<v></v>)
- Similar to class tag, also used to style the contained text using CSS.
Example 20 - Voice tag
```
<v Bob>text</v>
```

Interfaces

There are two interfaces or APIs used in WebVTT which are:

VTTCue interface

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();
};

VTT Region interface

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;
};

Methods and properties

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:

VTTCue
- The methods which are available in this interface are:
  - GetCueAsHTML to get the HTML of that Cue.
  - VTT Constructor for creating new objects of Cues.
  - Autokeyword.
  - DirectionSetting: to set the direction of caption or text in a file.
  - LineAlignment: to adjust the line alignment.
  - PositionAlignSetting: to adjust the position of text.
VTTRegion
- The methods used for region are listed below along with description of their functionality:
  - ScrollSetting: For adjusting the scrolling setting of all nodes present in given region.
  - VTT Region Constructor: for construction of new VTT Regions.

Tutorial on how to write a WebVTT file

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:

Open a notepad.
The first line of WebVTT is standardized similar to the way some other languages require you to put headers as the file starts to indicate the file type. On the very first line you have to write:

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

On the next line you can write the caption for this cue which will run from 1^st second to the 5^th second, inclusive.
Following the similar steps, a complete WebVTT file for specific video or audio file can be made.

CSS pseudo-classes

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  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:

Lang (Lanugage): e.g., p:lang(it).
Link: e.g., a:link.
Nth-last-child: e.g., p:nth-last-child(2).
Nth-child(n): e.g., p:nth-child(2).

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.

Specifications

Specification	Status	Comment
{{SpecName("WebVTT")}}	{{Spec2("WebVTT")}}	Initial definition

Browser compatibility

`VTTCue` interface

`TextTrack` interface

Notes

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)}}).

Archivos WebVTT

Estructura WebVTT

Ejemplo 1 - El archivo WebVTT más simple posible

Ejemplo 2 - Archivo WebVTT muy simple con un encabezado de texto

Ejemplo 3 - Ejemplo de un archivo WebVTT común con encabezado y anotaciones

Estructura interna de un archivo WebVTT

Comentarios en WebVTT

Ejemplo 4 - Ejemplo común de WebVTT

Ejemplo 5 - Comentario multilínea

Ejemplo 6 - Uso común de comentarios

Estilizando anotaciones WebVTT

Dentro del CSS del sitio

Within the WebVTT file itself

WebVTT cues

Example 7 - Example of a cue

Cue identifier

Example 8 - Cue identifier from Example 7

Example 9 - Common usage of identifiers

Cue timings

Example 10 - Basic cue timing examples

Example 11 - Overlapping cue timing examples

Example 12 - Non-overlapping cue timing examples

Cue settings

Example 13 - Cue setting examples

Cue payload

Cue payload text tags

Example 12 - Karaoke style text

Example 14 - Class tag

Example 15 - Italics tag

Example 16 - Bold tag

Example 17 - Underline tag

Example 18 - Ruby tag

Example 19 - Ruby text tag

Example 20 - Voice tag

Interfaces

VTTCue interface

VTT Region interface

Methods and properties

VTTCue

VTTRegion

Tutorial on how to write a WebVTT file

CSS pseudo-classes

Specifications

Browser compatibility

VTTCue interface

TextTrack interface

Notes

`VTTCue` interface

`TextTrack` interface