SourceBuffer: abort — Ereignis · JavaScript-Referenz

Signatur

sourceBuffer.addEventListener("abort", handler)

Beschreibung

Das Ereignis abort gehört zur Schnittstelle SourceBuffer der Media Source Extensions (MSE). Es wird ausgelöst, wenn ein Anfügevorgang abgebrochen wird, solange SourceBuffer.updating noch true ist. Das passiert in zwei Fällen:

Du rufst SourceBuffer.abort() auf, während appendBuffer() noch läuft.
Du entfernst den Puffer mit MediaSource.removeSourceBuffer(), während er noch aktualisiert wird.

Die Reihenfolge ist dabei immer gleich: Zuerst wird updating auf false gesetzt, dann folgt abort und direkt danach updateend. Ein update-Ereignis gibt es in diesem Fall nicht. Die Daten aus dem abgebrochenen Aufruf sind also womöglich nur teilweise oder gar nicht im Puffer gelandet.

Den Handler registrierst du entweder mit addEventListener("abort", handler) oder über die Eigenschaft sourceBuffer.onabort. Übergeben wird ein einfaches Event. Es steigt nicht auf (bubbles: false) und lässt sich nicht abbrechen (cancelable: false). Praktisch nutzt du es, um bei Qualitätswechseln (adaptives Streaming), beim Springen im Video (Seeking) oder beim Abbruch eines Downloads deine Anfüge-Warteschlange sauber zurückzusetzen.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, hier immer `"abort"`.
$handler Pflicht	(event: Event) => void		Callback, der ein einfaches `Event` erhält. `event.target` ist der betroffene `SourceBuffer`.
$options	boolean \| AddEventListenerOptions	false	Übliche Optionen von `addEventListener`, z. B. `{ once: true }` oder `{ signal }`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Die Eigenschaft onabort enthält den zugewiesenen Handler oder null.

Beispiele

abort-Ereignis mit addEventListener abfangen

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

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

  sb.addEventListener('abort', (e) => {
    console.log('Anfügen abgebrochen, updating =', e.target.updating);
  });
  sb.addEventListener('updateend', () => console.log('updateend'));

  const res = await fetch('/media/segment-1.m4s');
  sb.appendBuffer(await res.arrayBuffer());

  // Sofort abbrechen, solange noch angefügt wird
  if (sb.updating) sb.abort();
});

Anfügen abgebrochen, updating = false updateend

Anfüge-Warteschlange beim Seeking zurücksetzen (onabort)

const queue = [];
let sb; // SourceBuffer, im sourceopen-Handler erzeugt

const appendNext = () => {
  if (!sb.updating && queue.length) sb.appendBuffer(queue.shift());
};

const setupBuffer = (mediaSource, mime) => {
  sb = mediaSource.addSourceBuffer(mime);
  sb.onabort = () => {
    console.warn('Append abgebrochen – Warteschlange wird geleert');
    queue.length = 0;
  };
  sb.addEventListener('updateend', appendNext);
};

document.querySelector('video').addEventListener('seeking', () => {
  if (sb?.updating) sb.abort(); // löst abort + updateend aus
});

Append abgebrochen – Warteschlange wird geleert

Einmaligen Listener per Promise und removeEventListener

const waitForAbortOrEnd = (sb) => new Promise((resolve) => {
  const onAbort = () => { cleanup(); resolve('abgebrochen'); };
  const onUpdate = () => { cleanup(); resolve('fertig'); };
  const cleanup = () => {
    sb.removeEventListener('abort', onAbort);
    sb.removeEventListener('update', onUpdate);
  };
  sb.addEventListener('abort', onAbort);
  sb.addEventListener('update', onUpdate);
});

// Verwendung:
// sb.appendBuffer(data);
// const status = await waitForAbortOrEnd(sb);
// console.log(status);

abgebrochen // oder: fertig

// Wichtig · Fallstricke

Nicht mit error verwechseln: abort bedeutet einen bewussten Abbruch. Fehlerhafte Mediendaten lösen dagegen error aus (gefolgt von updateend).
updateend kommt trotzdem: Wer nur auf updateend hört, um das nächste Segment anzufügen, sollte bei einem Abbruch die Warteschlange prüfen. Sonst werden womöglich veraltete Segmente weiter angefügt.
remove() löst kein abort aus: Wenn du SourceBuffer.remove() aufrufst, während updating === true ist, wirft das einen InvalidStateError. Ein Abbruch passiert dabei nicht.
abort() ohne laufendes Anfügen löst kein Ereignis aus. Die Methode setzt dann nur den Parser zurück, z. B. timestampOffset-bezogene Zustände und das Anfügefenster. Hat die MediaSource nicht den Zustand readyState === \"open\", wirft abort() einen InvalidStateError.
Kompatibilität: Wird in Chrome, Edge, Firefox und Safari auf dem Desktop unterstützt. Auf dem iPhone steht MSE erst ab iOS 17.1 über ManagedMediaSource zur Verfügung, dessen SourceBuffer dasselbe Ereignis kennt. In Chromium-Browsern ist MSE auch in Dedicated Workers nutzbar. Vorher mit 'MediaSource' in window prüfen, ob die API vorhanden ist.

Siehe auch

SourceBuffer: error SourceBuffer: update SourceBuffer: updateend SourceBuffer: updatestart FileReader: abort