SourceBufferList — Schnittstelle · JavaScript-Referenz

Signatur

interface SourceBufferList extends EventTarget

Beschreibung

SourceBufferList ist eine Liste, die man nur lesen kann. Sie enthält SourceBuffer-Objekte aus der Media-Source-Extensions-API (MSE). Eigene Instanzen legt man nicht an. Man bekommt die Liste immer von einer MediaSource: mediaSource.sourceBuffers enthält alle Puffer, die mit addSourceBuffer() angelegt wurden. mediaSource.activeSourceBuffers enthält nur die Puffer, deren Spuren gerade ausgewählt bzw. aktiv sind.

Die Schnittstelle hat die Eigenschaft length. Einzelne Einträge liest man per Index-Zugriff (list[0]). Eine Methode item() gibt es nicht. Außerdem ist die Liste iterierbar, man kann sie also mit for...of durchlaufen. Da SourceBufferList von EventTarget erbt, meldet sie Änderungen über zwei Ereignisse: addsourcebuffer und removesourcebuffer. Man kann sie mit addEventListener() abonnieren oder die Eigenschaften onaddsourcebuffer bzw. onremovesourcebuffer setzen.

Typische Einsätze: Adaptives Streaming (DASH, HLS über MSE) mit getrennten Puffern für Audio und Video. Außerdem das Aufräumen oder Prüfen des Puffer-Zustands, bevor man endOfStream() aufruft. Dabei stellt man sicher, dass kein Puffer mehr updating ist.

Parameter

Name	Typ	Default	Beschreibung
$length	number		Nur lesbar. Gibt an, wie viele `SourceBuffer` die Liste enthält.
$[index]	number		Index-Zugriff auf einen `SourceBuffer`. Liegt der Index außerhalb der Liste, ist das Ergebnis `undefined`.
$onaddsourcebuffer	function\|null	null	Handler, der aufgerufen wird, wenn ein `SourceBuffer` zur Liste hinzukommt.
$onremovesourcebuffer	function\|null	null	Handler, der aufgerufen wird, wenn ein `SourceBuffer` aus der Liste entfernt wird.

Rückgabewert

Typ

SourceBufferList

Beschreibung

Man bekommt die Liste über MediaSource.sourceBuffers oder MediaSource.activeSourceBuffers. Sie ist „live“, gibt also Änderungen an der MediaSource sofort wieder.

Beispiele

Zugriff auf die Liste und Iteration

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

mediaSource.addEventListener('sourceopen', () => {
  mediaSource.addSourceBuffer('video/mp4; codecs="avc1.42E01E"');
  mediaSource.addSourceBuffer('audio/mp4; codecs="mp4a.40.2"');

  const list = mediaSource.sourceBuffers;
  console.log('Anzahl Puffer:', list.length);
  for (const sb of list) {
    console.log('mode:', sb.mode, 'updating:', sb.updating);
  }
});

Anzahl Puffer: 2 mode: segments updating: false mode: segments updating: false

Ereignisse addsourcebuffer / removesourcebuffer

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

const onAdd = () => console.log('Puffer hinzugefügt, jetzt:', mediaSource.sourceBuffers.length);
mediaSource.sourceBuffers.addEventListener('addsourcebuffer', onAdd);

// Alternative über die on-Property
mediaSource.sourceBuffers.onremovesourcebuffer = () => {
  console.log('Puffer entfernt, jetzt:', mediaSource.sourceBuffers.length);
};

mediaSource.addEventListener('sourceopen', () => {
  const sb = mediaSource.addSourceBuffer('video/webm; codecs="vp9"');
  mediaSource.removeSourceBuffer(sb);
  mediaSource.sourceBuffers.removeEventListener('addsourcebuffer', onAdd);
});

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

Warten, bis alle Puffer fertig sind, dann endOfStream()

const waitForIdle = (sb) =>
  sb.updating
    ? new Promise((resolve) => sb.addEventListener('updateend', resolve, { once: true }))
    : Promise.resolve();

const finishStream = async (mediaSource) => {
  // Array.from, weil die Liste live ist
  const buffers = Array.from(mediaSource.sourceBuffers);
  await Promise.all(buffers.map(waitForIdle));
  if (mediaSource.readyState === 'open') {
    mediaSource.endOfStream();
    console.log('Stream beendet mit', buffers.length, 'Puffern');
  }
};

Stream beendet mit 2 Puffern

// Wichtig · Fallstricke

Kein Konstruktor: new SourceBufferList() wirft einen TypeError.
Live-Liste: Wer während einer Schleife removeSourceBuffer() aufruft, verschiebt dabei die Indizes. Deshalb die Liste vorher mit Array.from() kopieren.
Auf der Liste gibt es keine Array-Methoden wie map oder forEach. Man muss sie zuerst umwandeln, z. B. mit [...list].
activeSourceBuffers kann weniger Einträge haben als sourceBuffers. Das hängt davon ab, welche Spuren gerade ausgewählt sind.
Kompatibilität: MSE wird von allen modernen Desktop-Browsern unterstützt. Auf dem iPhone steht MSE erst ab iOS 17.1 zur Verfügung, und zwar als ManagedMediaSource. Vorher sollte man die Unterstützung prüfen: 'MediaSource' in window || 'ManagedMediaSource' in window. MSE ist auch in dedizierten Workern verfügbar (Chrome 108+), nicht aber in allen Browsern.

Siehe auch

SourceBuffer SVGNumberList AudioBuffer CSSRuleList DOMRectList