HTMLMediaElement: emptied — Ereignis · JavaScript-Referenz

Signatur

element.addEventListener("emptied", handler)

Beschreibung

Das Ereignis emptied wird an einem <audio>- oder <video>-Element ausgelöst, wenn das Element auf seinen Ausgangszustand zurückgesetzt wird. Dabei springt networkState auf NETWORK_EMPTY (0) und readyState auf HAVE_NOTHING (0). Das passiert zum Beispiel, wenn ein bereits (teilweise) geladenes Medium durch einen Aufruf von load() neu geladen wird oder wenn die Quelle über src bzw. srcObject ausgetauscht wird.

Das Ereignis eignet sich gut, um anwendungsseitige Zustände zurückzusetzen: Fortschrittsbalken, Zeitanzeigen, Untertitel-Caches, Analyse-Zähler oder Puffer-Visualisierungen. Da nach emptied typischerweise ein neuer Ladevorgang mit loadstart, loadedmetadata usw. beginnt, markiert es zuverlässig das Ende des „alten“ Mediums.

Registrieren lässt sich der Handler über addEventListener("emptied", handler) oder über die Eigenschaft onemptied. Das Ereignis blubbert nicht (bubbles: false) und ist nicht abbrechbar; der Handler erhält ein einfaches Event-Objekt.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"emptied"`.
$handler Pflicht	(event: Event) => void		Callback, der beim Leeren des Mediums aufgerufen wird. Erhält ein generisches `Event`; `event.target` ist das Medienelement.
$options	boolean \| AddEventListenerOptions	false	Optionen wie `once`, `capture`, `passive` oder `signal` zum späteren Entfernen per `AbortController`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler erhält ein Event-Objekt (nicht abbrechbar, blubbert nicht).

Beispiele

emptied per addEventListener beobachten

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

video.addEventListener('emptied', (event) => {
  console.log('Medium geleert');
  console.log('networkState:', event.target.networkState);
  console.log('readyState:', event.target.readyState);
});

// Nach einiger Zeit das Video neu laden – löst emptied aus,
// sofern bereits Daten geladen waren
setTimeout(() => video.load(), 3000);

Medium geleert networkState: 0 readyState: 0

Player-UI beim Quellwechsel zurücksetzen

const player = document.querySelector('#player');
const progress = document.querySelector('#progress');
const timeLabel = document.querySelector('#time');

const resetUi = () => {
  progress.value = 0;
  timeLabel.textContent = '0:00 / --:--';
  console.log('UI zurückgesetzt');
};

player.addEventListener('emptied', resetUi);

// Playlist: nächsten Titel laden
const playNext = async (url) => {
  player.src = url; // Quellwechsel -> emptied (falls vorher geladen)
  try {
    await player.play();
  } catch (err) {
    console.warn('Autoplay blockiert:', err.name);
  }
};

document.querySelector('#next').addEventListener('click', () => playNext('/media/track2.mp3'));

UI zurückgesetzt

on-Property und Entfernen des Listeners

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

// Variante 1: on-Property (überschreibt vorherige Zuweisung)
audio.onemptied = () => console.log('onemptied: Medium leer');

// Variante 2: addEventListener mit AbortController wieder entfernen
const controller = new AbortController();
audio.addEventListener('emptied', () => console.log('Listener aktiv'), {
  signal: controller.signal
});

audio.load();

// Später: beide Handler entfernen
controller.abort();
audio.onemptied = null;

onemptied: Medium leer Listener aktiv

// Wichtig · Fallstricke

Nicht beim ersten Laden: emptied feuert nur, wenn das Element nicht bereits im Zustand NETWORK_EMPTY war. Ein erstes load() an einem frischen Element löst es in der Regel nicht aus.
Kein Bubbling: Das Ereignis blubbert nicht. Für Ereignisdelegation an einem Elternelement muss capture: true gesetzt werden.
Reihenfolge: Bei einem Quellwechsel folgt auf emptied üblicherweise loadstart. Ein zuvor laufendes Abspielen wird abgebrochen; offene play()-Promises werden mit AbortError abgelehnt – diese abfangen.
Nicht verwechseln mit abort (Laden abgebrochen, ohne Fehler), ended (Wiedergabe am Ende) oder stalled (Daten bleiben aus).
Kompatibilität: Von allen modernen Browsern unterstützt; kleinere Unterschiede gibt es beim genauen Zeitpunkt, z. B. beim Setzen von srcObject für MediaStreams.

Siehe auch

HTMLMediaElement.load() HTMLMediaElement: loadstart HTMLMediaElement: abort HTMLMediaElement.networkState HTMLMediaElement.readyState HTMLMediaElement HTMLElement: command