AudioTrack — Schnittstelle · JavaScript-Referenz

Signatur

interface AudioTrack

Beschreibung

Das Interface AudioTrack beschreibt eine einzelne Tonspur innerhalb einer Mediendatei. Einen Konstruktor gibt es nicht. Der Browser legt die Objekte selbst an, sobald er die Metadaten der Mediendatei gelesen hat. Du erreichst sie über die Eigenschaft HTMLMediaElement.audioTracks. Sie liefert eine AudioTrackList, die du wie ein Array per Index durchgehen oder mit getTrackById() abfragen kannst.

Gebraucht wird AudioTrack vor allem bei Medien mit mehreren Tonspuren. Typische Fälle sind Filme mit mehreren Sprachfassungen, Audiodeskription für sehbehinderte Menschen oder Regiekommentare. Mit den Eigenschaften kind, label und language baust du eine Auswahl für die Nutzer. Über enabled schaltest du Tonspuren ein oder aus.

Anders als bei VideoTrack (dort gilt selected, und es ist immer nur eine Spur aktiv) können mehrere Audiotracks gleichzeitig aktiv sein. Der Browser mischt sie dann zusammen. Wenn du die Sprache wechseln willst, musst du deshalb die bisher aktive Spur selbst ausschalten. Jede Änderung von enabled löst auf der zugehörigen AudioTrackList das Ereignis change aus.

Wichtig: Die API wird bisher kaum unterstützt. Nur Safari bietet sie standardmäßig an. Prüfe daher vorher, ob sie vorhanden ist, und biete für andere Browser eine Ausweichlösung an, zum Beispiel getrennte Mediendateien pro Sprache oder Media Source Extensions.

Parameter

Name	Typ	Default	Beschreibung
$enabled	boolean	abhängig von der Mediendatei	Les- und schreibbar. Gibt an, ob die Tonspur gerade abgespielt wird. Wenn du den Wert auf `true` oder `false` setzt, wird die Spur ein- oder ausgeschaltet.
$id	string		Nur lesbar. Eindeutige Kennung der Spur innerhalb des Mediums. Passt zum Argument von `AudioTrackList.getTrackById()` und kann als Media-Fragment genutzt werden (`#track=…`).
$kind	"alternative" \| "description" \| "main" \| "main-desc" \| "translation" \| "commentary" \| ""	""	Nur lesbar. Die Art der Spur: `main` ist die Haupttonspur, `translation` eine Synchronfassung, `description` eine Audiodeskription, `commentary` ein Kommentar und so weiter.
$label	string		Nur lesbar. Lesbarer Name der Spur, z. B. `"Deutsch (Dolby 5.1)"`. Ist leer, wenn die Mediendatei keinen Namen mitliefert.
$language	string		Nur lesbar. Sprachkennung nach BCP 47, z. B. `"de"` oder `"en-US"`. Ist leer, wenn keine Sprache bekannt ist.
$sourceBuffer	SourceBuffer \| null	null	Nur lesbar. Der `SourceBuffer` der Media Source Extensions, aus dem die Spur stammt. Ist `null`, wenn die Spur nicht über MSE erzeugt wurde.

Rückgabewert

Typ

AudioTrack

Beschreibung

Eigenständige Objekte bekommst du nicht direkt. Du erhältst sie als Einträge einer AudioTrackList aus media.audioTracks, über audioTracks[i] oder audioTracks.getTrackById(id).

Beispiele

Vorhandene Tonspuren auflisten (mit Unterstützungsprüfung)

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

video.addEventListener('loadedmetadata', () => {
  if (!('audioTracks' in video)) {
    console.warn('AudioTrack-API wird von diesem Browser nicht unterstützt.');
    return;
  }

  for (const track of Array.from(video.audioTracks)) {
    console.log(`${track.id}: ${track.label || '(ohne Name)'} [${track.language}] kind=${track.kind} aktiv=${track.enabled}`);
  }
});

1: Deutsch [de] kind=main aktiv=true 2: English [en] kind=translation aktiv=false 3: Regiekommentar [de] kind=commentary aktiv=false

Sprachwechsel: nur eine Tonspur aktiv halten

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

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

  let found = false;
  for (let i = 0; i < tracks.length; i++) {
    // Mehrere Spuren können parallel aktiv sein, darum alle anderen ausschalten
    const match = !found && tracks[i].language.startsWith(lang);
    tracks[i].enabled = match;
    if (match) found = true;
  }
  return found;
};

console.log(setAudioLanguage('en'));

true

Auswahlmenü erzeugen und auf Änderungen reagieren

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

video.addEventListener('loadedmetadata', () => {
  const tracks = video.audioTracks;
  if (!tracks || tracks.length < 2) {
    select.hidden = true;
    return;
  }

  for (const track of Array.from(tracks)) {
    const option = new Option(track.label || track.language || track.id, track.id);
    option.selected = track.enabled;
    select.append(option);
  }

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

  // Das Ereignis wird bei jeder Änderung von enabled ausgelöst
  tracks.addEventListener('change', () => {
    const active = Array.from(tracks).find((t) => t.enabled);
    console.log('Aktive Tonspur:', active?.label);
  });
});

Aktive Tonspur: English

// Wichtig · Fallstricke

Browser-Unterstützung: Standardmäßig ist die API nur in Safari (macOS und iOS) verfügbar. In Chrome und Edge brauchst du das Flag „Experimental Web Platform features“, in Firefox die Einstellung media.track.enabled. Prüfe daher immer mit 'audioTracks' in HTMLMediaElement.prototype, ob sie vorhanden ist.
Zeitpunkt: Die Liste der Tonspuren ist erst nach loadedmetadata befüllt. Wenn du vorher zugreifst, ist sie meist leer.
Mehrere aktive Spuren: Setzt du enabled = true, werden andere Spuren nicht automatisch ausgeschaltet. Ohne eigenes Ausschalten hörst du zwei Sprachen gleichzeitig.
Nur lesbare Metadaten: id, kind, label und language kommen aus der Mediendatei (z. B. MP4, HLS) und lassen sich nicht ändern. Viele Dateien liefern hier leere Zeichenketten. Plane deshalb einen Ersatznamen für die Anzeige ein.
Kein Konstruktor: new AudioTrack() wirft einen TypeError.
Bei HLS-Streams in Safari hängt es vom Manifest ab (EXT-X-MEDIA), welche Tonspuren angeboten werden.

Siehe auch

VideoTrack AudioData AudioParam AudioTrackList AudioNode