HTMLMediaElement: ratechange — Ereignis · JavaScript-Referenz

Signatur

element.addEventListener("ratechange", handler)

Beschreibung

Das Ereignis ratechange wird an einem HTMLMediaElement (also <audio> oder <video>) ausgelöst, sobald sich die Wiedergabegeschwindigkeit ändert. Auslöser ist eine Änderung von playbackRate (aktuelle Geschwindigkeit) oder defaultPlaybackRate (Standardgeschwindigkeit, die z. B. nach dem Laden einer neuen Quelle gilt).

Das Ereignis ist nicht abbrechbar (cancelable: false) und steigt nicht auf (bubbles: false). Den Handler registrierst du entweder mit addEventListener("ratechange", handler) oder über die Eigenschaft onratechange. Willst du es mit Event-Delegation am Elternelement abfangen, brauchst du die Capture-Phase ({ capture: true }).

Typische Anwendungsfälle: eine eigene Geschwindigkeitsanzeige in einem Player aktuell halten (auch wenn der Nutzer das native Kontextmenü oder Browser-Erweiterungen benutzt), die bevorzugte Geschwindigkeit in localStorage speichern, Analysedaten erfassen oder Untertitel- bzw. Animationssynchronisation anpassen.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"ratechange"`.
$handler Pflicht	(event: Event) => void		Callback, der ein einfaches `Event`-Objekt erhält. Die neue Geschwindigkeit liest du über `event.target.playbackRate` bzw. `defaultPlaybackRate` aus – das Ereignis selbst enthält keinen Wert.
$options	boolean \| AddEventListenerOptions	false	Optionen wie `once`, `passive`, `signal` oder `capture` (nötig für Delegation, weil das Ereignis nicht aufsteigt).

Beispiele

Geschwindigkeitsanzeige mit addEventListener aktualisieren

const video = document.querySelector('video');
const label = document.querySelector('#speed');

video.addEventListener('ratechange', (event) => {
  const rate = event.target.playbackRate;
  label.textContent = `${rate}×`;
  console.log(`Neue Geschwindigkeit: ${rate}`);
});

// Auslösen, z. B. durch einen Button
document.querySelector('#faster').addEventListener('click', () => {
  video.playbackRate = Math.min(video.playbackRate + 0.25, 4);
});

Neue Geschwindigkeit: 1.25

Bevorzugte Geschwindigkeit speichern und wiederherstellen

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

// Gespeicherten Wert als Standard setzen
const saved = Number(localStorage.getItem('podcastRate')) || 1;
audio.defaultPlaybackRate = saved;
audio.playbackRate = saved;

audio.onratechange = () => {
  localStorage.setItem('podcastRate', String(audio.playbackRate));
};

Listener per AbortController wieder entfernen

const video = document.querySelector('video');
const controller = new AbortController();

const logRate = () => console.log('Rate:', video.playbackRate);
video.addEventListener('ratechange', logRate, { signal: controller.signal });

video.playbackRate = 2;   // löst aus

// Später: Listener abmelden (alternativ removeEventListener)
setTimeout(() => {
  controller.abort();
  // gleichwertig: video.removeEventListener('ratechange', logRate);
  video.playbackRate = 0.5; // kein Log mehr
}, 0);

Rate: 2

Delegation für mehrere Player in der Capture-Phase

// ratechange steigt nicht auf – daher capture: true
document.addEventListener('ratechange', (event) => {
  if (event.target instanceof HTMLMediaElement) {
    console.log(`${event.target.id}: ${event.target.playbackRate}×`);
  }
}, { capture: true });

intro-video: 1.5×

// Wichtig · Fallstricke

Asynchron: Das Ereignis wird als Task in die Warteschlange gestellt und nicht sofort beim Setzen von playbackRate ausgelöst. Code direkt nach der Zuweisung läuft also vor dem Handler.
Kein Aufsteigen: ratechange bubbelt nicht. Für Delegation brauchst du { capture: true }.
Gleicher Wert: Setzt du denselben Wert erneut, wird kein Ereignis ausgelöst.
Endlosschleifen vermeiden: Wenn du im Handler playbackRate setzt (z. B. um Grenzen zu erzwingen), prüfe vorher, ob sich der Wert wirklich unterscheidet.
Wertebereich: Browser unterstützen nur bestimmte Bereiche (etwa 0,0625–16 in Chrome/Firefox). Werte außerhalb werfen einen NotSupportedError, dann wird kein ratechange ausgelöst. Bei 0 verhalten sich die Browser unterschiedlich.
Tonhöhe: Ob die Tonhöhe bei geänderter Geschwindigkeit erhalten bleibt, steuert preservesPitch (ältere Browser: mit Präfix).
Das Ereignis wird in allen modernen Browsern unterstützt (Baseline).

Siehe auch

HTMLMediaElement.playbackRate HTMLMediaElement.defaultPlaybackRate HTMLMediaElement.preservesPitch HTMLMediaElement: volumechange HTMLMediaElement: timeupdate HTMLMediaElement EventTarget.addEventListener()