WebVTT API

Konzepte und Verwendung

Eine Textspur ist ein Container fr zeitlich abgestimmte Textdaten, die parallel zu einem Video- oder Audiotrack abgespielt werden knnen, um eine bersetzung, Transkription oder bersicht ber den Inhalt bereitzustellen. Ein Video- oder Audiomedienelement kann Spuren verschiedener Arten oder in verschiedenen Sprachen definieren, sodass Benutzer passende Spuren basierend auf ihren Vorlieben oder Bedrfnissen anzeigen knnen.

Die verschiedenen Arten von Textdaten, die angegeben werden knnen, sind captions, descriptions, chapters, subtitles oder metadata; die <track>-Dokumentation bietet mehr Informationen darber, was sie bedeuten. Beachten Sie, dass Browser nicht unbedingt alle Arten von Textspuren untersttzen.

Die einzeln zeitlich abgestimmten Einheiten von Textdaten innerhalb einer Spur werden als "Hinweise" bezeichnet. Jeder Hinweis hat eine Startzeit, eine Endzeit und einen Textinhalt. Er kann auch "Hinweiseinstellungen" haben, die seine Anzeigeregion, Position, Ausrichtung und/oder Gre beeinflussen. Schlielich kann ein Hinweis ein Label haben, das zur Auswahl fr CSS-Styling verwendet werden kann.

Eine Textspur und Hinweise knnen in einer Datei unter Verwendung des WebVTT-Dateiformats definiert und dann mit einem bestimmten <video>-Element unter Verwendung des <track>-Elements verknpft werden.

Alternativ knnen Sie einem Medienelement ber JavaScript eine TextTrack hinzufgen, indem Sie HTMLMediaElement.addTextTrack() verwenden und dann einzelne VTTCue-Objekte mit TextTrack.addCue() zur Spur hinzufgen.

Das ::cue CSS Pseudoelement kann sowohl in HTML als auch in einer WebVTT-Datei verwendet werden, um die Hinweise fr ein bestimmtes Element, fr ein bestimmtes Tag innerhalb eines Hinweises, fr eine VTT-Klasse oder fr einen Hinweis mit einem bestimmten Label zu stylen. Das ::cue-region-Pseudoelement ist zum Stylen von Hinweisen in einer bestimmten Region vorgesehen, wird jedoch in keinem Browser untersttzt.

Die wichtigsten WebVTT-Funktionen knnen entweder mit dem Dateiformat oder der Web-API aufgerufen werden.

Schnittstellen

VTTCue

Reprsentiert einen Hinweis, den Text, der in einem bestimmten Zeitabschnitt der mit einem Medienelement verknpften Textspur angezeigt wird.

VTTRegion

Reprsentiert einen Abschnitt eines Videoelements, auf dem ein VTTCue dargestellt werden kann.

TextTrack

Reprsentiert eine Textspur, die die Liste der Hinweise enthlt, die zusammen mit einem verknpften Medienelement zu verschiedenen Zeitpunkten angezeigt werden, whrend es abgespielt wird.

TextTrackCue

Eine abstrakte Basisklasse fr verschiedene Hinweisarten, wie VTTCue.

TextTrackCueList

Ein array-artiges Objekt, das eine dynamisch aktualisierte Liste von TextTrackCue-Objekten darstellt. Eine Instanz dieses Typs wird von TextTrack.cues abgerufen, um alle Hinweise im TextTrack-Objekt zu erhalten.

TextTrackList

Reprsentiert eine Liste der fr ein Medienelement definierten Textspuren, wobei jede Spur durch eine separate TextTrack-Instanz in der Liste dargestellt wird.

Verwandte Schnittstellen

DataCue

Reprsentiert einen Hinweis fr die Zuordnung beliebiger zeitgesteuerter Daten (anstatt von Text) zu einer Medienressource, wie etwa in-band-Ereignisnachrichten.

TrackEvent

Teil der HTML DOM-API, diese Schnittstelle ist fr die addtrack- und removetrack-Ereignisse, die ausgelst werden, wenn eine Spur zu TextTrackList hinzugefgt oder daraus entfernt wird (oder allgemeiner, wenn eine Spur zu einem HTML-Medienelement hinzugefgt oder entfernt wird).

Verwandte CSS-Erweiterungen

Diese CSS Pseudoelemente werden verwendet, um Hinweise in Medien mit VTT-Spuren zu stylen.

::cue

Passt zu Hinweisen innerhalb eines ausgewhlten Elements in Medien mit VTT-Spuren.

Beispiele

Verwenden der WebVTT API, um Untertitel hinzuzufgen

HTML

Im folgenden Beispiel wird dem Video ein neues TextTrack hinzugefgt, dann werden Hinweise mithilfe von Methodenaufrufen von TextTrack.addCue() hinzugefgt, wobei konstruierte VTTCue-Objekte als Argumente verwendet werden.

<video controls src="/shared-assets/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);

Ergebnis

Anzeigen von VTT-Inhalten, die in einer Datei definiert sind

Dieses Beispiel zeigt, wie die gleiche Menge von Untertiteln zu dem im obigen Beispiel Verwenden der WebVTT API, um Untertitel hinzuzufgen gesehenen Video hinzugefgt wird. Diesmal werden wir es jedoch deklarativ unter Verwendung eines <track>-Elements tun.

Zuerst definieren wir die Untertitel in einer "captions.vtt"-Datei:

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

Wir knnen dies dann unter Verwendung des <track>-Elements zu einem <video>-Element hinzufgen. Das folgende HTML wrde zur gleichen Textspur wie das vorherige Beispiel fhren:

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

Wir knnen mehrere <track>-Elemente hinzufgen, um verschiedene Arten von Spuren in mehreren Sprachen zu spezifizieren, wobei die Attribute kind und srclang verwendet werden. Beachten Sie, dass, wenn kind angegeben ist, srclang auch gesetzt werden muss. Das default-Attribut kann zu nur einem <track> hinzugefgt werden: Dieser wird abgespielt, wenn Benutzereinstellungen keine bestimmte Sprache oder Art spezifizieren.

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

Styling von WebVTT in HTML oder einem Stylesheet

Sie knnen WebVTT-Hinweise stylen, indem Sie Elemente mit dem ::cue-Pseudoelement auswhlen. Dies ermglicht es Ihnen, das Erscheinungsbild von allem Hinweistext oder nur von bestimmten Elementen zu ndern. In diesem Beispiel werden wir einige Stilnderungen zum ersten Beispiel oben hinzufgen.

HTML

Das HTML fr das Video selbst ist wie bislang gesehen identisch:

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

<video controls src="/shared-assets/videos/friday.mp4"></video>

CSS

Zuerst verwenden wir das ::cue-Pseudoelement, um alle Video-Text-Hinweise auszuwhlen und sie grer, rot und mit einem Verlaufshintergrund zu gestalten.

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

Dann verwenden wir ::cue, um Text auszuwhlen, der mit den Elementen u und b gekennzeichnet wurde, und sie grn und gelb zu stylen.

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

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

JavaScript

Das JavaScript ist das gleiche wie im ersten Beispiel, auer dass wir Teile des Hinweistexts mit <b> (fett) und <u> (unterstrichen) getaggt haben. Standardmig wird der markierte Text als fett oder unterstrichen (abhngig vom Tag) angezeigt, aber wir haben das ::cue im vorherigen Abschnitt verwendet, um den Text auerdem grn und lila zu stylen.

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

Ergebnis

Weitere Beispiele zur Hinweisgestaltung

Dieses Beispiel zeigt weitere Beispiele, wie Sie Hinweistext mit Tags kennzeichnen und dann stylen knnen. Das gleiche Markup und die Stile knnen im WebVTT-Dateiformat verwendet werden.

Das HTML und CSS zur Anzeige des Videos selbst ist das gleiche wie im ersten Beispiel oben, daher zeigen wir hier nur den spezifischen Code zum Markieren und Stylen des Textes.

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

<video controls src="/shared-assets/videos/friday.mp4"></video>

Styling nach Tag-Typ

Der erste von uns erstellte Hinweis wird fr alle 6 Sekunden des Videos angezeigt und zeigt Text, der mit den Tags b, u, i und c gekennzeichnet ist.

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>",
  ),
);

Zuerst fgen wir eine Regel hinzu, um alle Hinweise um den Faktor 1,2 grer als normal zu machen.

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

Dann stylen wir jedes der oben genannten Tags in einer anderen Farbe.

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

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

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

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

Styling nach Klasse

Der zweite Hinweis wird direkt nach dem ersten angezeigt und enthlt die gleichen Tags. Sie haben jedoch alle die Klasse myclass angewendet.

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>",
  ),
);

Wir stylen alle Elemente mit der Klasse .myclass mit einer hellblauen Textfarbe, mit Ausnahme des speziellen Falls von c.myclass, dem eine blaue Textfarbe zugewiesen wird.

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

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

Styling mithilfe von Attributen

Die nchsten beiden Hinweise werden nach zwei bzw. drei Sekunden angezeigt. Der erste zeigt Text an, der mit dem lang-Tag fr drei Varianten des Englischen gekennzeichnet ist, whrend der zweite ein <v> (Stimme)-Tag mit dem Attribut "Bob" anzeigt.

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>"));

Wir verwenden den lang-Attributselektor, um jeder Sprachvariante eine andere Textfarbe zu geben.

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

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

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

Dann verwenden wir den v-Tag- und Attributselektor fr voice, um den Text in "Bobs Stimme" orange zu frben.

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

Ergebnis

Das Beispiel sollte die Hinweise mit Farbmarkierung zeigen, die den obigen Stilen entspricht (wenn der Text nicht gefrbt ist, dann wird ::cue in Ihrem Browser nicht untersttzt).

Spezifikationen

Browser-Kompatibilitt

api.VTTCue

api.TextTrack

api.VTTRegion

Siehe auch

• Die CSS ::cue und ::cue() Pseudoelemente