MediaSource.sourceBuffers — Eigenschaft · JavaScript-Referenz

Signatur

MediaSource.sourceBuffers

Beschreibung

Die schreibgeschützte Eigenschaft sourceBuffers einer MediaSource gibt eine SourceBufferList zurück. Darin stehen alle SourceBuffer-Objekte, die mit MediaSource.addSourceBuffer() angelegt und noch nicht mit removeSourceBuffer() entfernt wurden. Typisch ist ein Puffer für Video und ein zweiter für Audio, etwa bei getrennten DASH- oder HLS-Spuren.

Die Liste ist live: Sie ändert sich automatisch, wenn Puffer hinzukommen oder wegfallen. Jede Änderung löst auf der Liste ein Ereignis aus, entweder addsourcebuffer oder removesourcebuffer. Auf die einzelnen Einträge greifen Sie über den Index zu (sourceBuffers[0]) oder über length. Die Liste lässt sich auch mit for...of bzw. Array.from() durchlaufen.

In der Praxis brauchen Sie sourceBuffers vor allem für Verwaltungsaufgaben, zum Beispiel:

prüfen, ob gerade ein Puffer aktualisiert wird (updating), bevor Sie endOfStream() aufrufen oder die Dauer ändern,
gepufferte Zeitbereiche (buffered) auswerten,
beim Aufräumen alle Puffer entfernen.

Im Unterschied dazu enthält activeSourceBuffers nur die Puffer, die gerade eine ausgewählte Video- oder aktivierte Audio- bzw. Textspur liefern.

Rückgabewert

Typ

SourceBufferList

Beschreibung

Eine live aktualisierte, schreibgeschützte Liste der SourceBuffer-Objekte dieser MediaSource. Sie ist leer, solange noch kein Puffer angelegt wurde.

Beispiele

Puffer anlegen und die Liste auslesen

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

mediaSource.addEventListener('sourceopen', () => {
  console.log(mediaSource.sourceBuffers.length); // noch leer

  mediaSource.addSourceBuffer('video/mp4; codecs="avc1.42E01E"');
  mediaSource.addSourceBuffer('audio/mp4; codecs="mp4a.40.2"');

  console.log(mediaSource.sourceBuffers.length);
  console.log(mediaSource.sourceBuffers[0] instanceof SourceBuffer);
});

0 2 true

endOfStream() erst aufrufen, wenn kein Puffer mehr aktualisiert wird

const waitForIdle = (mediaSource) => {
  const busy = Array.from(mediaSource.sourceBuffers).filter((sb) => sb.updating);
  return Promise.all(
    busy.map((sb) => new Promise((resolve) =>
      sb.addEventListener('updateend', resolve, { once: true })
    ))
  );
};

const finishStream = async (mediaSource) => {
  await waitForIdle(mediaSource);
  if (mediaSource.readyState === 'open') {
    mediaSource.endOfStream();
    console.log('Stream beendet:', mediaSource.readyState);
  }
};

Stream beendet: ended

Auf Änderungen der Liste reagieren und aufräumen

const mediaSource = new MediaSource();
const list = mediaSource.sourceBuffers;

list.addEventListener('addsourcebuffer', () => {
  console.log('Puffer hinzugefügt, jetzt:', list.length);
});
list.onremovesourcebuffer = () => {
  console.log('Puffer entfernt, jetzt:', list.length);
};

const cleanup = () => {
  // Kopie anlegen, weil sich die Live-Liste beim Entfernen verkleinert
  for (const sb of Array.from(mediaSource.sourceBuffers)) {
    if (sb.updating) sb.abort();
    mediaSource.removeSourceBuffer(sb);
  }
};

Puffer hinzugefügt, jetzt: 1 Puffer entfernt, jetzt: 0

// Wichtig · Fallstricke

Live-Liste: Wenn Sie in einer Index-Schleife Puffer entfernen, verschieben sich die Indizes. Kopieren Sie die Liste deshalb vorher mit Array.from().
Kein Array: SourceBufferList hat weder map noch filter. Für diese Methoden müssen Sie die Liste zuerst umwandeln.
Schreibgeschützt: Eine Zuweisung an sourceBuffers wird ignoriert, im Strict Mode löst sie einen TypeError aus. Puffer ändern Sie nur über addSourceBuffer() und removeSourceBuffer().
Zeitpunkt: addSourceBuffer() funktioniert nur, wenn readyState den Wert 'open' hat. Warten Sie daher auf das Ereignis sourceopen.
Kompatibilität: Die Eigenschaft wird von Chrome, Edge, Firefox und Safari auf dem Desktop unterstützt. Auf dem iPhone steht sie erst ab iOS 17.1 zur Verfügung, und zwar über ManagedMediaSource. In Dedicated Workers gibt es sie nur in neueren Chromium-Versionen. Prüfen Sie die Unterstützung mit 'MediaSource' in window.

Siehe auch

MediaSource.canConstructInDedicatedWorker MediaSource.activeSourceBuffers MediaSource.duration MediaSource.handle MediaSource.readyState