HTMLMediaElement.addTextTrack() — Methode · JavaScript-Referenz

Signatur

HTMLMediaElement.prototype.addTextTrack(kind, label, language)

Beschreibung

Mit addTextTrack() erzeugst du eine Textspur direkt in JavaScript, ohne ein <track>-Element ins HTML zu schreiben und ohne WebVTT-Datei. Die neue Spur landet in media.textTracks. Mit track.addCue(new VTTCue(start, end, text)) füllst du sie anschließend mit Cues.

Typische Einsatzfälle sind dynamisch erzeugte Untertitel, z. B. aus einer JSON-API oder einer Live-Transkription, Kapitelmarken und vor allem Metadaten-Spuren (kind = "metadata"). Die werden nicht angezeigt, lösen aber zeitgenau cuechange-Events aus. So kannst du Aktionen an bestimmte Stellen der Wiedergabe koppeln, etwa Quiz-Einblendungen, Werbemarker oder Szenenwechsel.

Eine per addTextTrack() erzeugte Spur startet im Modus "hidden". Cues sind damit aktiv und Events werden ausgelöst, aber es wird nichts angezeigt. Für sichtbare Untertitel musst du track.mode = "showing" explizit setzen. Anders als bei <track>-Elementen gibt es kein zugehöriges DOM-Element, und die Spur lässt sich über die API nicht wieder entfernen. Du kannst sie nur mit mode = "disabled" abschalten.

Parameter

Name	Typ	Default	Beschreibung
$kind Pflicht	"subtitles" \| "captions" \| "descriptions" \| "chapters" \| "metadata"		Art der Textspur. Ein ungültiger Wert löst einen `TypeError` aus.
$label	string	""	Für Menschen lesbarer Name der Spur, z. B. `"Deutsch"`. Er erscheint unter Umständen im Untertitel-Menü des Browsers.
$language	string	""	BCP-47-Sprachcode der Spur, z. B. `"de"` oder `"en-US"`.

Rückgabewert

Typ

TextTrack

Beschreibung

Das neu erzeugte TextTrack-Objekt im Modus "hidden". Es ist bereits in media.textTracks eingetragen.

Beispiele

Deutsche Untertitel per Skript hinzufügen

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

// Neue Untertitelspur anlegen
const track = video.addTextTrack('subtitles', 'Deutsch', 'de');

// Cues hinzufügen (Zeiten in Sekunden)
track.addCue(new VTTCue(0, 3, 'Willkommen zum Tutorial!'));
track.addCue(new VTTCue(3.5, 7, 'Heute geht es um Textspuren.'));

// Standardmäßig "hidden", für die Anzeige explizit aktivieren
track.mode = 'showing';

console.log(track.kind, track.label, track.language, track.mode);

subtitles Deutsch de showing

Untertitel aus einer JSON-API laden

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

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

  const track = video.addTextTrack('captions', 'Englisch (CC)', 'en');
  for (const { start, end, text } of entries) {
    track.addCue(new VTTCue(start, end, text));
  }
  track.mode = 'showing';
  return track;
};

loadSubtitles('/api/videos/42/captions')
  .then((track) => console.log(`${track.cues.length} Cues geladen`));

z. B.: 128 Cues geladen

Metadaten-Spur für zeitgesteuerte Aktionen

const video = document.querySelector('video');
const quizBox = document.querySelector('#quiz');

const meta = video.addTextTrack('metadata', 'Quiz-Marker');

// Nutzdaten als JSON-String im Cue-Text ablegen
meta.addCue(new VTTCue(10, 15, JSON.stringify({ frage: 'Was ist ein Cue?' })));
meta.addCue(new VTTCue(30, 35, JSON.stringify({ frage: 'Welcher Modus ist Standard?' })));

// "hidden" reicht: Events kommen, aber es wird nichts eingeblendet
meta.addEventListener('cuechange', () => {
  const [cue] = meta.activeCues;
  quizBox.textContent = cue ? JSON.parse(cue.text).frage : '';
});

// Wichtig · Fallstricke

Standardmodus ist "hidden": Wenn du vergisst, mode = "showing" zu setzen, erscheinen keine Untertitel. Das ist der häufigste Fehler.
Kein Entfernen möglich: Es gibt kein removeTextTrack(). Wiederholte Aufrufe (z. B. bei einem Sprachwechsel) erzeugen immer neue Spuren. Nutze vorhandene Spuren weiter, entferne veraltete Cues mit removeCue() oder schalte die Spur mit mode = "disabled" ab.
Ungültiges kind führt zu einem TypeError.
VTTCue gibt es in allen modernen Browsern. Sehr alte Edge- oder IE-Versionen kannten nur TextTrackCue als Konstruktor.
Sicherheit: Cue-Texte werden als WebVTT-Text dargestellt, nicht als HTML. Wenn du Cue-Inhalte aus Metadaten-Spuren selbst ins DOM schreibst, verwende textContent statt innerHTML, um XSS zu vermeiden.
Die Darstellung der Untertitel (Position, Stil) lässt sich über das CSS-Pseudoelement ::cue anpassen.

Siehe auch

HTMLMediaElement.getStartDate() HTMLMediaElement.seekToNextFrame() HTMLMediaElement.captureStream() HTMLMediaElement.fastSeek() HTMLMediaElement.canPlayType()