HTMLMediaElement.muted — Eigenschaft · JavaScript-Referenz

Signatur

HTMLMediaElement.muted

Beschreibung

Die Eigenschaft muted eines HTMLMediaElement (also <audio> oder <video>) ist ein boolescher Wert, der angibt, ob die Tonausgabe stummgeschaltet ist. Mit true wird der Ton stummgeschaltet, mit false wieder eingeschaltet. Die Wiedergabe selbst läuft dabei unverändert weiter – nur der Ton fehlt.

muted ist unabhängig von volume: Beim Stummschalten bleibt der eingestellte Lautstärkewert (0.0–1.0) erhalten, sodass nach dem Aufheben der Stummschaltung wieder die vorherige Lautstärke gilt. Deshalb ist muted die richtige Wahl für einen „Ton aus/an“-Schalter, statt volume auf 0 zu setzen.

Wichtig ist der Unterschied zum HTML-Attribut muted: Das Attribut entspricht der Eigenschaft defaultMuted und legt nur den Anfangszustand fest. Die Eigenschaft muted spiegelt den aktuellen Zustand wider und verändert das Attribut nicht. Jede Änderung von muted löst das Ereignis volumechange aus.

Besonders relevant ist muted im Zusammenhang mit Autoplay-Richtlinien: Moderne Browser erlauben automatische Wiedergabe mit Ton in der Regel nur nach einer Benutzerinteraktion, stummgeschaltete Videos dürfen dagegen meist automatisch starten.

Parameter

Name	Typ	Default	Beschreibung
$value	boolean	false (bzw. Wert von defaultMuted)	Beim Setzen: `true` schaltet den Ton stumm, `false` hebt die Stummschaltung auf. Andere Werte werden in einen booleschen Wert umgewandelt.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn das Medienelement aktuell stummgeschaltet ist, sonst false.

Beispiele

Stummschalt-Button für ein Video

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

const updateLabel = () => {
  muteBtn.textContent = video.muted ? '🔇 Ton an' : '🔊 Ton aus';
  muteBtn.setAttribute('aria-pressed', String(video.muted));
};

muteBtn.addEventListener('click', () => {
  video.muted = !video.muted; // Zustand umschalten
});

// volumechange feuert auch bei Änderungen über die nativen Controls
video.addEventListener('volumechange', updateLabel);
updateLabel();

Autoplay stumm starten, falls mit Ton blockiert

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

const startPlayback = async () => {
  try {
    video.muted = false;
    await video.play();
    console.log('Wiedergabe mit Ton gestartet');
  } catch (err) {
    if (err.name === 'NotAllowedError') {
      // Browser blockiert Autoplay mit Ton – stumm erneut versuchen
      video.muted = true;
      await video.play();
      console.log('Wiedergabe stumm gestartet');
    } else {
      throw err;
    }
  }
};

startPlayback();

Wiedergabe stumm gestartet

muted vs. volume vs. defaultMuted

const audio = new Audio('podcast.mp3');
audio.volume = 0.6;

audio.muted = true;
console.log(audio.muted, audio.volume); // Lautstärke bleibt erhalten

audio.muted = false;
console.log(audio.muted, audio.volume);

// Das HTML-Attribut ändert sich durch muted nicht
console.log(audio.defaultMuted, audio.hasAttribute('muted'));

true 0.6 false 0.6 false false

// Wichtig · Fallstricke

Attribut vs. Eigenschaft: video.muted = true setzt nicht das HTML-Attribut muted. Für den Anfangszustand (z. B. bei serverseitig gerendertem Markup oder für Autoplay-Prüfungen beim Laden) das Attribut im HTML setzen bzw. defaultMuted verwenden. In Frameworks wie React wird das Attribut muted teilweise nicht ins DOM übertragen – dann per Ref element.muted = true setzen.
Autoplay-Richtlinien: Chrome, Safari und Firefox erlauben automatisches Abspielen meist nur stummgeschaltet (auf iOS zusätzlich mit playsinline). Die Stummschaltung per Skript ohne Benutzergeste aufzuheben kann dazu führen, dass der Browser die Wiedergabe pausiert.
iOS Safari: volume ist dort schreibgeschützt (Hardware-Tasten), muted funktioniert jedoch – deshalb für Ton-Schalter immer muted nutzen.
Jede Änderung löst volumechange aus; Oberflächen sollten auf dieses Ereignis reagieren statt den Zustand selbst nachzuhalten, da Benutzer auch über die nativen Steuerelemente stummschalten können.
Die Eigenschaft wird seit Jahren von allen gängigen Browsern unterstützt.

Siehe auch

HTMLMediaElement.volume HTMLMediaElement.defaultMuted HTMLMediaElement.play() HTMLMediaElement.autoplay HTMLMediaElement HTMLMediaElement.currentSrc