TextTrackList: addtrack — Ereignis · JavaScript-Referenz

Signatur

textTrackList.addEventListener("addtrack", handler)

Beschreibung

Das Ereignis addtrack wird an der TextTrackList eines Medienelements (video.textTracks bzw. audio.textTracks) ausgelöst, sobald ein neuer TextTrack in die Liste aufgenommen wird. Das passiert zum Beispiel, wenn per DOM ein <track>-Element eingefügt wird, wenn ein Skript HTMLMediaElement.addTextTrack() aufruft oder wenn der Browser eingebettete Text-Tracks im Medienstrom findet (etwa In-Band-Untertitel bei HLS).

Der Handler bekommt ein TrackEvent. Dessen Eigenschaft track verweist auf den neu hinzugefügten TextTrack. So kann man ein eigenes Untertitel-Menü dynamisch aufbauen, den Modus des Tracks ("showing", "hidden", "disabled") setzen oder einen cuechange-Listener registrieren.

Man kann den Handler mit addEventListener("addtrack", handler) registrieren oder über die Eigenschaft textTrackList.onaddtrack = handler zuweisen. Das Ereignis ist nicht abbrechbar und steigt nicht auf (bubbelt nicht). Das Gegenstück ist removetrack, für Statusänderungen gibt es change.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname, hier `"addtrack"`.
$handler Pflicht	(event: TrackEvent) => void		Callback-Funktion. Bekommt ein `TrackEvent`, dessen Eigenschaft `event.track` auf den hinzugefügten `TextTrack` zeigt.
$options	boolean \| AddEventListenerOptions	false	Optionale Einstellungen wie `once` oder `signal`. Alternativ ein Boolean für `capture`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler bekommt ein TrackEvent mit der Eigenschaft track.

Beispiele

Untertitel-Menü dynamisch erweitern

const video = document.querySelector('video');
const menu = document.querySelector('#untertitel-menue');

video.textTracks.addEventListener('addtrack', (event) => {
  const track = event.track;
  const option = document.createElement('option');
  option.value = track.language;
  option.textContent = track.label || track.language || 'Unbenannt';
  menu.append(option);
  console.log(`Neuer Track: ${track.kind} (${track.language})`);
});

// Track per Skript hinzufügen – löst addtrack aus
const track = video.addTextTrack('subtitles', 'Deutsch', 'de');
track.mode = 'showing';

Neuer Track: subtitles (de)

<track>-Element per DOM einfügen und über onaddtrack reagieren

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

video.textTracks.onaddtrack = ({ track }) => {
  console.log('Hinzugefügt:', track.label);
  // Standardmäßig ausgeblendet lassen, aber Cues laden
  track.mode = 'hidden';
  track.addEventListener('cuechange', () => {
    const cue = track.activeCues?.[0];
    if (cue) console.log('Aktueller Cue:', cue.text);
  });
};

const el = document.createElement('track');
el.kind = 'captions';
el.label = 'English';
el.srclang = 'en';
el.src = '/media/captions-en.vtt';
video.append(el);

Hinzugefügt: English

Listener mit AbortController sauber entfernen

const video = document.querySelector('video');
const controller = new AbortController();

const onAdd = (event) => {
  console.log('Track-Anzahl:', video.textTracks.length, '-', event.track.kind);
};

video.textTracks.addEventListener('addtrack', onAdd, { signal: controller.signal });

video.addTextTrack('chapters', 'Kapitel', 'de');

// Später, z. B. beim Abbau der Player-Komponente:
controller.abort();
// Alternativ: video.textTracks.removeEventListener('addtrack', onAdd);

Track-Anzahl: 1 - chapters

// Wichtig · Fallstricke

Bereits vorhandene Tracks: <track>-Elemente, die schon im HTML stehen, werden oft hinzugefügt, bevor dein Skript läuft. Du solltest deshalb zusätzlich einmal über die bestehende video.textTracks iterieren und dich nicht nur auf addtrack verlassen.
Das Ereignis wird asynchron ausgelöst (als Task in der Warteschlange). Direkt nach addTextTrack() ist der Track zwar schon in der Liste, der Handler läuft aber erst danach.
Ein neuer Track steht standardmäßig auf mode = "disabled" (außer bei default-Tracks). Dann werden keine Cues geladen. Setze "hidden" oder "showing", wenn du Cues auslesen willst.
Für <track>-Dateien von fremden Ursprüngen braucht es CORS-Header und das Attribut crossorigin am Medienelement.
Die Unterstützung ist in allen modernen Browsern gut. Das Feuern bei In-Band-Tracks (z. B. HLS in Safari) unterscheidet sich je nach Browser und Medienformat.

Siehe auch

TextTrackList: removetrack TextTrackList: change AudioTrackList: addtrack VideoTrackList: addtrack AudioTrackList: removetrack