MediaStreamTrack: mute — Ereignis · JavaScript-Referenz

Signatur

track.addEventListener("mute", handler)

Beschreibung

Das Ereignis mute wird an einen MediaStreamTrack gesendet, sobald seine Quelle vorübergehend keine Mediendaten mehr liefert. Gleichzeitig wechselt die schreibgeschützte Eigenschaft muted auf true. Solange der Track stummgeschaltet ist, gibt er bei Audio Stille und bei Video schwarze (leere) Bilder aus. Sobald wieder Daten fließen, folgt das Gegenstück unmute.

Typische Auslöser sind Netzwerkprobleme bei einem entfernten WebRTC-Track (z. B. wenn der Sender keine Pakete mehr schickt oder replaceTrack(null) aufruft), ein Kamera- oder Mikrofonzugriff, den das Betriebssystem unterbricht (etwa weil eine andere Anwendung das Gerät belegt oder der Nutzer es per Hardware-Schalter bzw. über Systemeinstellungen sperrt), oder ein mobiles Gerät, das die Aufnahme während eines Telefonats anhält.

Wichtig ist der Unterschied zu track.enabled: enabled = false ist eine bewusste Stummschaltung durch die Anwendung und löst kein mute-Ereignis aus. mute spiegelt dagegen einen Zustand wider, den weder Seite noch Nutzer über die API direkt steuern. Man nutzt das Ereignis daher, um im UI Hinweise wie „Verbindung unterbrochen“ oder „Kamera wird von einer anderen App verwendet“ anzuzeigen.

Registrieren lässt sich ein Handler per addEventListener("mute", handler) oder über die Eigenschaft track.onmute. Das Ereignis ist ein einfaches Event, blubbert nicht und ist nicht abbrechbar.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"mute"`.
$handler Pflicht	(event: Event) => void		Callback, das bei Stummschaltung der Quelle aufgerufen wird. `event.target` ist der betroffene `MediaStreamTrack`.
$options	boolean \| AddEventListenerOptions	false	Optionale Listener-Optionen wie `once` oder `signal` (zum Entfernen per `AbortController`).

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler erhält ein Event-Objekt vom Typ "mute".

Beispiele

Stummschaltung eines lokalen Kamera-Tracks erkennen

const stream = await navigator.mediaDevices.getUserMedia({ video: true });
const [videoTrack] = stream.getVideoTracks();

const status = document.querySelector('#kamera-status');

videoTrack.addEventListener('mute', () => {
  status.textContent = 'Kamera liefert gerade kein Bild.';
  console.log('muted:', videoTrack.muted);
});

videoTrack.addEventListener('unmute', () => {
  status.textContent = 'Kamera aktiv.';
  console.log('muted:', videoTrack.muted);
});

muted: true muted: false

Entfernten WebRTC-Track überwachen (onmute-Property)

const pc = new RTCPeerConnection();

pc.ontrack = ({ track, streams }) => {
  const video = document.querySelector('#remote');
  video.srcObject = streams[0];

  track.onmute = () => {
    console.warn(`${track.kind}-Track unterbrochen`);
    video.classList.add('verbindung-gestoert');
  };

  track.onunmute = () => {
    console.info(`${track.kind}-Track wieder aktiv`);
    video.classList.remove('verbindung-gestoert');
  };
};

video-Track unterbrochen video-Track wieder aktiv

Listener per AbortController wieder entfernen

const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
const [micTrack] = stream.getAudioTracks();
const controller = new AbortController();

const onMute = (event) => {
  console.log('Mikrofon stumm:', event.target.label);
};

micTrack.addEventListener('mute', onMute, { signal: controller.signal });

// Später, z. B. beim Verlassen des Calls:
controller.abort();
// alternativ: micTrack.removeEventListener('mute', onMute);
micTrack.stop();

Unterschied zu enabled = false

const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
const [track] = stream.getAudioTracks();

track.addEventListener('mute', () => console.log('mute-Ereignis!'));

// Bewusstes Stummschalten durch die App löst KEIN mute aus:
track.enabled = false;
console.log('enabled:', track.enabled, 'muted:', track.muted);

enabled: false muted: false

// Wichtig · Fallstricke

Nicht mit enabled verwechseln: track.enabled = false löst kein mute aus und ändert muted nicht. Für eine UI-Stummschalttaste also enabled verwenden, mute nur für von außen verursachte Unterbrechungen auswerten.
Nicht mit ended verwechseln: mute ist vorübergehend; ein beendeter Track (readyState === "ended") sendet ended und wird nie wieder aktiv.
Remote-Tracks starten oft stumm: Bei WebRTC ist ein über ontrack empfangener Track häufig zunächst muted, bis erste RTP-Pakete eintreffen. Den Anfangszustand daher immer über track.muted prüfen, statt nur auf Ereignisse zu warten.
Browserunterschiede: Wann genau mute ausgelöst wird, hängt von Browser und Betriebssystem ab. Safari auf iOS schaltet z. B. Tracks bei eingehenden Anrufen oder beim Wechsel in den Hintergrund stumm; Chrome feuert bei Remote-Tracks nach Paketausfall mit Verzögerung. Nicht auf exaktes Timing verlassen.
Das Ereignis blubbert nicht und ist nicht abbrechbar – die Stummschaltung lässt sich per preventDefault() nicht verhindern.

Siehe auch

MediaStreamTrack MediaStreamTrack.muted MediaStreamTrack.enabled MediaDevices.getUserMedia() MediaStreamTrack: unmute