new VTTCue() — Methode · JavaScript-Referenz

Signatur

new VTTCue(startTime, endTime, text)

Beschreibung

Der Konstruktor VTTCue() erzeugt einen einzelnen Cue im WebVTT-Format. Ein Cue ist ein Textabschnitt, der in einem bestimmten Zeitfenster eines <video>- oder <audio>-Elements gilt. Solche Cues werden normalerweise aus einer .vtt-Datei über ein <track>-Element geladen. Mit new VTTCue() lassen sie sich aber auch direkt im Skript anlegen.

Das ist praktisch, wenn Untertitel erst zur Laufzeit entstehen, zum Beispiel durch Live-Transkription, Übersetzung, Daten aus einer API oder eigene Formate wie SRT oder JSON. Außerdem kann man Cues als reine Metadaten nutzen, etwa für Kapitelmarken oder Werbe-Trigger. Dafür legt man einen Track mit der Art "metadata" an und reagiert auf die Events enter und exit der Cues.

Nach dem Erzeugen kann man Eigenschaften wie line, position, size, align, vertical oder snapToLines setzen und damit die Darstellung steuern. Danach fügt man den Cue mit TextTrack.addCue() einem Track hinzu. Sichtbar wird er nur, wenn der Track den Modus "showing" hat.

Parameter

Name	Typ	Beschreibung
$startTime Pflicht	number	Startzeit des Cues in Sekunden relativ zum Medienanfang, z. B. `1.5`.
$endTime Pflicht	number	Endzeit des Cues in Sekunden. Sie sollte größer als `startTime` sein, sonst wird der Cue nie aktiv.
$text Pflicht	string	Inhalt des Cues. Er darf WebVTT-Auszeichnungen wie `<b>`, `<i>` oder `<v Sprecher>` enthalten. Zeilenumbrüche schreibt man als `\n`.

Rückgabewert

Typ

VTTCue

Beschreibung

Ein neues VTTCue-Objekt. Es gehört noch zu keinem Track: track ist null.

Beispiele

Untertitel per Skript hinzufügen

const video = document.querySelector('video');

// Neuen Untertitel-Track anlegen und anzeigen
const track = video.addTextTrack('subtitles', 'Deutsch', 'de');
track.mode = 'showing';

const cue = new VTTCue(0, 4, 'Willkommen bei programmierung.net!');
cue.line = -2;       // zweitletzte Zeile
cue.align = 'center';
track.addCue(cue);

console.log(track.cues.length, cue.text);

1 Willkommen bei programmierung.net!

Untertitel aus JSON-Daten erzeugen

const video = document.querySelector('video');
const track = video.addTextTrack('captions', 'Transkript', 'de');
track.mode = 'showing';

const loadCaptions = async (url) => {
  const response = await fetch(url);
  const segments = await response.json(); // [{ start, end, text }, ...]

  for (const { start, end, text } of segments) {
    track.addCue(new VTTCue(start, end, text));
  }
  console.log(`${track.cues.length} Cues geladen`);
};

loadCaptions('/api/transcript/42.json');

z. B. "37 Cues geladen"

Kapitelmarken als Metadaten-Cues mit enter-Event

const video = document.querySelector('video');
const meta = video.addTextTrack('metadata', 'Kapitel');
meta.mode = 'hidden'; // Events feuern, aber nichts wird angezeigt

const chapters = [
  [0, 30, 'Einleitung'],
  [30, 95, 'Installation'],
  [95, 180, 'Erste Schritte']
];

chapters.forEach(([start, end, title]) => {
  const cue = new VTTCue(start, end, JSON.stringify({ title }));
  cue.addEventListener('enter', () => {
    const { title } = JSON.parse(cue.text);
    document.querySelector('#kapitel').textContent = title;
  });
  meta.addCue(cue);
});

// Wichtig · Fallstricke

Sichtbarkeit: Cues werden nur dargestellt, wenn track.mode === "showing" ist. Im Modus "hidden" feuern zwar die Events enter, exit und cuechange, es wird aber nichts angezeigt. Im Modus "disabled" passiert gar nichts.
Zeiten in Sekunden: Die Werte werden als Gleitkommazahlen in Sekunden angegeben, nicht in Millisekunden. Das ist ein häufiger Fehler beim Umrechnen aus SRT-Zeitstempeln.
Kein HTML: text wird als WebVTT-Cue-Text interpretiert, nicht als HTML. Beliebige HTML-Tags werden nicht dargestellt. Das ist auch in Bezug auf XSS sicher. Mit getCueAsHTML() erhält man ein DocumentFragment.
Kompatibilität: Der Konstruktor wird von allen modernen Browsern unterstützt. Sehr alte Versionen von Edge und IE kannten nur TextTrackCue. Wie gut Eigenschaften wie region, vertical oder position: "auto" umgesetzt sind, unterscheidet sich zwischen den Browsern. In Node.js gibt es VTTCue nicht.
Ein Cue kann immer nur zu einem Track gehören. Soll er in einen anderen Track, entfernt man ihn zuerst mit removeCue().

Siehe auch

VTTCue TextTrack TextTrack.prototype.addCue() HTMLMediaElement.prototype.addTextTrack() TextTrackCue VTTRegion