HTMLMediaElement.volume — Eigenschaft · JavaScript-Referenz

Signatur

HTMLMediaElement.volume

Beschreibung

Die Eigenschaft volume gibt die aktuelle Lautstärke eines Medienelements als Gleitkommazahl zurück und lässt sich auch setzen. Der Wert 0.0 bedeutet Stille, 1.0 die maximale Lautstärke. Das ist die Lautstärke des Elements selbst, nicht die Systemlautstärke. Der Standardwert ist 1.0.

Typische Einsatzfälle sind eigene Lautstärkeregler für selbst gebaute Player, Ein- und Ausblenden (Fade-in/Fade-out) von Hintergrundmusik und das Speichern der Nutzereinstellung, etwa in localStorage. Jede Änderung löst das Ereignis volumechange aus. Damit bleibt die Oberfläche auch dann synchron, wenn der Nutzer die nativen Bedienelemente verwendet.

volume ist unabhängig von muted. Wird ein Element stummgeschaltet, bleibt der volume-Wert erhalten, und nach dem Aufheben der Stummschaltung ist die vorherige Lautstärke wieder da. Umgekehrt setzt volume = 0 die Eigenschaft muted nicht auf true.

Parameter

Name	Typ	Default	Beschreibung
$value	number	1.0	Beim Setzen: neue Lautstärke im Bereich `0.0` bis `1.0`. Werte außerhalb dieses Bereichs lösen einen `IndexSizeError` (`DOMException`) aus.

Rückgabewert

Typ

number

Beschreibung

Die aktuelle Lautstärke als double zwischen 0.0 und 1.0.

Beispiele

Lautstärke lesen und setzen

const video = document.querySelector('video');
console.log(video.volume); // Standardwert
video.volume = 0.5;        // halbe Lautstärke
console.log(video.volume);

1 0.5

Lautstärkeregler mit Speicherung in localStorage

// HTML: <audio id="player" src="musik.mp3" controls></audio>
//       <input id="vol" type="range" min="0" max="1" step="0.01">
const player = document.getElementById('player');
const slider = document.getElementById('vol');

const saved = Number(localStorage.getItem('volume') ?? 0.8);
player.volume = Math.min(1, Math.max(0, saved));
slider.value = player.volume;

slider.addEventListener('input', () => {
  player.volume = Number(slider.value);
});

// Regler auch bei Änderungen über die nativen Bedienelemente aktualisieren
player.addEventListener('volumechange', () => {
  slider.value = player.volume;
  localStorage.setItem('volume', player.volume);
});

Sanftes Ausblenden (Fade-out) mit async/await

const fadeOut = async (media, duration = 2000, steps = 40) => {
  const start = media.volume;
  const delay = duration / steps;
  for (let i = steps - 1; i >= 0; i--) {
    media.volume = Math.max(0, (start * i) / steps);
    await new Promise((r) => setTimeout(r, delay));
  }
  media.pause();
  media.volume = start; // Ausgangswert für die nächste Wiedergabe wiederherstellen
};

const bgm = document.querySelector('audio');
document.querySelector('#stop').addEventListener('click', () => fadeOut(bgm));

Ungültige Werte abfangen

const audio = new Audio();
try {
  audio.volume = 1.5;
} catch (err) {
  console.log(err.name);
}
// Sicher: Wert vorher begrenzen
const clamp = (v) => Math.min(1, Math.max(0, v));
audio.volume = clamp(1.5);
console.log(audio.volume);

IndexSizeError 1

// Wichtig · Fallstricke

Wertebereich: Werte kleiner 0 oder größer 1 lösen einen IndexSizeError aus. Begrenze Eingaben daher vorher, zum Beispiel mit Math.min/Math.max. Bei NaN wird ein TypeError geworfen.
iOS/iPadOS Safari: Dort wird volume ignoriert, weil die Lautstärke nur über die Hardware-Tasten geregelt wird. Beim Lesen erhält man immer 1, und das Setzen hat keine hörbare Wirkung. Zum Stummschalten nimmst du muted. Für echte Lautstärkeregelung eignet sich die Web Audio API mit einem GainNode.
Linearer Wert: Die Skala ist linear, das Gehör nimmt Lautstärke aber etwa logarithmisch wahr. Für natürlich wirkende Regler kann eine Kurve wie value ** 2 sinnvoll sein.
Autoplay: Eine niedrige Lautstärke umgeht die Autoplay-Sperren der Browser nicht. Ohne Nutzerinteraktion ist nur stummgeschaltete Wiedergabe (muted) erlaubt.
Das Attribut volume gibt es in HTML nicht. Die Lautstärke lässt sich nur per JavaScript setzen.

Siehe auch

HTMLMediaElement.muted HTMLMediaElement HTMLMediaElement.play() GainNode ElementInternals.ariaValueMax HTMLMetaElement.name