TextTrackCueList — Schnittstelle · JavaScript-Referenz

Signatur

interface TextTrackCueList

Beschreibung

Das Interface TextTrackCueList gehört zur WebVTT-API. Es steht für eine laufend aktualisierte („live“) Liste von TextTrackCue-Objekten, meist VTTCue-Instanzen. Eigene Instanzen legt man nicht an. Man bekommt die Liste über TextTrack.cues (alle Cues einer Spur) oder TextTrack.activeCues (die Cues, die gerade zum aktuellen Wiedergabezeitpunkt aktiv sind).

Die Liste ist nach Startzeit sortiert. Bei gleicher Startzeit kommt der Cue mit der späteren Endzeit zuerst. Auf die Einträge greift man per Index zu (list[0]), die Anzahl liefert length. Zusätzlich gibt es die Methode getCueById(id): Sie gibt den ersten Cue zurück, dessen id zur übergebenen Zeichenkette passt.

Typische Einsatzfälle sind eigene Untertitel-Anzeigen, interaktive Transkripte, Kapitelnavigationen oder das Auswerten von Metadaten-Spuren (kind="metadata"). Weil die Liste live ist, ändert sich ihr Inhalt, sobald Cues per addCue()/removeCue() hinzukommen oder wegfallen oder die Wiedergabe fortschreitet (bei activeCues).

length – Anzahl der Cues (nur lesbar).
getCueById(id) – sucht einen Cue anhand seiner Kennung.
Indexzugriff list[index] – liefert den Cue an der Position oder undefined.

Parameter

Name	Typ	Default	Beschreibung
$id Pflicht	string		Parameter von `getCueById(id)`: die Kennung des gesuchten Cues. In WebVTT-Dateien ist das die optionale Zeile vor der Zeitangabe.
$index Pflicht	number		Index für den Zugriff per Klammerschreibweise `list[index]`. Die Zählung beginnt bei 0.

Rückgabewert

Typ

TextTrackCueList

Beschreibung

Die Liste selbst stammt aus TextTrack.cues bzw. TextTrack.activeCues. Beide sind null, solange der Modus der Spur "disabled" ist. getCueById() gibt einen TextTrackCue zurück oder null, wenn keiner passt.

Beispiele

Alle Cues einer Untertitelspur auflisten

const video = document.querySelector('video');
const track = video.textTracks[0];

// Ohne passenden Modus sind die Cues nicht verfügbar
track.mode = 'hidden';

const trackEl = video.querySelector('track');
trackEl.addEventListener('load', () => {
  const cues = track.cues; // TextTrackCueList
  console.log(`Anzahl Cues: ${cues.length}`);
  for (const cue of Array.from(cues)) {
    console.log(`${cue.startTime.toFixed(1)}s – ${cue.endTime.toFixed(1)}s: ${cue.text}`);
  }
});

Anzahl Cues: 3 0.0s – 2.5s: Hallo! 2.5s – 5.0s: Willkommen zum Video. 5.0s – 8.0s: Los geht's.

Aktive Cues für eigene Untertitel-Anzeige nutzen

const video = document.querySelector('video');
const output = document.querySelector('#untertitel');
const track = video.textTracks[0];
track.mode = 'hidden'; // Browser-Darstellung aus, Cues bleiben verfügbar

track.addEventListener('cuechange', () => {
  const active = track.activeCues; // TextTrackCueList
  output.textContent = Array.from(active ?? [])
    .map((cue) => cue.text)
    .join('\n');
});

Cue per ID suchen und zur Stelle springen

const video = document.querySelector('video');
const track = video.addTextTrack('chapters', 'Kapitel', 'de');
track.mode = 'hidden';

const intro = new VTTCue(0, 30, 'Einleitung');
intro.id = 'intro';
const demo = new VTTCue(30, 90, 'Live-Demo');
demo.id = 'demo';
track.addCue(intro);
track.addCue(demo);

const cue = track.cues.getCueById('demo');
if (cue) {
  video.currentTime = cue.startTime;
  console.log(`Springe zu: ${cue.text} (${cue.startTime}s)`);
}
console.log(track.cues.getCueById('gibtsnicht'));

Springe zu: Live-Demo (30s) null

// Wichtig · Fallstricke

Kein echtes Array: map, filter und forEach fehlen. Vorher mit Array.from(list) oder [...list] umwandeln. for...of funktioniert in modernen Browsern direkt.
Live-Liste: Wer beim Durchlaufen Cues per removeCue() entfernt, verschiebt die Indizes. Deshalb vorher eine Kopie anlegen oder rückwärts durchlaufen.
null bei deaktivierter Spur: Ist track.mode === \"disabled\" (Standard bei nicht voreingestellten Spuren), sind cues und activeCues gleich null. Setzen Sie den Modus auf \"hidden\" oder \"showing\".
Laden abwarten: Bei <track>-Elementen ist die Liste erst nach dem load-Ereignis gefüllt. Externe VTT-Dateien von anderen Ursprüngen brauchen CORS und das Attribut crossorigin am Medienelement.
getCueById() liefert nur den ersten Treffer. IDs müssen nicht eindeutig sein.
Kompatibilität: Wird von allen modernen Browsern unterstützt. Sehr alte Browser (vor ca. 2013) kennen die WebVTT-API nur teilweise.

Siehe auch

TextTrackList TextTrackCue TextTrack AudioTrackList ImageTrackList