TextTrack.addCue() — Methode · JavaScript-Referenz

Signatur

TextTrack.prototype.addCue(cue)

Beschreibung

Mit addCue() fügt man einer Textspur (TextTrack) eines <video>- oder <audio>-Elements per Skript eine Cue hinzu. Eine Cue ist ein Zeitabschnitt mit Start- und Endzeit sowie Inhalt, meist ein VTTCue mit Untertiteltext. Die Cue landet in der Liste track.cues, die intern nach Startzeit sortiert ist.

Sinnvoll ist das bei dynamisch erzeugten Untertiteln (z. B. Live-Transkription, Übersetzung per API), bei Kapitelmarken oder bei Metadaten-Spuren (kind: "metadata"), über die man zu bestimmten Zeitpunkten eigene Logik anstößt. Die Spur legt man dafür meist mit HTMLMediaElement.addTextTrack() an.

Gehört die Cue schon zu einer anderen Spur, wird sie dort zuerst entfernt und dann hier eingefügt. Eine Cue kann also immer nur zu einer einzigen Spur gehören. Sichtbar wird die Spur erst, wenn ihr mode auf "showing" steht. Bei "hidden" werden die Cues zwar ausgewertet (cuechange, enter/exit), aber nicht dargestellt.

Parameter

Name	Typ	Default	Beschreibung
$cue Pflicht	TextTrackCue \| VTTCue		Die Cue, die hinzugefügt werden soll, meist `new VTTCue(startTime, endTime, text)`. Gehört sie schon zu einer anderen Spur, wird sie dort entfernt.

Beispiele

Untertitel per Skript hinzufügen

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

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

track.addCue(new VTTCue(0, 3, 'Willkommen zum Tutorial!'));
track.addCue(new VTTCue(3.5, 7, 'Heute geht es um die TextTrack-API.'));

console.log(track.cues.length);

2

Untertitel aus JSON-Daten einer API laden

const video = document.querySelector('video');
const track = video.addTextTrack('captions', 'Automatisch', '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) {
    const cue = new VTTCue(start, end, text);
    cue.line = -2;          // etwas über dem unteren Rand
    cue.align = 'center';
    track.addCue(cue);
  }
  console.log(`${track.cues.length} Cues geladen`);
};

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

z. B. "18 Cues geladen"

Metadaten-Spur für zeitgesteuerte Aktionen

const video = document.querySelector('video');
const meta = video.addTextTrack('metadata', 'Kapitel');
meta.mode = 'hidden'; // auswerten, aber nicht anzeigen

const chapters = [
  { start: 0, end: 60, id: 'intro' },
  { start: 60, end: 180, id: 'grundlagen' },
  { start: 180, end: 300, id: 'praxis' }
];

for (const { start, end, id } of chapters) {
  const cue = new VTTCue(start, end, JSON.stringify({ id }));
  cue.id = id;
  cue.addEventListener('enter', () => {
    console.log('Kapitel gestartet:', id);
    document.querySelector(`#nav-${id}`)?.classList.add('aktiv');
  });
  cue.addEventListener('exit', () => {
    document.querySelector(`#nav-${id}`)?.classList.remove('aktiv');
  });
  meta.addCue(cue);
}

Kapitel gestartet: intro (beim Abspielen ab 0 s)

// Wichtig · Fallstricke

Sichtbarkeit: Eine neue Spur aus addTextTrack() steht auf mode = "hidden". Ohne track.mode = "showing" sieht man keine Untertitel. Bei "disabled" ist track.cues sogar null.
Keine Duplikatprüfung: Dieselbe Textzeile mit gleichen Zeiten lässt sich mehrfach anlegen, dann erscheint sie doppelt. Vor dem Neuladen alte Cues mit removeCue() entfernen.
Ungültige Zeiten: Liegt endTime vor startTime, wird die Cue nie aktiv. Die Browser prüfen das nicht einheitlich.
Performance: Tausende einzelne addCue()-Aufrufe während der Wiedergabe können das Rendering bremsen. Cues deshalb möglichst gebündelt anlegen.
Kompatibilität: addCue() und VTTCue gibt es in allen modernen Browsern. Das allgemeine TextTrackCue hat keinen öffentlichen Konstruktor, deshalb VTTCue verwenden. Der Internet Explorer kannte nur das veraltete TextTrackCue-Konstruktormuster.
Sicherheit: Der Cue-Text wird als WebVTT-Markup ausgewertet, nicht als HTML. Wer Inhalte daraus später per getCueAsHTML() oder innerHTML ins DOM schreibt, sollte Benutzereingaben trotzdem bereinigen.

Siehe auch

TextTrack TextTrack.removeCue() TextTrack.cues TextTrack.mode VTTCue HTMLMediaElement.addTextTrack()