API WebVTT

Подписи к видеороликам веб-формата (WebVTT) — это текстовые дорожки, предоставляющие определённые текстовые «метки», которые синхронизированы по времени с другими медиа, такими как видео или аудио дорожки. API WebVTT предоставляет функциональность для определения и управления этими текстовыми дорожками. API WebVTT в первую очередь используется для отображения субтитров или титров, которые накладываются на видеоконтент, но у него есть и другие применения: предоставление информации о главах для удобной навигации и общая метаданные, которые необходимо синхронизировать по времени с аудио или видео контентом.

Текстовая дорожка — это контейнер для данных синхронизированного по времени текста, который может воспроизводиться параллельно с видео- или аудиодорожкой для предоставления перевода, транскрипции или обзора содержимого. Видео- или аудиоэлемент медиа может определять дорожки различных типов или на разных языках, что позволяет пользователям отображать соответствующие дорожки в зависимости от их предпочтений или потребностей.

Ниже перечислены различные типы текстовых данных, которые могут быть указаны. Обратите внимание, что браузеры не обязательно поддерживают все типы текстовых дорожек.

• subtitles предоставляют текстовый перевод диалога. Это тип текстовой дорожки по умолчанию, и если она используется, необходимо указать исходный язык.
• captions предоставляют транскрипцию разговорной речи и могут содержать информацию об другом аудио, таком как музыка или фоновый шум. Они предназначены для пользователей с нарушениями слуха.
• chapters предоставляют информацию о высокой уровне навигации, позволяя пользователям легче переключаться на соответствующее содержимое.
• metadata используется для других типов информации, синхронизированной по времени.

Индивидуальные временные единицы текстовых данных в пределах дорожки называются «метками». Каждая метка имеет начальное время, конечное время и текстовую нагрузку. Она также может иметь «настройки меток», которые влияют на область отображения, позицию, выравнивание и/или размер. Наконец, метка может иметь метку, которая может использоваться для её выбора для стилизации CSS.

Текстовую дорожку и метки можно определить в файле, используя формат файлов WebVTT, а затем связать с определенным <video> элементом с помощью <track> элемента.

В качестве альтернативы, вы можете добавить TextTrack к элементу медиа на JavaScript, используя HTMLMediaElement.addTextTrack(), а затем добавить отдельные VTTCue объекты в дорожку с помощью TextTrack.addCue().

::cue CSS псевдоэлемент можно использовать как в HTML, так и в файле WebVTT для стилизации меток для определенного элемента, для определенного тега внутри метки, для класса VTT или для метки с определённой меткой. ::cue-region псевдоэлемент предназначен для стилизации меток в определенной области, но не поддерживается ни в одном браузере.

Большинство важных функций WebVTT можно получить, используя либо формат файла, либо веб-API.

VTTCue

Представляет метку, текст, отображаемый в определённом временном интервале текстовой дорожки, связанной с элементом медиа.

VTTRegion

Представляет часть элемента видео, на которую может быть рендерирована VTTCue.

TextTrack

Представляет текстовую дорожку, которая содержит список меток для отображения вместе с связанным элементом медиа в различные моменты во время воспроизведения.

TextTrackCue

Абстрактный базовый класс для различных типов меток, таких как VTTCue.

TextTrackCueList

Объект, подобный массиву, который представляет динамически обновляемый список TextTrackCue объектов. Экземпляр этого типа получается из TextTrack.cues для получения всех меток в TextTrack объекте.

TextTrackList

Представляет список текстовых дорожек, определённых для элемента медиа, при этом каждая дорожка представлена отдельным TextTrack экземпляром в списке.

TrackEvent

Часть API HTML DOM, это интерфейс для событий addtrack и removetrack, которые срабатывают, когда дорожка добавляется или удаляется из TextTrackList (или, более общим образом, когда дорожка добавляется/удаляется из элемента HTML медиа).

Эти CSS псевдоэлементы используются для стилизации меток в медиа с дорожками VTT.

::cue

Сопоставляет метки внутри выбранного элемента в медиа с дорожками VTT.

HTML

В данном примере добавляется новая TextTrack к видео, затем добавляются метки с помощью вызовов метода TextTrack.addCue(), в качестве аргументов используются сконструированные VTTCue объекты.

<video
  controls
  src="https://interactive-examples.mdn.mozilla.net/media/cc0-videos/friday.mp4"></video>

CSS

video {
  width: 420px;
  height: 300px;
}

JavaScript

let video = document.querySelector("video");
let track = video.addTextTrack("captions", "Captions", "en");
track.mode = "showing";
track.addCue(new VTTCue(0, 0.9, "Hildy!"));
track.addCue(new VTTCue(1, 1.4, "How are you?"));
track.addCue(new VTTCue(1.5, 2.9, "Tell me, is the lord of the universe in?"));
track.addCue(new VTTCue(3, 4.2, "Yes, he's in - in a bad humor"));
track.addCue(new VTTCue(4.3, 6, "Somebody must've stolen the crown jewels"));
console.log(track.cues);

Результат

Этот пример демонстрирует, как добавить тот же набор субтитров к видео, что и в примере Использование API WebVTT для добавления субтитров выше. В этот раз, однако, мы сделаем это декларативно, используя элемент <track>.

Сначала определим субтитры внутри файла "captions.vtt":

WEBVTT

00:00.000 --> 00:00.900
Hildy!

00:01.000 --> 00:01.400
How are you?

00:01.500 --> 00:02.900
Tell me, is the lord of the universe in?

00:03.000 --> 00:04.200
Yes, he's in - in a bad humor

00:04.300 --> 00:06.000
Somebody must've stolen the crown jewels

Затем мы можем добавить его в элемент <video> с помощью элемента <track>. Следующий HTML приведет к той же текстовой дорожке, что и в предыдущем примере:

<video controls src="video.webm">
  <track default kind="captions" src="captions.vtt" srclang="en" />
</video>

Мы можем добавить несколько элементов <track> для указания различных типов дорожек на нескольких языках, используя атрибуты kind и srclang. Обратите внимание, что если kind указан, srclang обязательно должен быть задан тоже. Атрибут default может быть добавлен только к одному <track>: именно он будет воспроизводиться, если настройки пользователя не указывают конкретный язык или тип.

<video controls src="video.webm">
  <track default kind="captions" src="captions.vtt" srclang="en" />
  <track kind="subtitles" src="subtitles.vtt" srclang="en" />
  <track kind="descriptions" src="descriptions.vtt" srclang="en" />
  <track kind="chapters" src="chapters_de.vtt" srclang="de" />
  <track kind="subtitles" src="subtitles_en.vtt" srclang="en" />
</video>

Вы можете стилизовать метки WebVTT, сопоставляя элементы с помощью псевдоэлемента ::cue. Это позволяет изменять внешний вид всего текстового содержимого меток или только определённых элементов. В этом примере мы добавим немного стилей к первому примеру выше.

HTML

HTML для самого видео такой же, как мы видели ранее:

<video
  controls
  src="https://interactive-examples.mdn.mozilla.net/media/cc0-videos/friday.mp4"></video>

CSS

Сначала используем ::cue псевдоэлемент для выбора всех текстовых меток видео, давая им больший красный цвет и градиентный фон.

video::cue {
  font-size: 1.5rem;
  background-image: linear-gradient(to bottom, yellow, lightyellow);
  color: red;
}

Затем мы используем ::cue для выбора текста, который был разметкой с помощью элементов u и b, и стилизуем их зелёным и жёлтым соответственно.

video::cue(u) {
  color: green;
}

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

JavaScript

JavaScript такой же, как в первом примере, за исключением того, что мы поместили разметку некоторых текстовых меток с помощью <b> (жирный шрифт) и <u> (подчёркнутый) тегов. По умолчанию помеченный текст отображался бы жирным или подчёркнутым (в зависимости от тега), но мы использовали ::cue в предыдущем разделе, чтобы также стилизовать текст зелёным и фиолетовым соответственно.

let video = document.querySelector("video");
let track = video.addTextTrack("captions", "Captions", "en");
track.mode = "showing";
track.addCue(new VTTCue(0, 0.9, "Hildy!"));
track.addCue(new VTTCue(1, 1.4, "How are you?"));
track.addCue(
  new VTTCue(1.5, 2.9, "Tell me, is the <u>lord of the universe</u> in?"),
);
track.addCue(new VTTCue(3, 4.2, "Yes, he's in - in a bad humor"));
track.addCue(
  new VTTCue(4.3, 6, "Somebody must've <b>stolen</b> the crown jewels"),
);
console.log(track.cues);

Результат

Этот пример демонстрирует дополнительные примеры того, как вы можете форматировать текст субтитров с помощью тегов и затем стилизовать их. Такую же разметку и стили можно использовать в формате файла WebVTT.

HTML и CSS для отображения самого видео такие же, как и в первом примере выше, поэтому здесь мы показываем только код, специфичный для разметки и стилизации текста.

Стилизация по типу тега

Первый субтитр будет отображаться в течение всех 6 секунд видео и содержать текст, разметку которого выполняют теги b, u, i и c.

let video = document.querySelector("video");

let track = video.addTextTrack("captions", "Captions", "en");
track.mode = "showing";

track.addCue(
  new VTTCue(
    0,
    6,
    "Styles: Normal <b>bold</b> <u>underlined</u> <i>italic</i> <c>class</c>",
  ),
);

Сначала добавим правило, чтобы все субтитры были на 1,2 размера больше обычного.

video::cue {
  font-size: 1.2rem;
}

Затем мы стилизуем каждый из перечисленных тегов разными цветами.

video::cue(u) {
  color: green;
}

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

video::cue(i) {
  color: red;
}

video::cue(c) {
  color: lavender;
}

Стилизация по классу

Второй субтитр отображается сразу после первого и содержит те же теги. Однако все они имеют применённый класс myclass.

track.addCue(
  new VTTCue(
    1,
    6,
    "Styles: Class markup: <b.myclass>bold</b> <u.myclass>underlined</u> <i.myclass>italic</i> <c.myclass>class</c>",
  ),
);

Мы стилизуем все элементы с классом .myclass светло-голубым цветом текста, за исключением конкретного случая c.myclass, которому задаётся синий цвет текста.

video::cue(.myclass) {
  color: lightblue;
}

video::cue(c.myclass) {
  color: blue;
}

Стилизация с помощью атрибутов

Следующие два субтитра отображаются после двух, а затем трёх секунд. Первый отображает текст, разметку которого выполняет тег lang для трёх вариантов английского языка, а второй отображает тег <v> (голос) с атрибутом "Bob".

track.addCue(
  new VTTCue(
    2,
    6,
    "<lang en>Lang markup: 'en'</lang>  <lang en-GB>Text: 'en-GB'</lang> <lang en-US>Text: 'en-US'</lang>",
  ),
);

track.addCue(new VTTCue(3, 6, "<v Bob>Bob's voice</v>"));

Мы используем селектор атрибута lang для задания разному варианту языка разного цвета текста.

video::cue([lang="en"]) {
  color: lightgreen;
}

video::cue([lang="en-GB"]) {
  color: darkgreen;
}

video::cue(:lang(en-US)) {
  color: #6082b6;
}

Затем мы используем селектор тега v и атрибута для voice , чтобы окрасить текст голосом "Bob" в оранжевый цвет.

video::cue(v[voice="Bob"]) {
  color: orange;
}

Результат

В примере должны отображаться субтитры с цветовым кодированием, соответствующим вышеуказанной стилизации (если текст не окрашен, значит ::cue не поддерживается вашим браузером).

• Псевдоэлементы CSS ::cue и ::cue()