TextTrackCue — Schnittstelle · JavaScript-Referenz

Signatur

interface TextTrackCue extends EventTarget

Beschreibung

TextTrackCue ist die gemeinsame Basis aller Cues, die zu einer TextTrack eines <video>- oder <audio>-Elements gehören. Ein Cue ist ein Eintrag mit Start- und Endzeit, zum Beispiel eine Untertitelzeile, ein Kapitelname oder ein Metadaten-Block.

Die Klasse ist abstrakt: new TextTrackCue() löst einen TypeError aus. In der Praxis erzeugen Sie VTTCue-Objekte (Untertitel, Kapitel, Metadaten) oder in Safari DataCue-Objekte. Die gemeinsamen Eigenschaften sind:

track: die TextTrack, zu der der Cue gehört, oder null
id: frei wählbare Kennung (entspricht der Cue-ID in WebVTT)
startTime / endTime: Start- und Endzeit in Sekunden (double)
pauseOnExit: wenn true, pausiert die Wiedergabe am Ende des Cues

Zusätzlich löst jeder Cue die Events enter und exit aus, sobald die Wiedergabeposition den Cue betritt bzw. verlässt. So lassen sich zeitgesteuerte Aktionen umsetzen, etwa Quizfragen, Einblendungen oder synchronisierte Inhalte.

Rückgabewert

Typ

TextTrackCue

Beschreibung

Wird nie direkt erzeugt; Instanzen sind immer abgeleitete Typen wie VTTCue.

Beispiele

Cue über VTTCue erzeugen und einer Spur hinzufügen

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

// VTTCue erbt von TextTrackCue
const cue = new VTTCue(1.5, 4, 'Willkommen zum Tutorial!');
cue.id = 'intro';
track.addCue(cue);

console.log(cue instanceof TextTrackCue, cue.startTime, cue.endTime, cue.track === track);

true 1.5 4 true

enter- und exit-Events für zeitgesteuerte Aktionen

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

const quizCue = new VTTCue(10, 15, JSON.stringify({ frage: 'Was ist ein Cue?' }));
quizCue.pauseOnExit = true; // Video stoppt nach 15 s

quizCue.addEventListener('enter', () => {
  const { frage } = JSON.parse(quizCue.text);
  console.log('Quiz einblenden:', frage);
});
quizCue.onexit = () => console.log('Quiz-Abschnitt beendet');

track.addCue(quizCue);

Quiz einblenden: Was ist ein Cue? Quiz-Abschnitt beendet

Alle Cues einer geladenen Spur auslesen

const trackEl = document.querySelector('track[kind="chapters"]');

trackEl.addEventListener('load', () => {
  const { cues } = trackEl.track;
  for (const cue of cues) {
    console.log(`${cue.id || '-'}: ${cue.startTime}s–${cue.endTime}s`);
  }
});
// Wichtig: mode darf nicht 'disabled' sein, sonst wird nichts geladen
trackEl.track.mode = 'hidden';

kap1: 0s–60s kap2: 60s–180s

Abstrakte Klasse kann nicht instanziiert werden

try {
  new TextTrackCue(0, 1);
} catch (err) {
  console.log(err.name);
}

TypeError

// Wichtig · Fallstricke

Nicht instanziierbar: new TextTrackCue() wirft einen TypeError. Verwenden Sie VTTCue. DataCue gibt es derzeit nur in Safari.
Spur-Modus beachten: Ist track.mode auf 'disabled' gesetzt, sind cues/activeCues null und enter/exit feuern nicht. Für unsichtbare Metadaten verwenden Sie 'hidden'.
Ungenaues Timing: Die Events werden im Rahmen des Wiedergabe-Updates ausgelöst (typisch alle 15–250 ms). Bei sehr kurzen Cues oder beim Springen (Seeking) kann enter verspätet kommen oder ganz ausfallen.
Ändern Sie startTime/endTime eines bereits hinzugefügten Cues, sortiert der Browser die Liste neu. Das Entfernen geschieht mit track.removeCue(cue).
Sicherheit: Der Cue-Text kann aus fremden Quellen stammen. Fügen Sie ihn nie ungeprüft per innerHTML ein, sondern verwenden Sie textContent oder VTTCue.getCueAsHTML(). Externe .vtt-Dateien aus anderen Ursprüngen brauchen CORS und das Attribut crossorigin am Medienelement.
Die Unterstützung in modernen Browsern ist gut. Das Styling über ::cue ist aber je nach Browser eingeschränkt.

Siehe auch

VTTCue TextTrack TextTrackCueList HTMLMediaElement.addTextTrack() TextTrack.addCue() HTMLTrackElement