SourceBuffer.audioTracks — Eigenschaft · JavaScript-Referenz

Signatur

SourceBuffer.audioTracks

Beschreibung

Die Eigenschaft audioTracks eines SourceBuffer gibt eine AudioTrackList zurück. Darin stehen alle Audiospuren, die aus den bisher angehängten Initialisierungssegmenten (z. B. fMP4- oder WebM-Header) dieses Puffers erkannt wurden. Jede Spur ist ein AudioTrack-Objekt mit Eigenschaften wie id, kind, label, language und enabled.

Gebraucht wird die Eigenschaft vor allem bei Media Source Extensions (MSE), etwa in eigenen Playern für adaptives Streaming (DASH/HLS). Sind in einem Stream mehrere Tonspuren enthalten, zum Beispiel verschiedene Sprachen oder eine Audiodeskription, kannst du sie hier nach Puffer getrennt auslesen und über AudioTrack.enabled ein- oder ausschalten.

Die Liste füllt sich erst, wenn ein Initialisierungssegment verarbeitet wurde. Direkt nach addSourceBuffer() ist sie leer. Lies sie deshalb erst im Ereignis updateend oder hör auf die Ereignisse addtrack/removetrack der Liste. Dieselben Spuren tauchen außerdem in HTMLMediaElement.audioTracks des zugehörigen <video>- bzw. <audio>-Elements auf.

Rückgabewert

Typ

AudioTrackList

Beschreibung

Eine live aktualisierte, schreibgeschützte Liste von AudioTrack-Objekten. Die Eigenschaft selbst kannst du nicht neu zuweisen. Einzelne Spuren lassen sich aber über enabled umschalten.

Beispiele

Audiospuren nach dem Initialisierungssegment auflisten

const video = document.querySelector('video');
const mediaSource = new MediaSource();
video.src = URL.createObjectURL(mediaSource);

mediaSource.addEventListener('sourceopen', async () => {
  const mime = 'video/mp4; codecs="avc1.64001f, mp4a.40.2"';
  const sourceBuffer = mediaSource.addSourceBuffer(mime);

  sourceBuffer.addEventListener('updateend', () => {
    if (!('audioTracks' in sourceBuffer)) {
      console.warn('SourceBuffer.audioTracks wird nicht unterstützt');
      return;
    }
    for (const track of sourceBuffer.audioTracks) {
      console.log(`${track.id}: ${track.label || '(ohne Name)'} [${track.language}] aktiv=${track.enabled}`);
    }
  }, { once: true });

  const init = await fetch('/media/init.mp4').then((r) => r.arrayBuffer());
  sourceBuffer.appendBuffer(init);
});

1: Deutsch [de] aktiv=true 2: English [en] aktiv=false

Tonspur nach Sprache wechseln

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

  let found = false;
  for (const track of tracks) {
    const match = track.language === lang && !found;
    track.enabled = match;
    if (match) found = true;
  }
  return found;
};

// z. B. nach Klick auf einen Sprachschalter
console.log(selectAudioLanguage(sourceBuffer, 'en'));

true

Auf neue Spuren reagieren (addtrack)

const watchAudioTracks = (sourceBuffer) => {
  const list = sourceBuffer.audioTracks;
  if (!list) return;

  list.addEventListener('addtrack', (event) => {
    const { track } = event;
    console.log(`Neue Audiospur: ${track.kind} / ${track.language}`);
  });
  list.onremovetrack = (event) => {
    console.log(`Spur entfernt: ${event.track.id}`);
  };
};

watchAudioTracks(sourceBuffer);

Neue Audiospur: main / de

// Wichtig · Fallstricke

Browserunterstützung: Die Eigenschaft ist nur in Safari standardmäßig verfügbar. In Chromium-Browsern ist sie hinter dem Flag „Experimental Web Platform features“ versteckt, in Firefox hinter media.track.enabled. Prüfe deshalb immer mit 'audioTracks' in sourceBuffer und sieh eine Ersatzlösung vor, etwa getrennte SourceBuffer pro Sprache.
Leere Liste: Vor dem ersten verarbeiteten Initialisierungssegment ist die Liste leer. Werte sie nicht synchron nach appendBuffer() aus, sondern erst im Ereignis updateend.
Wird der SourceBuffer mit MediaSource.removeSourceBuffer() entfernt, verschwinden seine Spuren aus der Liste und auch aus HTMLMediaElement.audioTracks.
In einem ManagedMediaSource- oder Worker-Kontext (MSE in Dedicated Workers) ist audioTracks je nach Browser nicht verfügbar.
Meist ist nur eine Audiospur gleichzeitig aktiv. Mehrere Spuren mit enabled = true werden je nach Implementierung gemischt oder ignoriert.

Siehe auch

SourceBuffer.videoTracks SourceBuffer.textTracks SourceBuffer.buffered SourceBuffer.updating SourceBuffer.mode