HTMLMediaElement.textTracks — Eigenschaft · JavaScript-Referenz

Signatur

HTMLMediaElement.textTracks

Beschreibung

Die Eigenschaft textTracks gibt ein TextTrackList-Objekt zurück. Es enthält für jede Textspur des Media-Elements ein TextTrack-Objekt, und zwar in der Reihenfolge, in der die Spuren angelegt wurden. Dazu gehören Spuren aus <track>-Kindelementen, Spuren, die per Skript mit addTextTrack() erzeugt wurden, und im Container eingebettete Spuren (In-Band-Spuren, z. B. bei HLS oder MP4 in Safari).

Jede Spur hat eine Art (kind: subtitles, captions, descriptions, chapters, metadata), eine Sprache (language), eine Beschriftung (label) und einen Modus (mode: "disabled", "hidden", "showing"). Über mode schaltet man Untertitel ein oder aus. Das ist die Grundlage für eigene Untertitel-Menüs in selbstgebauten Playern.

Die Liste selbst ist „live“: Sie aktualisiert sich automatisch und löst die Ereignisse addtrack, removetrack und change aus. Man kann sie wie ein Array mit Index und length durchlaufen. Mit for...of oder Array.from() lässt sie sich ebenfalls iterieren.

Rückgabewert

Typ

TextTrackList

Beschreibung

Eine live aktualisierte, iterierbare Liste von TextTrack-Objekten. Hat das Element keine Textspuren, ist die Liste leer (length === 0). Es wird nie null zurückgegeben.

Beispiele

Alle Textspuren auflisten

// HTML: <video id="film" src="film.mp4">
//   <track kind="subtitles" src="de.vtt" srclang="de" label="Deutsch" default>
//   <track kind="subtitles" src="en.vtt" srclang="en" label="English">
// </video>
const video = document.getElementById('film');

for (const track of video.textTracks) {
  console.log(`${track.label} (${track.language}) – ${track.kind}, Modus: ${track.mode}`);
}

Deutsch (de) – subtitles, Modus: showing English (en) – subtitles, Modus: disabled

Untertitel-Sprache umschalten

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

const setSubtitleLanguage = (lang) => {
  for (const track of video.textTracks) {
    if (track.kind !== 'subtitles' && track.kind !== 'captions') continue;
    track.mode = track.language === lang ? 'showing' : 'disabled';
  }
};

// Englische Untertitel anzeigen
setSubtitleLanguage('en');
// Alle Untertitel ausschalten
setSubtitleLanguage(null);

Auf neue Spuren und Moduswechsel reagieren

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

tracks.addEventListener('addtrack', (event) => {
  console.log('Neue Spur:', event.track.label || event.track.kind);
});

tracks.addEventListener('change', () => {
  const aktiv = Array.from(tracks).find((t) => t.mode === 'showing');
  console.log('Aktive Spur:', aktiv ? aktiv.label : 'keine');
});

// Spur per Skript hinzufügen – löst "addtrack" aus
const meta = video.addTextTrack('metadata', 'Kapitelmarken', 'de');
meta.mode = 'hidden';
meta.addCue(new VTTCue(0, 10, 'Intro'));

Neue Spur: Kapitelmarken

Aktuelle Cues einer versteckten Spur auswerten

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

// "hidden": Cues werden geladen und Ereignisse ausgelöst, aber nicht angezeigt
track.mode = 'hidden';

track.addEventListener('cuechange', () => {
  const cue = track.activeCues[0];
  document.getElementById('untertitel').textContent = cue ? cue.text : '';
});

// Wichtig · Fallstricke

Schreibgeschützt: video.textTracks = … hat keine Wirkung. Spuren fügt man über <track>-Elemente oder addTextTrack() hinzu. Mit addTextTrack() erzeugte Spuren lassen sich nicht wieder entfernen, sondern nur mit mode = "disabled" deaktivieren.
Cues werden erst geladen, wenn die Spur aktiv ist: Bei mode === "disabled" ist track.cues null. Wenn man die Cues nur auslesen möchte, setzt man zuerst mode = "hidden".
Keine echte Array-Instanz: Methoden wie map oder filter fehlen. Man wandelt die Liste daher vorher mit Array.from() oder dem Spread-Operator um.
CORS: WebVTT-Dateien von einer fremden Origin laden nur, wenn das Media-Element das Attribut crossorigin hat und der Server passende CORS-Header sendet. Andernfalls bleibt die Spur still leer.
Browser-Unterschiede: Die Eigenschaft wird in allen modernen Browsern unterstützt. In-Band-Spuren (z. B. aus HLS-Streams) erscheinen zuverlässig vor allem in Safari. Bei eingeschalteter nativer Untertitelanzeige kann der Browser mode selbst ändern. Deshalb auf change hören und den eigenen Zustand nicht zwischenspeichern.

Siehe auch

HTMLMediaElement.audioTracks HTMLMediaElement.videoTracks HTMLMediaElement.controls HTMLMediaElement.error HTMLMediaElement.mediaKeys