TextTrackList — Schnittstelle · JavaScript-Referenz

Signatur

interface TextTrackList extends EventTarget

Beschreibung

TextTrackList ist die Liste aller Textspuren eines Medienelements. Man bekommt sie nicht über einen Konstruktor, sondern über die Eigenschaft HTMLMediaElement.textTracks. Darin stehen sowohl Spuren aus <track>-Elementen im Markup als auch Spuren, die per Skript mit HTMLMediaElement.addTextTrack() angelegt wurden.

Die Liste ist live: Kommen <track>-Elemente hinzu oder werden sie entfernt, ändert sich die Liste sofort. Man greift per Index (textTracks[0]) oder mit length auf die Einträge zu. Mit getTrackById(id) sucht man gezielt eine Spur. Weil die Liste iterierbar ist, funktionieren auch for...of und Array.from().

Wichtige Bestandteile:

length – Anzahl der Spuren (nur lesbar).
getTrackById(id) – liefert den TextTrack mit passender id oder null.
Events – addtrack, removetrack (Objekt vom Typ TrackEvent) und change, wenn sich der mode einer Spur ändert. Man kann sie per addEventListener() abonnieren oder über onaddtrack, onremovetrack und onchange zuweisen.

Typische Einsatzfälle sind eigene Untertitel-Menüs für selbstgebaute Player, das Umschalten zwischen Sprachen und das Auswerten von Metadaten-Spuren (kind="metadata") für synchronisierte Inhalte.

Parameter

Name	Typ	Default	Beschreibung
$index Pflicht	number		Beim Zugriff per Index (`list[index]`): nullbasierte Position der Spur. Liegt der Index außerhalb der Liste, ist das Ergebnis `undefined`.
$id Pflicht	string		Für `getTrackById(id)`: der Wert des `id`-Attributs des zugehörigen `<track>`-Elements.

Rückgabewert

Typ

TextTrackList

Beschreibung

Die Liste bekommt man über HTMLMediaElement.textTracks. Ein Indexzugriff liefert einen TextTrack oder undefined. getTrackById() liefert einen TextTrack oder null.

Beispiele

Liste abrufen und alle Spuren auflisten

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

console.log(`Anzahl Spuren: ${tracks.length}`);
for (const track of tracks) {
  console.log(track.label, track.language, track.mode);
}

Anzahl Spuren: 2 Deutsch de showing English en disabled

Untertitel-Sprache per getTrackById umschalten

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

const showSubtitles = (id) => {
  for (const track of video.textTracks) {
    if (track.kind === 'subtitles') track.mode = 'disabled';
  }
  const target = video.textTracks.getTrackById(id);
  if (target) target.mode = 'showing';
};

showSubtitles('en');
console.log(video.textTracks.getTrackById('en').mode);
console.log(video.textTracks.getTrackById('fr'));

showing null

Auf addtrack und change reagieren (addEventListener und on-Property)

const video = document.querySelector('#player');
const list = video.textTracks;

const onAdd = (event) => {
  console.log('Neue Spur:', event.track.label);
};
list.addEventListener('addtrack', onAdd);

// Alternativ über die on-Property
list.onchange = () => {
  const active = Array.from(list).find((t) => t.mode === 'showing');
  console.log('Aktiv:', active ? active.label : 'keine');
};

// Spur per Skript hinzufügen → löst addtrack aus
const chapters = video.addTextTrack('chapters', 'Kapitel', 'de');
chapters.mode = 'hidden';

// Später wieder abmelden
setTimeout(() => list.removeEventListener('addtrack', onAdd), 5000);

Neue Spur: Kapitel

// Wichtig · Fallstricke

Kein Array: TextTrackList hat keine Methoden wie map() oder filter(). Dafür wandelt man die Liste zuerst mit Array.from(list) oder [...list] um.
Live-Liste: Wenn während einer Schleife <track>-Elemente entfernt werden, verschieben sich die Indizes. Im Zweifel vorher eine Kopie mit Array.from() anlegen.
Kein removeTrack(): Per Skript mit addTextTrack() angelegte Spuren lassen sich nicht entfernen. Man kann sie nur über mode = 'disabled' ausschalten. Spuren aus dem Markup entfernt man, indem man das <track>-Element löscht.
Zeitpunkt: Die cues einer Spur werden erst geladen, wenn ihr mode nicht disabled ist. Direkt nach dem Seitenaufruf können sie deshalb noch null oder leer sein.
CORS: WebVTT-Dateien von fremden Domains brauchen am Medienelement das Attribut crossorigin und passende CORS-Header. Sonst lädt der Browser die Spur nicht.
Kompatibilität: Wird von allen modernen Browsern unterstützt. Das change-Event verhält sich in älteren Safari-Versionen teils uneinheitlich. Bei nativen Vollbild-Playern auf iOS entscheidet das System selbst, welche Untertitel angezeigt werden.

Siehe auch

TextTrackCueList TextTrack TextTrackCue AudioTrackList ImageTrackList