AudioTrackList — Schnittstelle · JavaScript-Referenz

Signatur

interface AudioTrackList extends EventTarget

Beschreibung

AudioTrackList ist eine listenartige Sammlung von AudioTrack-Objekten. Du erhältst sie nicht über einen Konstruktor, sondern über die Eigenschaft HTMLMediaElement.audioTracks eines <video>- oder <audio>-Elements. Die einzelnen Spuren liest du per Index (tracks[0]) aus. Wie viele Spuren es gibt, steht in length. Mit getTrackById(id) suchst du gezielt eine Spur anhand ihrer ID.

Praktisch ist die Schnittstelle vor allem bei Medien mit mehreren Tonspuren, etwa verschiedenen Sprachfassungen, einem Regiekommentar oder einer Audiodeskription für blinde und sehbehinderte Menschen. Mit der Eigenschaft enabled eines AudioTrack schaltest du Spuren ein oder aus. Anders als bei Videospuren dürfen auch mehrere Audiospuren gleichzeitig aktiv sein; der Browser mischt sie dann zusammen.

Da AudioTrackList von EventTarget erbt, kann sie drei Events auslösen:

addtrack: Eine Spur wurde hinzugefügt (auch als onaddtrack verfügbar).
removetrack: Eine Spur wurde entfernt (onremovetrack).
change: Eine Spur wurde ein- oder ausgeschaltet (onchange).

Die Liste ist live: Sie ändert sich automatisch, sobald der Browser Metadaten lädt oder sich die Quelle ändert. Deshalb liest du sie am besten erst nach dem Event loadedmetadata aus.

Parameter

Name	Typ	Default	Beschreibung
$length	number		Nur lesbar. Anzahl der `AudioTrack`-Objekte in der Liste.
$[index]	AudioTrack		Zugriff per Index von `0` bis `length - 1`. Ein ungültiger Index ergibt `undefined`.
$getTrackById(id)	(id: string) => AudioTrack \| null		Gibt die Spur mit der passenden `id` zurück, sonst `null`.
$onaddtrack / onremovetrack / onchange	Function \| null	null	Event-Handler-Eigenschaften für die Events `addtrack`, `removetrack` und `change`.

Rückgabewert

Typ

AudioTrackList

Beschreibung

Wird von HTMLMediaElement.audioTracks zurückgegeben. Wo die API nicht unterstützt wird, ist die Eigenschaft undefined.

Beispiele

Alle Audiospuren eines Videos auflisten

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

video.addEventListener('loadedmetadata', () => {
  const tracks = video.audioTracks;
  if (!tracks) {
    console.warn('AudioTrackList wird in diesem Browser nicht unterstützt.');
    return;
  }
  // Die Liste ist kein Array, lässt sich aber mit Array.from umwandeln
  for (const track of Array.from(tracks)) {
    console.log(`${track.id}: ${track.label} (${track.language}) – aktiv: ${track.enabled}`);
  }
});

1: Deutsch (de) – aktiv: true 2: English (en) – aktiv: false 3: Audiodeskription (de) – aktiv: false

Tonspur nach Sprache umschalten

const selectAudioLanguage = (video, lang) => {
  const tracks = video.audioTracks;
  if (!tracks) return false;

  let found = false;
  for (let i = 0; i < tracks.length; i++) {
    const isMatch = tracks[i].language === lang && !found;
    tracks[i].enabled = isMatch; // nur eine Sprachspur aktiv lassen
    if (isMatch) found = true;
  }
  return found;
};

const video = document.querySelector('video');
console.log(selectAudioLanguage(video, 'en'));

true

Auswahlmenü aktuell halten mit addtrack, removetrack und change

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

const render = () => {
  select.replaceChildren(
    ...Array.from(tracks, (t) => new Option(t.label || t.language || t.id, t.id, false, t.enabled))
  );
};

if (tracks) {
  tracks.addEventListener('addtrack', render);
  tracks.addEventListener('removetrack', render);
  tracks.onchange = () => console.log('Aktive Tonspur geändert');

  select.addEventListener('change', () => {
    for (const t of Array.from(tracks)) t.enabled = false;
    const chosen = tracks.getTrackById(select.value);
    if (chosen) chosen.enabled = true;
  });

  // Aufräumen, z. B. wenn der Player entfernt wird
  const destroy = () => {
    tracks.removeEventListener('addtrack', render);
    tracks.removeEventListener('removetrack', render);
    tracks.onchange = null;
  };
}

Aktive Tonspur geändert

// Wichtig · Fallstricke

Eingeschränkte Browser-Unterstützung: Nur Safari (macOS und iOS) unterstützt die API standardmäßig. In Chrome und Edge musst du das Flag „Experimental Web Platform features“ aktivieren, in Firefox die Einstellung media.track.enabled. Prüfe deshalb immer, ob video.audioTracks existiert, bevor du es nutzt.
Die Liste ist kein Array. Methoden wie map oder filter fehlen. Wandle sie zuerst mit Array.from() um. Iterierbar ist sie nicht in allen Implementierungen garantiert.
Vor loadedmetadata ist die Liste oft leer. Bei MSE- oder HLS-Streams können Spuren auch später dazukommen. Höre deshalb auf addtrack.
Mehrere Audiospuren können gleichzeitig aktiv sein und werden dann gemischt. Wenn du die Sprache wechselst, schalte die anderen Spuren ausdrücklich ab.
Bibliotheken wie hls.js oder dash.js verwalten ihre Tonspuren oft über eigene APIs. audioTracks kann dort leer bleiben.

Siehe auch

ImageTrackList VideoTrackList AudioTrack TextTrackList AudioWorklet