AudioTrackList: change — Ereignis · JavaScript-Referenz

Signatur

audioTrackList.addEventListener("change", handler)

Beschreibung

Das change-Ereignis der AudioTrackList tritt auf, sobald sich bei einem der enthaltenen Audiotracks die Eigenschaft enabled ändert. Das kann per Skript passieren (track.enabled = true) oder über die eingebaute Oberfläche des Browsers, etwa wenn Nutzerinnen und Nutzer in den Mediensteuerelementen eine andere Tonspur (Sprachfassung, Audiodeskription, Kommentar) wählen.

Das Ereignis ist ein einfaches Event ohne zusätzliche Daten. Es sagt also nicht, welcher Track sich geändert hat. Um den aktuellen Zustand zu bestimmen, durchläuft man im Handler die Liste und fragt bei jedem Track enabled ab. Das Ereignis lässt sich nicht abbrechen und steigt nicht auf (kein Bubbling).

Man registriert den Handler entweder mit addEventListener("change", handler) oder über die Eigenschaft audioTracks.onchange. Die Liste bekommt man über HTMLMediaElement.audioTracks eines <video>- oder <audio>-Elements. Das Ereignis eignet sich gut, um eine eigene Sprachauswahl mit dem tatsächlichen Wiedergabezustand abzugleichen.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname, hier immer `"change"`.
$handler Pflicht	(event: Event) => void		Callback, das bei jeder Änderung des `enabled`-Zustands eines Tracks aufgerufen wird. `event.target` ist die `AudioTrackList`.
$options	boolean \| AddEventListenerOptions	false	Optionale Einstellungen wie `once` oder `signal` (zum Entfernen per `AbortController`).

Beispiele

Aktive Tonspur mit addEventListener protokollieren

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

if (!tracks) {
  console.warn('AudioTrackList wird von diesem Browser nicht unterstützt.');
} else {
  tracks.addEventListener('change', () => {
    const aktiv = Array.from(tracks).filter((t) => t.enabled);
    console.log('Aktive Tonspuren:', aktiv.map((t) => `${t.label} (${t.language})`));
  });
}

Aktive Tonspuren: ["Deutsch (de)"]

Eigene Sprachauswahl mit onchange synchronisieren

const video = document.querySelector('#film');
const select = document.querySelector('#sprache');
const tracks = video.audioTracks;

// Auswahlliste aus den vorhandenen Tonspuren aufbauen
const fuelleAuswahl = () => {
  select.replaceChildren(...Array.from(tracks, (t) => new Option(t.label || t.language, t.id)));
};

// Nutzerwahl -> genau eine Spur aktivieren
select.addEventListener('change', () => {
  for (const t of tracks) t.enabled = t.id === select.value;
});

// Änderungen über die nativen Controls zurück ins Select spiegeln
tracks.onchange = () => {
  const aktiv = Array.from(tracks).find((t) => t.enabled);
  if (aktiv) select.value = aktiv.id;
};

video.addEventListener('loadedmetadata', fuelleAuswahl);

Listener wieder entfernen

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

const beiWechsel = () => console.log('Tonspur gewechselt');
tracks.addEventListener('change', beiWechsel);

// später, z. B. beim Abbau einer Komponente:
tracks.removeEventListener('change', beiWechsel);

// Alternative über die on-Property:
tracks.onchange = beiWechsel;
tracks.onchange = null; // entfernt den Handler

// Wichtig · Fallstricke

Browser-Kompatibilität: HTMLMediaElement.audioTracks und damit dieses Ereignis werden nur von Safari standardmäßig unterstützt. In Chrome/Edge (--enable-experimental-web-platform-features) und Firefox (media.track.enabled) nur hinter einem Flag. Immer prüfen, ob video.audioTracks vorhanden ist.
Das Ereignis sagt nicht, welcher Track sich geändert hat. Den Zustand immer neu aus der Liste lesen.
Werden in einem Durchlauf mehrere Tracks umgeschaltet, kann das Ereignis nur einmal kommen (es wird gesammelt als Task ausgelöst). Den Handler nicht so schreiben, dass er genau ein Ereignis pro Track erwartet.
Nicht verwechseln mit addtrack/removetrack: Diese melden, dass Tracks hinzugefügt oder entfernt wurden. change meldet nur Änderungen an enabled.
Bei Videospuren heißt die entsprechende Eigenschaft selected statt enabled (siehe VideoTrackList: change).

Siehe auch

AudioTrackList AudioTrack.enabled HTMLMediaElement.audioTracks EventTarget.addEventListener() AudioTrackList: addtrack