HTMLMediaElement: seeking — Ereignis · JavaScript-Referenz

Signatur

element.addEventListener("seeking", handler)

Beschreibung

Das Ereignis seeking wird an einem <audio>- oder <video>-Element ausgelöst, sobald eine Suchoperation startet – etwa weil der Nutzer den Fortschrittsbalken verschiebt oder weil per Skript currentTime bzw. fastSeek() gesetzt wurde. Zu diesem Zeitpunkt ist die Eigenschaft HTMLMediaElement.seeking bereits true, und currentTime enthält schon die Zielposition.

Typische Einsatzzwecke: einen Lade-Spinner anzeigen, solange die neue Position noch nicht verfügbar ist, Analyse-Ereignisse („Nutzer springt von X nach Y“) protokollieren oder Untertitel und synchronisierte Inhalte (z. B. Kapitelmarken, Transkripte) vorübergehend aussetzen. Das Gegenstück ist das Ereignis seeked, das feuert, wenn die Suche abgeschlossen ist und seeking wieder false ist.

Das Ereignis ist nicht abbrechbar und steigt nicht auf (bubbles: false). Registriert wird es entweder mit addEventListener("seeking", handler) oder über die Eigenschaft onseeking. Der Handler erhält ein generisches Event-Objekt.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"seeking"`.
$handler Pflicht	(event: Event) => void		Callback, der beim Start der Suche aufgerufen wird. `event.target` ist das Medienelement.
$options	boolean \| AddEventListenerOptions	false	Optionen wie `once`, `signal` oder `capture`. Da das Ereignis nicht aufsteigt, braucht man für Delegation `capture: true`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler erhält ein Event (nicht abbrechbar, steigt nicht auf).

Beispiele

Lade-Spinner während der Suche anzeigen

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

video.addEventListener('seeking', () => {
  spinner.hidden = false;
  console.log(`Suche nach ${video.currentTime.toFixed(1)} s …`);
});

video.addEventListener('seeked', () => {
  spinner.hidden = true;
  console.log('Suche abgeschlossen');
});

Suche nach 42.0 s … Suche abgeschlossen

Sprünge für Statistik protokollieren (Start- und Zielposition)

const video = document.querySelector('video');
let lastTime = 0;

video.addEventListener('timeupdate', () => {
  if (!video.seeking) lastTime = video.currentTime;
});

video.addEventListener('seeking', () => {
  const from = lastTime.toFixed(1);
  const to = video.currentTime.toFixed(1);
  console.log(`Sprung von ${from} s nach ${to} s`);
});

// Suche per Skript auslösen
video.currentTime = 90;

Sprung von 12.3 s nach 90.0 s

on-Property und Entfernen des Listeners per AbortController

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

// Variante 1: on-Property (überschreibt vorherige Zuweisung)
audio.onseeking = (event) => {
  console.log('seeking via onseeking:', event.target.seeking);
};

// Variante 2: addEventListener mit Abbruch-Signal
const controller = new AbortController();
audio.addEventListener('seeking', () => {
  console.log('seeking via addEventListener');
}, { signal: controller.signal });

// Später: Listener entfernen
controller.abort();
audio.onseeking = null;

seeking via onseeking: true

// Wichtig · Fallstricke

Kein Aufsteigen: seeking bubbelt nicht. Für Delegation auf einem Container muss { capture: true } verwendet werden.
currentTime ist bereits das Ziel: Die alte Position ist im Handler nicht mehr verfügbar – sie muss vorher (z. B. in timeupdate) zwischengespeichert werden.
Häufige Auslösung: Beim Ziehen des Fortschrittsbalkens feuern viele seeking-Ereignisse hintereinander, teils ohne dazwischenliegendes seeked. Aufwendige Logik (Netzwerk-Tracking) daher entprellen (Debounce).
Nach seeking folgen je nach Pufferzustand ggf. waiting, dann seeked und canplay.
Kompatibilität: In allen modernen Browsern seit Langem unterstützt; fastSeek() dagegen nicht überall (u. a. fehlt es in Chromium).

Siehe auch

HTMLMediaElement: seeked HTMLMediaElement.currentTime HTMLMediaElement.fastSeek() HTMLMediaElement: timeupdate HTMLMediaElement: waiting EventTarget.addEventListener()