HTMLMediaElement: volumechange — Ereignis · JavaScript-Referenz

Signatur

element.addEventListener("volumechange", handler)

Beschreibung

Das Ereignis volumechange wird an einem HTMLMediaElement (also <audio> oder <video>) ausgelöst, wenn sich die Eigenschaft volume oder die Eigenschaft muted geändert hat. Dabei ist es egal, ob die Änderung per Skript, über die eingebauten Bedienelemente des Browsers (controls) oder über Systemfunktionen erfolgt.

Typische Anwendungsfälle sind eigene Player-Oberflächen, deren Lautstärkeregler und Stummschalt-Symbol mit dem tatsächlichen Zustand synchron bleiben sollen, sowie das Speichern der Lautstärke-Einstellung (z. B. in localStorage), damit sie beim nächsten Besuch wiederhergestellt werden kann.

Das Ereignis ist ein einfaches Event ohne zusätzliche Daten. Es ist nicht abbrechbar (cancelable: false) und steigt nicht auf (bubbles: false). Den neuen Zustand liest man daher direkt über event.target.volume und event.target.muted aus. Alternativ zu addEventListener kann die Eigenschaft onvolumechange verwendet werden.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"volumechange"`.
$handler Pflicht	(event: Event) => void		Callback, der bei jeder Änderung von `volume` oder `muted` aufgerufen wird. Erhält ein einfaches `Event`-Objekt.
$options	boolean\|AddEventListenerOptions	false	Optionen wie `once`, `passive`, `signal` oder `capture`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Das Ereignisobjekt ist ein generisches Event.

Beispiele

Lautstärke-Anzeige mit addEventListener synchronisieren

const video = document.querySelector('video');
const anzeige = document.querySelector('#lautstaerke');

const aktualisieren = ({ target }) => {
  anzeige.textContent = target.muted
    ? 'Stumm'
    : `${Math.round(target.volume * 100)} %`;
};

video.addEventListener('volumechange', aktualisieren);

// Änderung per Skript löst das Ereignis ebenfalls aus
video.volume = 0.5;

Anzeige zeigt: 50 %

Lautstärke dauerhaft in localStorage speichern

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

// Gespeicherte Einstellung wiederherstellen
const gespeichert = JSON.parse(localStorage.getItem('player-audio') ?? 'null');
if (gespeichert) {
  audio.volume = gespeichert.volume;
  audio.muted = gespeichert.muted;
}

audio.onvolumechange = () => {
  localStorage.setItem('player-audio', JSON.stringify({
    volume: audio.volume,
    muted: audio.muted,
  }));
};

Eigener Stumm-Button und Listener wieder entfernen

const video = document.querySelector('video');
const muteBtn = document.querySelector('#mute');

const beiAenderung = () => {
  muteBtn.textContent = video.muted || video.volume === 0 ? '🔇' : '🔊';
  console.log('volume:', video.volume, 'muted:', video.muted);
};

video.addEventListener('volumechange', beiAenderung);
muteBtn.addEventListener('click', () => {
  video.muted = !video.muted;
});

// Später, z. B. beim Abbau der Komponente:
const aufraeumen = () => video.removeEventListener('volumechange', beiAenderung);

volume: 1 muted: true

// Wichtig · Fallstricke

muted und volume sind unabhängig: Beim Stummschalten bleibt volume unverändert. Prüfe für „kein Ton“ immer beide Werte (muted || volume === 0).
Das Ereignis wird nur ausgelöst, wenn sich der Wert tatsächlich ändert. video.volume = video.volume löst kein Ereignis aus.
Werte für volume außerhalb von 0–1 werfen einen IndexSizeError; es wird dann kein volumechange ausgelöst.
iOS/iPadOS Safari: volume ist dort schreibgeschützt (liefert immer 1) – die Lautstärke wird über die Hardware-Tasten gesteuert, die kein volumechange auslösen. muted funktioniert dagegen.
Das Ereignis steigt nicht auf. Für Ereignisdelegation an einem Elternelement musst du capture: true verwenden.
Beim Speichern in localStorage kann das Ereignis beim Ziehen eines Reglers sehr oft feuern – gegebenenfalls drosseln (Debounce).
Unterstützt in allen modernen Browsern seit vielen Jahren.

Siehe auch

HTMLMediaElement.volume HTMLMediaElement.muted HTMLMediaElement EventTarget.addEventListener() HTMLFormElement: formdata