AudioTrackList: addtrack — Ereignis · JavaScript-Referenz

Signatur

audioTrackList.addEventListener("addtrack", handler)

Beschreibung

Das Ereignis addtrack wird an einer AudioTrackList ausgelöst, sobald eine neue AudioTrack in die Liste aufgenommen wird. Die Liste erhalten Sie über HTMLMediaElement.audioTracks eines <audio>- oder <video>-Elements. Das passiert typischerweise, wenn der Browser die Metadaten einer Mediendatei mit mehreren Tonspuren liest (z. B. mehrere Sprachfassungen oder ein Kommentar-Track), oder bei adaptivem Streaming, wenn neue Spuren dazukommen.

Der Handler erhält ein TrackEvent. Dessen Eigenschaft track verweist auf die hinzugefügte AudioTrack. Dort finden Sie id, kind, label, language und enabled. Das Ereignis kann nicht abgebrochen werden und steigt nicht auf (kein Bubbling).

Registrieren können Sie den Handler mit addEventListener("addtrack", …) oder über die Eigenschaft onaddtrack. Am häufigsten nutzt man das Ereignis, um eine Sprachauswahl in einem eigenen Player-Menü dynamisch aufzubauen, statt nach dem Laden die Liste einmal abzufragen.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname, hier immer `"addtrack"`.
$handler Pflicht	(event: TrackEvent) => void		Callback-Funktion. Sie erhält ein `TrackEvent`, dessen Eigenschaft `event.track` die neue `AudioTrack` enthält.
$options	boolean \| AddEventListenerOptions	false	Optionale Listener-Optionen wie `once`, `signal` oder `capture`.

Rückgabewert

Typ

void

Beschreibung

addEventListener hat keinen Rückgabewert. Der Handler bekommt ein TrackEvent mit der Eigenschaft track vom Typ AudioTrack.

Beispiele

Neue Audiospuren protokollieren (addEventListener)

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

if (video.audioTracks) {
  video.audioTracks.addEventListener("addtrack", (event) => {
    const { id, label, language, kind, enabled } = event.track;
    console.log(`Spur hinzugefügt: ${label || id} (${language}, ${kind}) aktiv=${enabled}`);
  });
} else {
  console.warn("audioTracks wird von diesem Browser nicht unterstützt.");
}

Spur hinzugefügt: Deutsch (de, main) aktiv=true Spur hinzugefügt: English (en, translation) aktiv=false

Sprachmenü dynamisch aufbauen

const video = document.querySelector("#player");
const select = document.querySelector("#audio-language");

const addOption = (track) => {
  const option = document.createElement("option");
  option.value = track.id;
  option.textContent = track.label || track.language || `Spur ${track.id}`;
  option.selected = track.enabled;
  select.append(option);
};

const tracks = video.audioTracks;
if (tracks) {
  // Bereits vorhandene Spuren übernehmen
  Array.from(tracks).forEach(addOption);
  // Später hinzukommende Spuren ergänzen
  tracks.addEventListener("addtrack", (e) => addOption(e.track));

  select.addEventListener("change", () => {
    for (const track of tracks) {
      track.enabled = track.id === select.value;
    }
  });
}

onaddtrack-Eigenschaft und Listener wieder entfernen

const audio = document.querySelector("audio");
const tracks = audio.audioTracks;

if (tracks) {
  // Variante 1: Handler-Eigenschaft (ersetzt einen vorher gesetzten Handler)
  tracks.onaddtrack = (event) => {
    console.log("onaddtrack:", event.track.language);
  };

  // Variante 2: benannter Listener, später entfernbar
  const onAdd = (event) => console.log("Listener:", event.track.id);
  tracks.addEventListener("addtrack", onAdd);

  // z. B. beim Zerstören der Player-Komponente
  const destroy = () => {
    tracks.removeEventListener("addtrack", onAdd);
    tracks.onaddtrack = null;
  };
  audio.addEventListener("emptied", destroy, { once: true });
}

onaddtrack: de Listener: 1

// Wichtig · Fallstricke

Eingeschränkte Browser-Unterstützung: HTMLMediaElement.audioTracks und damit AudioTrackList gibt es standardmäßig praktisch nur in Safari. In Chrome/Edge braucht es ein Experimentier-Flag, in Firefox die Einstellung media.track.enabled. Prüfen Sie deshalb immer, ob die Eigenschaft existiert (if (video.audioTracks)).
Zeitpunkt: Spuren aus der Datei werden oft schon beim Laden der Metadaten hinzugefügt. Ein Listener, den Sie erst danach registrieren, verpasst diese Ereignisse. Lesen Sie deshalb zusätzlich die schon vorhandenen Einträge der Liste aus.
Das Ereignis steigt nicht auf. Es kommt nur an der AudioTrackList selbst an, nicht am Medienelement.
Wenn Sie onaddtrack neu zuweisen, wird der vorherige Handler überschrieben. Für mehrere unabhängige Handler verwenden Sie addEventListener.
Streaming-Bibliotheken (hls.js, dash.js, Shaka) verwalten Audiospuren meist über eigene APIs und Ereignisse. Dort wird addtrack oft gar nicht ausgelöst.

Siehe auch

AudioTrackList AudioTrackList: removetrack AudioTrackList: change AudioTrack TrackEvent HTMLMediaElement.audioTracks VideoTrackList: addtrack TextTrackList: addtrack