aboutsummaryrefslogtreecommitdiff
path: root/files/zh-cn/web/api/webvtt_api/index.html
blob: 9316bee752f7068e5dd04d1794ea19dd64d54fe7 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
---
title: Web 视频文本轨格式(WebVTT)
slug: Web/API/WebVTT_API
tags:
  - API
  - Media
  - NeedsMarkupWork
  - NeedsUpdate
  - WebVTT
  - 参考
  - 多媒体
  - 字幕
  - 视频
translation_of: Web/API/WebVTT_API
---
<div>{{DefaultAPISidebar("WebVTT")}}</div>

<p><span class="seoSummary"><strong>Web视频文本跟踪格式 </strong>(<strong>WebVTT</strong>) 是一种使用{{HTMLElement("track")}}元素显示定时文本轨道(如字幕或标题)的格式。 WebVTT文件的主要用途是将文本叠加添加到{{HTMLElement("video")}}。 WebVTT是一种基于文本的格式,必须使用{{Glossary("UTF-8")}}进行编码。 在可以使用空格的地方,您也可以使用制表符。 还有一个小的API可用于表示和管理这些轨道以及在正确的时间执行文本回放所需的数据。</span></p>

<h2 id="WebVTT_文件">WebVTT 文件</h2>

<p>WebVTT 文件的 MIME 类型为 <code>text/vtt</code></p>

<p>一个 WebVTT 文件(<code>.vtt</code>) 包含任意条<u>带时间的提示性内容</u><u>cue</u>)(可理解为一条或多条字幕),可以是单行或多行,如下所示:</p>

<pre>WEBVTT

00:01.000 --&gt; 00:04.000
Never drink liquid nitrogen. 别喝液氮。

00:05.000 --&gt; 00:09.000
- 它会刺穿你的胃。
- It will perforate your stomach.
- 你可能会因此挂掉。
- You could die.
</pre>

<h2 id="WebVTT_文件内容">WebVTT 文件内容</h2>

<p>一个 WebVTT 文件的内容由以下部分组成,其中一些是可选的,依次为:</p>

<ul>
 <li>一个可选的字节顺序标记(BOM)。</li>
 <li>字符串 "<code>WEBVTT</code>"。</li>
 <li>An optional text header to the right of <code>WEBVTT.</code>
  <ul>
   <li>There must be at least one space after <code>WEBVTT.</code></li>
   <li>You could use this to add a description to the file.</li>
   <li>You may use anything in the text header except newlines or the string "<code>--&gt;</code>".</li>
  </ul>
 </li>
 <li>A blank line, which is equivalent to two consecutive newlines.</li>
 <li>任意数量的 cue 或备注。</li>
 <li>任意数量的空行。</li>
</ul>

<h5 id="例子_1_-_最简形式的_WEBVTT_文件">例子 1 - 最简形式的 WEBVTT 文件</h5>

<pre class="eval">WEBVTT
</pre>

<h5 id="例子_2_-_仅有_text_header_的_WebVTT_文件">例子 2 - 仅有 text header 的 WebVTT 文件</h5>

<pre class="eval">WEBVTT - This file has no cues.
</pre>

<h5 id="例子_3_-_拥有_header_和_cue_的_WebVTT_文件示例">例子 3 - 拥有 header 和 cue 的 WebVTT 文件示例</h5>

<pre class="eval">WEBVTT - This file has cues.

14
00:01:14.815 --&gt; 00:01:18.114
- What?
- Where are we now?

15
00:01:18.171 --&gt; 00:01:20.991
- This is big bat country.

16
00:01:21.058 --&gt; 00:01:23.868
- [ Bats Screeching ]
- They won't get in your hair. They're after the bugs.
</pre>

<h3 id="一个_WebVTT_文件的内部结构">一个 WebVTT 文件的内部结构</h3>

<p>让我们重新检查前面的一个示例,并更详细地研究线索结构。</p>

<pre>WEBVTT

00:01.000 --&gt; 00:04.000
- Never drink liquid nitrogen.

00:05.000 --&gt; 00:09.000
- It will perforate your stomach.
- You could die.

NOTE This is the last line in the file</pre>

<p>In the case of each cue:</p>

<ul>
 <li>第一行以时间开始,时间是显示下面出现的文本的开始时间。</li>
 <li>在同一行,我们有一个字符串<code>--&gt;</code></li>
 <li>我们用第二次结束第一行,这是显示关联文本的结束时间。</li>
 <li>然后,我们可以有一个或多个以连字符(-)开头的行,每个行包含要显示的文本跟踪的一部分。</li>
</ul>

<p>我们还可以在.vtt文件中放置注释,以帮助我们记住关于文件各部分的重要信息。这些应该在单独的行上,从字符串NOTE开始。您将在下一节中找到更多关于这些的信息。</p>

<p>重要的是不要在提示中使用“额外的”空白行,例如在计时行和提示有效负载之间。WebVTT是基于行;空白行将关闭提示。</p>

<h2 id="WebVTT_注释">WebVTT 注释</h2>

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

<p>A comment cannot contain the string "<code>--&gt;",</code> the ampersand character (&amp;), or the less-than sign (&lt;). If you wish to use such characters, you need to escape them using for example <code>&amp;amp;</code> for ampersand and <code>&amp;lt;</code> for less-than. It is also recommended that you use the greater-than escape sequence (<code>&amp;gt;</code>) instead of the greater-than character (<code>&gt;</code>) to avoid confusion with tags.</p>

<p>A comment consists of three parts:</p>

<ul>
 <li>The string <code>NOTE.</code></li>
 <li>A space or a newline.</li>
 <li>Zero or more characters other than those noted above.</li>
</ul>

<h5 id="Example_4_-_单行_WebVTT_注释">Example 4 - 单行 WebVTT 注释</h5>

<pre class="eval">NOTE This is a comment
</pre>

<h5 id="Example_5_-_多行注释">Example 5 - 多行注释</h5>

<pre class="eval">NOTE
Another comment that is spanning
more than one line.

NOTE You can also make a comment
across more than one line this way.
</pre>

<h5 id="Example_6_-_普通注释">Example 6 - 普通注释</h5>

<pre class="eval">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 --&gt; 00:02:20.000
- Ta en kopp varmt te.
- Det är inte varmt.

2
00:02:20.000 --&gt; 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 --&gt; 00:02:30.000
- Ta en kopp
</pre>

<h2 id="Styling_WebVTT_cues">Styling WebVTT cues</h2>

<p>You can style WebVTT cues by looking for elements which match the {{cssxref("::cue")}} pseudo-element.</p>

<h3 id="Within_site_CSS">Within site CSS</h3>

<pre class="brush: css">video::cue {
  background-image: linear-gradient(to bottom, dimgray, lightgray);
  color: papayawhip;
}

video::cue(b) {
  color: peachpuff;
}
</pre>

<p>Here, all video elements are styled to use a gray linear gradient as their backgrounds, with a foreground color of <code>"papayawhip"</code>. In addition, text boldfaced using the {{HTMLElement("b")}} element are colored <code>"peachpuff"</code>.</p>

<p>The HTML snippet below actually handles displaying the media itself.</p>

<pre class="brush: html">&lt;video controls autoplay src="video.webm"&gt;
 &lt;track default src="track.vtt"&gt;
&lt;/video&gt;
</pre>

<h3 id="Within_the_WebVTT_file_itself">Within the WebVTT file itself</h3>

<p>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 <code>"STYLE"</code> all by itelf on a line of text, as shown below:</p>

<pre>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 --&gt; 00:00:10.000
- Hello &lt;b&gt;world&lt;/b&gt;.

NOTE style blocks cannot appear after the first cue.</pre>

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

<pre>WEBVTT

1
00:00.000 --&gt; 00:02.000
That’s an, an, that’s an L!

crédit de transcription
00:04.000 --&gt; 00:05.000
Transcrit par Célestes™
</pre>

<pre class="brush: css">::cue(#\31) { color: lime; }
::cue(#crédit\ de\ transcription) { color: red; }</pre>

<p>Positioning of text tracks is also supported, by including positioning information after the timings in a cue, as seen below (see <a href="#cue_settings">Cue settings</a> for more information):</p>

<pre>WEBVTT

00:00:00.000 --&gt; 00:00:04.000 position:10%,line-left align:left size:35%
Where did he go?

00:00:03.000 --&gt; 00:00:06.500 position:90% align:right size:35%
I think he went down this lane.

00:00:04.000 --&gt; 00:00:06.500 position:45%,line-right align:center size:35%
What are you waiting for?</pre>

<h2 id="WebVTT_cues">WebVTT cues</h2>

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

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

<h5 id="Example_7_-_Example_of_a_cue">Example 7 - Example of a cue</h5>

<pre class="eval">1 - Title Crawl
00:00:05.000 --&gt; 00:00:10.000 line:0 position:20% size:60% align:start
Some time ago in a place rather distant....</pre>

<h3 id="Cue_identifier">Cue identifier</h3>

<p>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 "<code>--&gt;"</code>. 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, ...).</p>

<h5 id="Example_8_-_Cue_identifier_from_Example_7">Example 8 - Cue identifier from Example 7</h5>

<pre class="eval">1 - Title Crawl</pre>

<h5 id="Example_9_-_Common_usage_of_identifiers">Example 9 - Common usage of identifiers</h5>

<pre class="eval">WEBVTT

1
00:00:22.230 --&gt; 00:00:24.606
This is the first subtitle.

2
00:00:30.739 --&gt; 00:00:34.074
This is the second.

3
00:00:34.159 --&gt; 00:00:35.743
Third
</pre>

<h3 id="Cue_timings">Cue timings</h3>

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

<p>If the WebVTT file is being used for chapters ({{HTMLElement("track")}} {{htmlattrxref("kind")}} is <code>chapters</code>) then the file cannot have overlapping timings.</p>

<p>Each cue timing contains five components:</p>

<ul>
 <li>Timestamp for start time.</li>
 <li>At least one space.</li>
 <li>The string "<code>--&gt;".</code></li>
 <li>At least one space.</li>
 <li>Timestamp for end time.
  <ul>
   <li>Which must be greater than the start time.</li>
  </ul>
 </li>
</ul>

<p>The timestamps must be in one of two formats:</p>

<ul>
 <li><code>mm:ss.ttt</code></li>
 <li><code>hh:mm:ss.ttt</code></li>
</ul>

<p>Where the components are defined as follows:</p>

<ul>
 <li><code>hh</code> is hours.

  <ul>
   <li>Must be at least two digits.</li>
   <li>Hours can be greater than two digits (e.g., 9999:00:00.000).</li>
  </ul>
 </li>
 <li><code>mm</code> is minutes.
  <ul>
   <li>Must be between 00 and 59 inclusive.</li>
  </ul>
 </li>
 <li><code>ss</code> is seconds.
  <ul>
   <li>Must be between 00 and 59 inclusive.</li>
  </ul>
 </li>
 <li><code>ttt</code> is miliseconds.
  <ul>
   <li>Must be between 000 and 999 inclusive.</li>
  </ul>
 </li>
</ul>

<h5 id="Example_10_-_Basic_cue_timing_examples">Example 10 - Basic cue timing examples</h5>

<pre class="eval">00:22.230 --&gt; 00:24.606
00:30.739 --&gt; 00:00:34.074
00:00:34.159 --&gt; 00:35.743
00:00:35.827 --&gt; 00:00:40.122</pre>

<h5 id="Example_11_-_Overlapping_cue_timing_examples">Example 11 - Overlapping cue timing examples</h5>

<pre class="eval">00:00:00.000 --&gt; 00:00:10.000
00:00:05.000 --&gt; 00:01:00.000
00:00:30.000 --&gt; 00:00:50.000</pre>

<h5 id="Example_12_-_Non-overlapping_cue_timing_examples">Example 12 - Non-overlapping cue timing examples</h5>

<pre class="eval">00:00:00.000 --&gt; 00:00:10.000
00:00:10.000 --&gt; 00:01:00.581
00:01:00.581 --&gt; 00:02:00.100
00:02:01.000 --&gt; 00:02:01.000</pre>

<h3 id="Cue_settings">Cue settings</h3>

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

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

<ul>
 <li><strong>vertical</strong>

  <ul>
   <li>Indicates that the text will be displayed vertically rather than horizontally, such as in some Asian languages.</li>
  </ul>

  <table>
   <thead>
    <tr>
     <th colspan="2">Table 1 - vertical values</th>
    </tr>
   </thead>
   <tbody>
    <tr>
     <th><code>vertical:rl</code></th>
     <td>writing direction is right to left</td>
    </tr>
    <tr>
     <th><code>vertical:lr</code></th>
     <td>writing direction is left to right</td>
    </tr>
   </tbody>
  </table>
 </li>
 <li><strong>line</strong>
  <ul>
   <li>Specifies where text appears vertically. If vertical is set, line specifies where text appears horizontally.</li>
   <li>Value can be a line number.
    <ul>
     <li>The line height is the height of the first line of the cue as it appears on the video.</li>
     <li>Positive numbers indicate top down.</li>
     <li>Negative numbers indicate bottom up.</li>
    </ul>
   </li>
   <li>Or value can be a percentage.
    <ul>
     <li>Must be an integer (i.e., no decimals) between 0 and 100 inclusive.</li>
     <li>Must be followed by a percent sign (%).</li>
    </ul>
   </li>
  </ul>

  <table>
   <thead>
    <tr>
     <th colspan="4">Table 2 - line examples</th>
    </tr>
   </thead>
   <tbody>
    <tr>
     <th></th>
     <th><code>vertical</code> omitted</th>
     <th><code>vertical:rl</code></th>
     <th><code>vertical:lr</code></th>
    </tr>
    <tr>
     <th><code>line:0</code></th>
     <td>top</td>
     <td>right</td>
     <td>left</td>
    </tr>
    <tr>
     <th><code>line:-1</code></th>
     <td>bottom</td>
     <td>left</td>
     <td>right</td>
    </tr>
    <tr>
     <th><code>line:0%</code></th>
     <td>top</td>
     <td>right</td>
     <td>left</td>
    </tr>
    <tr>
     <th><code>line:100%</code></th>
     <td>bottom</td>
     <td>left</td>
     <td>right</td>
    </tr>
   </tbody>
  </table>
 </li>
 <li><strong>position</strong>
  <ul>
   <li>Specifies where the text will appear horizontally. If vertical is set, position specifies where the text will appear vertically.</li>
   <li>Value is a percentage.</li>
   <li>Must be an integer (no decimals) between 0 and 100 inclusive.</li>
   <li>Must be followed by a percent sign (%).</li>
  </ul>

  <table>
   <thead>
    <tr>
     <th colspan="4">Table 3 - position examples</th>
    </tr>
   </thead>
   <tbody>
    <tr>
     <th></th>
     <th><code>vertical</code> omitted</th>
     <th><code>vertical:rl</code></th>
     <th><code>vertical:lr</code></th>
    </tr>
    <tr>
     <th><code>position:0%</code></th>
     <td>left</td>
     <td>top</td>
     <td>top</td>
    </tr>
    <tr>
     <th><code>position:100%</code></th>
     <td>right</td>
     <td>bottom</td>
     <td>bottom</td>
    </tr>
   </tbody>
  </table>
 </li>
 <li><strong>size</strong>
  <ul>
   <li>Specifies the width of the text area. If vertical is set, size specifies the height of the text area.</li>
   <li>Value is a percentage.</li>
   <li>Must be an integer (i.e., no decimals) between 0 and 100 inclusive.</li>
   <li>Must be followed by a percent sign (%).</li>
  </ul>

  <table>
   <thead>
    <tr>
     <th colspan="4">Table 4 - size examples</th>
    </tr>
   </thead>
   <tbody>
    <tr>
     <th></th>
     <th><code>vertical</code> omitted</th>
     <th><code>vertical:rl</code></th>
     <th><code>vertical:lr</code></th>
    </tr>
    <tr>
     <th><code>size:100%</code></th>
     <td>full width</td>
     <td>full height</td>
     <td>full height</td>
    </tr>
    <tr>
     <th><code>size:50%</code></th>
     <td>half width</td>
     <td>half height</td>
     <td>half height</td>
    </tr>
   </tbody>
  </table>
 </li>
 <li><strong>align</strong>
  <ul>
   <li>Specifies the alignment of the text. Text is aligned within the space given by the size cue setting if it is set.</li>
  </ul>

  <table>
   <thead>
    <tr>
     <th colspan="4">Table 5 - align values</th>
    </tr>
   </thead>
   <tbody>
    <tr>
     <th></th>
     <th><code>vertical</code> omitted</th>
     <th><code>vertical:rl</code></th>
     <th><code>vertical:lr</code></th>
    </tr>
    <tr>
     <th><code>align:start</code></th>
     <td>left</td>
     <td>top</td>
     <td>top</td>
    </tr>
    <tr>
     <th><code>align:middle</code></th>
     <td>centred horizontally</td>
     <td>centred vertically</td>
     <td>centred vertically</td>
    </tr>
    <tr>
     <th><code>align:end</code></th>
     <td>right</td>
     <td>bottom</td>
     <td>bottom</td>
    </tr>
   </tbody>
  </table>
 </li>
</ul>

<h5 id="Example_13_-_Cue_setting_examples">Example 13 - Cue setting examples</h5>

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

<pre class="eval">00:00:05.000 --&gt; 00:00:10.000
00:00:05.000 --&gt; 00:00:10.000 line:63% position:72% align:start
00:00:05.000 --&gt; 00:00:10.000 line:0 position:20% size:60% align:start
00:00:05.000 --&gt; 00:00:10.000 vertical:rt line:-1 align:end
</pre>

<h3 id="Cue_payload">Cue payload</h3>

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

<p>A cue text payload cannot contain the string "<code>--&gt;"</code>, the ampersand character (&amp;), or the less-than sign (&lt;). Instead use the escape sequence "&amp;amp;" for ampersand and "&amp;lt;" for less-than. It is also recommended that you use the greater-than escape sequence "&amp;gt;" instead of the greater-than character (&gt;) to avoid confusion with tags. If you are using the WebVTT file for metadata these restrictions do not apply.</p>

<p>In addition to the three escape sequences mentioned above, there are fours others. They are listed in the table below.</p>

<table>
 <thead>
  <tr>
   <th colspan="3">Table 6 - Escape sequences</th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <th>Name</th>
   <th>Character</th>
   <th>Escape Sequence</th>
  </tr>
  <tr>
   <td>Ampersand</td>
   <td>&amp;</td>
   <td><code>&amp;amp;</code></td>
  </tr>
  <tr>
   <td>Less-than</td>
   <td>&lt;</td>
   <td><code>&amp;lt;</code></td>
  </tr>
  <tr>
   <td>Greater-than</td>
   <td>&gt;</td>
   <td><code>&amp;gt;</code></td>
  </tr>
  <tr>
   <td>Left-to-right mark</td>
   <td></td>
   <td><code>&amp;lrm;</code></td>
  </tr>
  <tr>
   <td>Right-to-left mark</td>
   <td></td>
   <td><code>&amp;rlm;</code></td>
  </tr>
  <tr>
   <td>Non-breaking space</td>
   <td><code> </code></td>
   <td><code>&amp;nbsp;</code></td>
  </tr>
 </tbody>
</table>

<h3 id="Cue_payload_text_tags">Cue payload text tags</h3>

<p>There are a number of tags, such as <code>&lt;bold&gt;</code>, that can be used. However, if the WebVTT file is used in a {{HTMLElement("track")}} element where the attribute {{htmlattrxref("kind")}} is <code>chapters</code> then you cannot use tags.</p>

<ul>
 <li><strong>Timestamp tag</strong>

  <ul>
   <li>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 <em>active text</em> 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 <em>active text</em> in the payload is <em>previous text</em> . Any text beyond the <em>active text</em> is <em>future text</em> . This enables karaoke style captions.</li>
  </ul>

  <div>
  <h5 id="Example_12_-_Karaoke_style_text">Example 12 - Karaoke style text</h5>

  <pre class="eval">1
00:16.500 --&gt; 00:18.500
When the moon &lt;00:17.500&gt;hits your eye

1
00:00:18.500 --&gt; 00:00:20.500
Like a &lt;00:19.000&gt;big-a &lt;00:19.500&gt;pizza &lt;00:20.000&gt;pie

1
00:00:20.500 --&gt; 00:00:21.500
That's &lt;00:00:21.000&gt;amore
</pre>
  </div>
 </li>
</ul>

<p>The following tags are the HTML tags allowed in a cue and require opening and closing tags (e.g., <code>&lt;b&gt;text&lt;/b&gt;</code>).</p>

<ul>
 <li><strong>Class tag</strong> (<code>&lt;c&gt;&lt;/c&gt;</code>)

  <ul>
   <li>Style the contained text using a CSS class.</li>
  </ul>

  <div>
  <h5 id="Example_14_-_Class_tag">Example 14 - Class tag</h5>

  <pre>&lt;c.classname&gt;text&lt;/c&gt;</pre>
  </div>
 </li>
 <li><strong>Italics tag</strong> (<code>&lt;i&gt;&lt;/i&gt;</code>)
  <ul>
   <li>Italicize the contained text.</li>
  </ul>

  <div>
  <h5 id="Example_15_-_Italics_tag">Example 15 - Italics tag</h5>

  <pre>&lt;i&gt;text&lt;/i&gt;</pre>
  </div>
 </li>
 <li><strong>Bold tag</strong> (<code>&lt;b&gt;&lt;/b&gt;</code>)
  <ul>
   <li>Bold the contained text.</li>
  </ul>

  <div>
  <h5 id="Example_16_-_Bold_tag">Example 16 - Bold tag</h5>

  <pre>&lt;b&gt;text&lt;/b&gt;</pre>
  </div>
 </li>
 <li><strong>Underline tag</strong> (<code>&lt;u&gt;&lt;/u&gt;</code>)
  <ul>
   <li>Underline the contained text.</li>
  </ul>

  <div>
  <h5 id="Example_17_-_Underline_tag">Example 17 - Underline tag</h5>

  <pre>&lt;u&gt;text&lt;/u&gt;</pre>
  </div>
 </li>
 <li><strong>Ruby tag</strong> (<code>&lt;ruby&gt;&lt;/ruby&gt;</code>)
  <ul>
   <li>Used with ruby text tags to display <a href="http://en.wikipedia.org/wiki/Ruby_character">ruby characters</a> (i.e., small annotative characters above other characters).</li>
  </ul>

  <div>
  <h5 id="Example_18_-_Ruby_tag">Example 18 - Ruby tag</h5>

  <pre>&lt;ruby&gt;WWW&lt;rt&gt;World Wide Web&lt;/rt&gt;oui&lt;rt&gt;yes&lt;/rt&gt;&lt;/ruby&gt;</pre>
  </div>
 </li>
 <li><strong>Ruby text tag</strong> (<code>&lt;rt&gt;&lt;/rt&gt;</code>)
  <ul>
   <li>Used with ruby tags to display <a href="http://en.wikipedia.org/wiki/Ruby_character">ruby characters</a> (i.e., small annotative characters above other characters).</li>
  </ul>

  <div>
  <h5 id="Example_19_-_Ruby_text_tag">Example 19 - Ruby text tag</h5>

  <pre>&lt;ruby&gt;WWW&lt;rt&gt;World Wide Web&lt;/rt&gt;oui&lt;rt&gt;yes&lt;/rt&gt;&lt;/ruby&gt;</pre>
  </div>
 </li>
 <li><strong>Voice tag</strong> (<code>&lt;v&gt;&lt;/v&gt;</code>)
  <ul>
   <li>Similar to class tag, also used to style the contained text using CSS.</li>
  </ul>

  <div>
  <h5 id="Example_20_-_Voice_tag">Example 20 - Voice tag</h5>

  <pre>&lt;v Bob&gt;text&lt;/v&gt;</pre>
  </div>
 </li>
</ul>

<h2 id="Interfaces">Interfaces</h2>

<p>There are two interfaces or APIs used in WebVTT which are:</p>

<h3 id="VTTCue_interface">VTTCue interface</h3>

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

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

<pre class="idl def">enum <dfn>AutoKeyword</dfn> { <dfn>"auto"</dfn> };
enum <dfn>DirectionSetting</dfn> { <dfn>""</dfn> /* horizontal */, <dfn>"rl"</dfn>, <dfn>"lr"</dfn> };
enum <dfn>LineAlignSetting</dfn> { <dfn>"start"</dfn>, <dfn>"center"</dfn>, <dfn>"end"</dfn> };
enum <dfn>PositionAlignSetting</dfn> { <dfn>"line-left"</dfn>, <dfn>"center"</dfn>, <dfn>"line-right"</dfn>, <dfn>"auto"</dfn> };
enum <dfn>AlignSetting</dfn> { <dfn>"start"</dfn>, <dfn>"center"</dfn>, <dfn>"end"</dfn>, <dfn>"left"</dfn>, <dfn>"right"</dfn> };
[<a class="idl-code" href="https://w3c.github.io/webvtt/#dom-vttcue-vttcue" id="ref-for-dom-vttcue-vttcue-1">Constructor</a>(double <dfn>startTime</dfn>, double <dfn>endTime</dfn>, DOMString <dfn>text</dfn>)]
interface <dfn>VTTCue</dfn> : <a href="https://html.spec.whatwg.org/multipage/embedded-content.html#texttrackcue">TextTrackCue</a> {
  attribute <a href="https://w3c.github.io/webvtt/#vttregion" id="ref-for-vttregion-1">VTTRegion</a>? <a class="idl-code" href="https://w3c.github.io/webvtt/#dom-vttcue-region" id="ref-for-dom-vttcue-region-1">region</a>;
  attribute <a href="https://w3c.github.io/webvtt/#enumdef-directionsetting" id="ref-for-enumdef-directionsetting-1">DirectionSetting</a> <a class="idl-code" href="https://w3c.github.io/webvtt/#dom-vttcue-vertical" id="ref-for-dom-vttcue-vertical-1">vertical</a>;
  attribute boolean <a class="idl-code" href="https://w3c.github.io/webvtt/#dom-vttcue-snaptolines" id="ref-for-dom-vttcue-snaptolines-2">snapToLines</a>;
  attribute (double or <a href="https://w3c.github.io/webvtt/#enumdef-autokeyword" id="ref-for-enumdef-autokeyword-1">AutoKeyword</a>) <a class="idl-code" href="https://w3c.github.io/webvtt/#dom-vttcue-line" id="ref-for-dom-vttcue-line-2">line</a>;
  attribute <a href="https://w3c.github.io/webvtt/#enumdef-linealignsetting" id="ref-for-enumdef-linealignsetting-1">LineAlignSetting</a> <a class="idl-code" href="https://w3c.github.io/webvtt/#dom-vttcue-linealign" id="ref-for-dom-vttcue-linealign-1">lineAlign</a>;
  attribute (double or <a href="https://w3c.github.io/webvtt/#enumdef-autokeyword" id="ref-for-enumdef-autokeyword-2">AutoKeyword</a>) <a class="idl-code" href="https://w3c.github.io/webvtt/#dom-vttcue-position" id="ref-for-dom-vttcue-position-1">position</a>;
  attribute <a href="https://w3c.github.io/webvtt/#enumdef-positionalignsetting" id="ref-for-enumdef-positionalignsetting-1">PositionAlignSetting</a> <a class="idl-code" href="https://w3c.github.io/webvtt/#dom-vttcue-positionalign" id="ref-for-dom-vttcue-positionalign-1">positionAlign</a>;
  attribute double <a class="idl-code" href="https://w3c.github.io/webvtt/#dom-vttcue-size" id="ref-for-dom-vttcue-size-1">size</a>;
  attribute <a href="https://w3c.github.io/webvtt/#enumdef-alignsetting" id="ref-for-enumdef-alignsetting-1">AlignSetting</a> <a class="idl-code" href="https://w3c.github.io/webvtt/#dom-vttcue-align" id="ref-for-dom-vttcue-align-1">align</a>;
  attribute DOMString <a class="idl-code" href="https://w3c.github.io/webvtt/#dom-vttcue-text" id="ref-for-dom-vttcue-text-1">text</a>;
  <a href="https://dom.spec.whatwg.org/#documentfragment">DocumentFragment</a> <a class="idl-code" href="https://w3c.github.io/webvtt/#dom-vttcue-getcueashtml" id="ref-for-dom-vttcue-getcueashtml-2">getCueAsHTML</a>();
};</pre>

<h3 id="VTT_Region_interface">VTT Region interface</h3>

<p>This is the second interface in WebVTT API.</p>

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

<pre class="idl def">enum <dfn>ScrollSetting</dfn> { <dfn>""</dfn> /* none */, <dfn>"up"</dfn> };
[<a class="idl-code" href="https://w3c.github.io/webvtt/#dom-vttregion-vttregion" id="ref-for-dom-vttregion-vttregion-1">Constructor</a>]
interface <dfn>VTTRegion</dfn> {
  attribute double <a class="idl-code" href="https://w3c.github.io/webvtt/#dom-vttregion-width" id="ref-for-dom-vttregion-width-1">width</a>;
  attribute long <a class="idl-code" href="https://w3c.github.io/webvtt/#dom-vttregion-lines" id="ref-for-dom-vttregion-lines-1">lines</a>;
  attribute double <a class="idl-code" href="https://w3c.github.io/webvtt/#dom-vttregion-regionanchorx" id="ref-for-dom-vttregion-regionanchorx-1">regionAnchorX</a>;
  attribute double <a class="idl-code" href="https://w3c.github.io/webvtt/#dom-vttregion-regionanchory" id="ref-for-dom-vttregion-regionanchory-1">regionAnchorY</a>;
  attribute double <a class="idl-code" href="https://w3c.github.io/webvtt/#dom-vttregion-viewportanchorx" id="ref-for-dom-vttregion-viewportanchorx-1">viewportAnchorX</a>;
  attribute double <a class="idl-code" href="https://w3c.github.io/webvtt/#dom-vttregion-viewportanchory" id="ref-for-dom-vttregion-viewportanchory-1">viewportAnchorY</a>;
  attribute <a href="https://w3c.github.io/webvtt/#enumdef-scrollsetting" id="ref-for-enumdef-scrollsetting-1">ScrollSetting</a> <a class="idl-code" href="https://w3c.github.io/webvtt/#dom-vttregion-scroll" id="ref-for-dom-vttregion-scroll-1">scroll</a>;
};</pre>

<h2 id="Methods_and_properties">Methods and properties</h2>

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

<ul style="list-style-type: circle;">
 <li>
  <h3 id="VTTCue">VTTCue</h3>

  <ul>
   <li>The methods which are available in this interface are:
    <ul style="list-style-type: circle;">
     <li>GetCueAsHTML to get the HTML of that Cue.</li>
     <li>VTT Constructor for creating new objects of Cues.</li>
     <li>Autokeyword.</li>
     <li>DirectionSetting: to set the direction of caption or text in a file.</li>
     <li>LineAlignment: to adjust the line alignment.</li>
     <li>PositionAlignSetting: to adjust the position of text.</li>
    </ul>
   </li>
  </ul>
 </li>
 <li>
  <h3 id="VTTRegion">VTTRegion</h3>

  <ul>
   <li>The methods used for region are listed below along with description of their functionality:
    <ul style="list-style-type: circle;">
     <li>ScrollSetting: For adjusting the scrolling setting of all nodes present in given region.</li>
     <li>VTT Region Constructor: for construction of new VTT Regions.</li>
    </ul>
   </li>
  </ul>
 </li>
</ul>

<h2 id="Tutorial_on_how_to_write_a_WebVTT_file">Tutorial on how to write a WebVTT file</h2>

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

<ol>
 <li>Open a notepad.</li>
 <li>The first line of WebVTT is standardized similar in the way some other languages require you to put headers as the file starts to indicate the file type. One the very first line you have to write.</li>
</ol>

<pre>WEBVTT</pre>

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

<pre>00:01.000 --&gt; 00:05.000</pre>

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

<h2 id="CSS_pseudo-classes">CSS pseudo-classes</h2>

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

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

<pre>WEBVTT

04:02.500 --&gt; 04:05.000
J’ai commencé le basket à l'âge de 13, 14 ans

04:05.001 --&gt; 04:07.800
Sur les &lt;i.foreignphrase&gt;&lt;lang en&gt;playground&lt;/lang&gt;&lt;/i&gt;, ici à Montpellier</pre>

<p>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 <code>&lt;i&gt;</code> tag is for italics.</p>

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

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

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

<h2 id="规范">规范</h2>

<table class="standard-table">
 <tbody>
  <tr>
   <th>Specification</th>
   <th>Status</th>
   <th>Comment</th>
  </tr>
  <tr>
   <td>{{SpecName("WebVTT")}}</td>
   <td>{{Spec2("WebVTT")}}</td>
   <td>Initial definition</td>
  </tr>
 </tbody>
</table>

<h2 id="浏览器兼容性">浏览器兼容性</h2>

<h3 id="VTTCue_接口"><code>VTTCue</code> 接口</h3>

<div>


<p>{{Compat("api.VTTCue", 0)}}</p>

<h3 id="TextTrack_接口"><code>TextTrack</code> 接口</h3>

<div>
<p>{{Compat("api.TextTrack", 0)}}</p>

<h3 id="备注">备注</h3>
</div>
</div>

<p>Prior to Firefox 50, the <code>AlignSetting</code> enum (representing possible values for {{domxref("VTTCue.align")}}) incorrectly included the value <code>"middle"</code> instead of <code>"center"</code>. This has been corrected.</p>

<p>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 <code>true</code>. WebVTT is enabled by default starting in Firefox 31 and can be disabled by setting the preference to <code>false</code>.</p>

<p>Prior to Firefox 58, the <code>REGION</code> keyword was creating {{domxref("VTTRegion")}} objects, but they were not being used. Firefox 58 now fully supports <code>VTTRegion</code> and its use; however, this feature is disabled by default behind the preference <code>media.webvtt.regions.enabled</code>; set it to <code>true</code> to enable region support in Firefox 58. Regions are enabled by default starting in Firefox 59 (see bugs {{bug(1338030)}} and {{bug(1415805)}}).</p>