TrackEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface TrackEvent extends Event

Beschreibung

Das Interface TrackEvent gehört zur HTML-DOM-API und beschreibt Ereignisse, bei denen sich die Menge der verfügbaren Tracks eines <audio>- oder <video>-Elements ändert. Ausgelöst werden die Ereignisse addtrack und removetrack, und zwar nicht am Medienelement selbst, sondern an seinen Track-Listen: AudioTrackList (media.audioTracks), VideoTrackList (media.videoTracks) und TextTrackList (media.textTracks).

Die wichtigste Eigenschaft ist track. Sie verweist auf das betroffene AudioTrack-, VideoTrack- oder TextTrack-Objekt, oder sie ist null. Darüber kannst du z. B. kind, label, language oder id des Tracks auslesen und damit eine Auswahl für Untertitel oder Tonspuren in einem eigenen Player aktualisieren.

Typische Einsatzfälle sind eigene Mediaplayer, die ein Menü für Sprachen und Untertitel dynamisch aufbauen, sowie Streaming-Szenarien mit MSE oder HLS, bei denen Tracks erst während der Wiedergabe dazukommen. Mit dem Konstruktor new TrackEvent(type, options) kannst du solche Ereignisse auch selbst erzeugen, etwa für Tests.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Konstruktor-Parameter: Name des Ereignisses, meist `"addtrack"` oder `"removetrack"` (Groß-/Kleinschreibung beachten).
$options	object	{}	Konstruktor-Optionen. Erlaubt sind alle Optionen von `Event` (`bubbles`, `cancelable`, `composed`) und zusätzlich `track`.
$options.track	AudioTrack \| VideoTrack \| TextTrack \| null	null	Der Track, auf den sich das Ereignis bezieht. Er ist später als `event.track` lesbar.

Rückgabewert

Typ

TrackEvent

Beschreibung

Der Konstruktor liefert eine neue TrackEvent-Instanz. Die Eigenschaft track (nur lesbar) enthält den betroffenen Track oder null.

Beispiele

Neue Untertitel-Spuren per addEventListener erkennen

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

const onAddTrack = (event) => {
  const { kind, label, language } = event.track;
  console.log(`Neuer Track: ${kind} – ${label || '(ohne Titel)'} [${language}]`);
};

video.textTracks.addEventListener('addtrack', onAddTrack);

// Track per Skript hinzufügen: löst addtrack aus
video.addTextTrack('subtitles', 'Deutsch', 'de');

// Später wieder abmelden
// video.textTracks.removeEventListener('addtrack', onAddTrack);

Neuer Track: subtitles – Deutsch [de]

Tonspur-Menü über on-Properties aktuell halten

const video = document.querySelector('video');
const select = document.querySelector('#audio-select');

const rebuildMenu = () => {
  select.replaceChildren(
    ...Array.from(video.audioTracks ?? [], (t) =>
      new Option(t.label || t.language || t.id, t.id, false, t.enabled)
    )
  );
};

if (video.audioTracks) {
  video.audioTracks.onaddtrack = (e) => {
    console.log('Tonspur hinzugefügt:', e.track.id);
    rebuildMenu();
  };
  video.audioTracks.onremovetrack = (e) => {
    console.log('Tonspur entfernt:', e.track.id);
    rebuildMenu();
  };
} else {
  console.warn('audioTracks wird von diesem Browser nicht unterstützt.');
}

TrackEvent selbst erzeugen (z. B. für Tests)

const video = document.createElement('video');
const track = video.addTextTrack('captions', 'English', 'en');

video.textTracks.addEventListener('removetrack', (e) => {
  console.log(e instanceof TrackEvent, e.type, e.track.label);
});

const evt = new TrackEvent('removetrack', { track });
video.textTracks.dispatchEvent(evt);

true removetrack English

// Wichtig · Fallstricke

Falsches Ziel: addtrack und removetrack werden an den Track-Listen (textTracks, audioTracks, videoTracks) ausgelöst, nicht am <video>-Element. Ein Listener direkt auf dem Element bekommt diese Ereignisse nie. Sie steigen auch nicht nach oben auf (kein Bubbling).
Kompatibilität: TrackEvent und textTracks funktionieren in allen modernen Browsern. audioTracks und videoTracks fehlen dagegen in Firefox standardmäßig und in Chrome ohne Flag. Prüfe deshalb immer vorher, ob sie vorhanden sind (if (video.audioTracks)).
Zeitpunkt: Tracks aus <track>-Elementen im HTML sind oft schon da, bevor dein Skript den Listener anmeldet. Lies deshalb zusätzlich den aktuellen Inhalt der Liste aus, statt dich nur auf addtrack zu verlassen.
event.track kann bei selbst erzeugten Ereignissen null sein. Prüfe den Wert, bevor du darauf zugreifst.
Das Ereignis lässt sich nicht abbrechen. preventDefault() hat keine Wirkung.

Siehe auch

TextTrackList AudioTrackList VideoTrackList TextTrack HTMLMediaElement HTMLMediaElement.addTextTrack() Event