HTMLMediaElement: waiting — Ereignis · JavaScript-Referenz

Signatur

element.addEventListener("waiting", handler)

Beschreibung

Das waiting-Ereignis tritt auf, wenn ein HTMLMediaElement abspielen soll, aber die Wiedergabe stoppt, weil der nächste Frame noch nicht geladen ist. Das passiert typischerweise bei langsamer Netzwerkverbindung, direkt nach einem Sprung (seeking) oder am Ende des bereits gepufferten Bereichs. Das Element bleibt dabei im Zustand „spielt“ (paused ist false). Es wartet nur auf Daten.

Am häufigsten nutzt man das Ereignis, um einen Lade-Indikator (Spinner) anzuzeigen. Ausgeblendet wird er, sobald die Wiedergabe weiterläuft, also beim Ereignis playing oder nach Abschluss eines Sprungs beim Ereignis canplay. Außerdem eignet sich waiting für Analysen, zum Beispiel um zu zählen, wie oft und wie lange ein Stream hängt (Rebuffering).

Das Ereignis lässt sich über addEventListener("waiting", handler) oder die Eigenschaft onwaiting registrieren. Es steigt nicht im DOM auf (kein Bubbling) und kann nicht abgebrochen werden. Der Handler bekommt ein einfaches Event-Objekt.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"waiting"`.
$handler Pflicht	(event: Event) => void		Funktion, die beim Ereignis aufgerufen wird. Sie bekommt ein `Event`-Objekt, dessen `target` das Medienelement ist.
$options	boolean \| AddEventListenerOptions	false	Optionen wie `once`, `passive`, `signal` oder `capture`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler bekommt ein Event-Objekt.

Beispiele

Lade-Spinner beim Puffern anzeigen

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

video.addEventListener('waiting', () => {
  spinner.hidden = false;
  console.log('Puffern … warte auf Daten');
});

video.addEventListener('playing', () => {
  spinner.hidden = true;
  console.log('Wiedergabe läuft weiter');
});

Puffern … warte auf Daten Wiedergabe läuft weiter

Rebuffering-Dauer für Analysen messen

const video = document.querySelector('video');
let waitStart = null;
let stalls = 0;

video.addEventListener('waiting', () => {
  waitStart = performance.now();
  stalls++;
});

video.addEventListener('playing', () => {
  if (waitStart !== null) {
    const ms = Math.round(performance.now() - waitStart);
    console.log(`Hänger #${stalls}: ${ms} ms bei ${video.currentTime.toFixed(1)} s`);
    waitStart = null;
  }
});

Hänger #1: 842 ms bei 12.3 s

onwaiting-Eigenschaft und Listener wieder entfernen

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

// Variante 1: on-Eigenschaft (nur ein Handler möglich)
audio.onwaiting = () => console.log('Audio wartet auf Daten');

// Variante 2: benannter Listener, der sich entfernen lässt
const onWaiting = (event) => {
  console.log('waiting auf', event.target.currentSrc);
};
audio.addEventListener('waiting', onWaiting);

// Später, z. B. beim Abbau der Komponente:
audio.removeEventListener('waiting', onWaiting);
audio.onwaiting = null;

// Wichtig · Fallstricke

Kein Pausieren: Bei waiting bleibt paused auf false. Ein Pausieren durch den Nutzer löst stattdessen pause aus. Beide Fälle sollten im UI getrennt behandelt werden.
Gegenstück wählen: Blende den Spinner beim Ereignis playing aus, nicht bei play. play feuert schon, bevor Daten da sind. Wenn das Video pausiert ist und nach einem Sprung nicht weiterläuft, kommt kein playing. Dann zusätzlich canplay oder seeked beachten.
Abgrenzung zu stalled: stalled bedeutet, dass der Browser Daten abrufen will, aber keine ankommen. waiting betrifft die Wiedergabe selbst. Die beiden Ereignisse treten unabhängig voneinander auf.
Häufigkeit: Bei schlechten Verbindungen kann waiting oft hintereinander auslösen. Sehr kurze Hänger lassen sich überbrücken, indem man den Spinner erst nach einer kleinen Verzögerung (etwa 200 ms per setTimeout) einblendet. So flackert er nicht.
Browser-Unterstützung: Das Ereignis wird von allen modernen Browsern unterstützt. Wann genau es feuert, kann sich je nach Browser und Streaming-Technik (MSE, HLS, DASH) leicht unterscheiden.

Siehe auch

HTMLMediaElement: playing HTMLMediaElement: stalled HTMLMediaElement: canplay HTMLMediaElement: seeking HTMLMediaElement.readyState HTMLMediaElement FontFaceSet: loading