VTTCue — Schnittstelle · JavaScript-Referenz

Signatur

interface VTTCue extends TextTrackCue

Beschreibung

VTTCue gehört zur WebVTT API und beschreibt eine einzelne Cue: einen Textabschnitt, der zwischen startTime und endTime (in Sekunden) über einem <video>- oder <audio>-Element angezeigt wird. Das Interface erbt von TextTrackCue (id, startTime, endTime, pauseOnExit, track, Ereignisse enter/exit) und ergänzt es um WebVTT-spezifische Layout-Eigenschaften.

Wichtige eigene Eigenschaften sind text (Cue-Inhalt inklusive WebVTT-Markup wie <b>, <i>, <v Sprecher>), line, lineAlign, position, positionAlign, size, align, vertical, snapToLines und region (ein VTTRegion). Mit der Methode getCueAsHTML() erhält man den Inhalt als DocumentFragment.

Man verwendet VTTCue, wenn Untertitel, Kapitelmarken oder Metadaten dynamisch erzeugt werden sollen – etwa aus einer JSON-Antwort, einer Live-Transkription oder für zeitgesteuerte Aktionen (kind = "metadata") –, statt eine statische .vtt-Datei über <track> einzubinden. Die Cue wird mit textTrack.addCue(cue) hinzugefügt und mit removeCue(cue) entfernt.

Parameter

Name	Typ	Beschreibung
$startTime Pflicht	number	Startzeit der Cue in Sekunden relativ zum Medienbeginn.
$endTime Pflicht	number	Endzeit der Cue in Sekunden. Sollte größer als `startTime` sein.
$text Pflicht	string	Inhalt der Cue; darf WebVTT-Cue-Markup enthalten (z. B. `<b>`, `<i>`, `<c.klasse>`, `<v Name>`).

Rückgabewert

Typ

VTTCue

Beschreibung

Eine neue VTTCue-Instanz, die noch keiner Spur zugeordnet ist (track ist null), bis sie per addCue() hinzugefügt wird.

Beispiele

Untertitel dynamisch zu einem Video hinzufügen

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

// Neue Untertitelspur anlegen und sichtbar schalten
const track = video.addTextTrack('subtitles', 'Deutsch', 'de');
track.mode = 'showing';

const cue1 = new VTTCue(0, 3.5, 'Willkommen zu unserem Tutorial!');
const cue2 = new VTTCue(4, 8, '<v Anna>Heute geht es um <b>WebVTT</b>.');

track.addCue(cue1);
track.addCue(cue2);

console.log(track.cues.length);

2

Position und Ausrichtung einer Cue festlegen

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

const cue = new VTTCue(2, 6, '[Musik setzt ein]');
cue.snapToLines = false; // line wird als Prozentwert interpretiert
cue.line = 10;           // 10 % vom oberen Rand
cue.position = 90;       // 90 % horizontal
cue.positionAlign = 'line-right';
cue.align = 'end';
cue.size = 30;           // Breite der Cue-Box in %

track.addCue(cue);
console.log(cue.line, cue.align);

10 end

Untertitel aus JSON laden und Ereignisse nutzen

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

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

  for (const { start, end, text } of entries) {
    const cue = new VTTCue(start, end, text);
    cue.addEventListener('enter', () => console.log('Angezeigt:', cue.text));
    track.addCue(cue);
  }
};

loadSubtitles('/untertitel/folge1.json');

Angezeigt: … (bei Erreichen jeder Cue während der Wiedergabe)

Metadaten-Cues für zeitgesteuerte Aktionen

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

const cue = new VTTCue(30, 31, JSON.stringify({ kapitel: 'Einleitung beendet' }));
meta.addCue(cue);

meta.addEventListener('cuechange', () => {
  const active = meta.activeCues[0];
  if (active) console.log(JSON.parse(active.text).kapitel);
});

Einleitung beendet

// Wichtig · Fallstricke

Sichtbarkeit: Eine mit addTextTrack() erzeugte Spur hat standardmäßig mode = "hidden". Ohne track.mode = "showing" werden die Cues nicht angezeigt.
snapToLines: Ist es true (Standard), wird line als Zeilennummer interpretiert (negativ = von unten), sonst als Prozentwert. Ein häufiger Grund für „verschwundene“ Untertitel.
Markup: text wird als WebVTT-Cue-Text geparst, nicht als HTML. Nur WebVTT-Tags sind erlaubt; Skripte werden nicht ausgeführt. getCueAsHTML() liefert ein sicheres DocumentFragment – dennoch Benutzereingaben nicht ungeprüft per innerHTML weiterverwenden.
Styling: Das Aussehen wird über das CSS-Pseudoelement ::cue gesteuert; Safari und Firefox unterstützen nur eine Teilmenge der Eigenschaften.
Kompatibilität: In allen modernen Browsern verfügbar. Ältere Edge-/IE-Versionen kannten nur TextTrackCue als Konstruktor. VTTRegion und region werden nicht überall vollständig unterstützt. In Node.js existiert VTTCue nicht.
Die Enumerationswerte (align: "start" | "center" | "end" | "left" | "right"; vertical: "" | "rl" | "lr") sind streng: Ungültige Werte werden ignoriert oder lösen einen Fehler aus.

Siehe auch

DataCue Attr Cache Fence VRPose