MediaStreamTrack: unmute — Ereignis · JavaScript-Referenz

Signatur

track.addEventListener("unmute", handler)

Beschreibung

Das Ereignis unmute wird an einem MediaStreamTrack ausgelöst, sobald dessen Quelle nach einer Phase ohne Mediendaten wieder Daten liefern kann. Unmittelbar vorher wechselt die schreibgeschützte Eigenschaft track.muted von true auf false. Das Gegenstück ist das Ereignis mute.

Wichtig: muted ist nicht dasselbe wie track.enabled. Die Eigenschaft enabled steuert die Anwendung selbst, etwa über einen Stummschalt-Button. muted dagegen spiegelt einen Zustand wider, den die Anwendung nicht direkt kontrolliert, zum Beispiel wenn der Nutzer die Kamera über Betriebssystem oder Browser pausiert, ein Hardware-Schalter umgelegt wird oder bei WebRTC vorübergehend keine RTP-Pakete vom Gegenüber ankommen.

Registrieren lässt sich ein Handler mit track.addEventListener("unmute", handler) oder über die Eigenschaft track.onunmute. Das Ereignis ist ein einfaches Event ohne zusätzliche Eigenschaften. Es steigt nicht auf (bubbles nicht) und lässt sich nicht abbrechen.

Typische Einsatzfälle sind Benutzeroberflächen, die „Kamera pausiert“ oder „Keine Verbindung zum Video“ anzeigen und diesen Hinweis wieder ausblenden, sobald Daten fließen. Außerdem nutzt man das Ereignis bei WebRTC-Remote-Tracks, deren Video erst mit dem ersten eintreffenden Paket sichtbar wird.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignistyp, hier immer `"unmute"`.
$handler Pflicht	(event: Event) => void		Callback, der beim Ereignis aufgerufen wird. `event.target` ist der betroffene `MediaStreamTrack`.
$options	boolean \| AddEventListenerOptions	false	Optionale Listener-Optionen wie `once` oder `signal` (`AbortSignal`) zum späteren Entfernen.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler bekommt ein Event-Objekt übergeben.

Beispiele

Kamera-Track überwachen mit addEventListener

const stream = await navigator.mediaDevices.getUserMedia({ video: true });
const [videoTrack] = stream.getVideoTracks();
const hinweis = document.querySelector('#kamera-hinweis');

videoTrack.addEventListener('mute', () => {
  hinweis.textContent = 'Kamera liefert gerade kein Bild.';
  hinweis.hidden = false;
});

videoTrack.addEventListener('unmute', (event) => {
  console.log(`Track ${event.target.label} liefert wieder Daten, muted =`, event.target.muted);
  hinweis.hidden = true;
});

Track FaceTime HD Camera liefert wieder Daten, muted = false

WebRTC: Remote-Video erst bei eintreffenden Daten anzeigen (onunmute)

const pc = new RTCPeerConnection();
const remoteVideo = document.querySelector('#remote');

pc.ontrack = ({ track, streams }) => {
  remoteVideo.srcObject = streams[0];
  remoteVideo.classList.add('warte');

  // Remote-Tracks starten oft im Zustand muted, bis RTP-Pakete eintreffen
  track.onunmute = () => {
    remoteVideo.classList.remove('warte');
    console.log(`${track.kind}-Track des Gegenübers aktiv`);
  };
  track.onmute = () => remoteVideo.classList.add('warte');
};

video-Track des Gegenübers aktiv

Listener mit AbortController wieder entfernen

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

const onUnmute = () => console.log('Mikrofon wieder aktiv');
audioTrack.addEventListener('unmute', onUnmute, { signal: controller.signal });

// Beim Verlassen der Ansicht aufräumen:
const aufraeumen = () => {
  controller.abort(); // entfernt den Listener
  // alternativ: audioTrack.removeEventListener('unmute', onUnmute);
  audioTrack.stop();
};

// Wichtig · Fallstricke

Nicht mit enabled verwechseln: Wenn du track.enabled = true setzt, wird kein unmute ausgelöst. Das Ereignis reagiert nur auf Zustandsänderungen der Quelle, auf die deine Anwendung keinen direkten Einfluss hat.
Ein gestoppter Track (readyState === "ended") löst kein unmute mehr aus. Dafür gibt es das Ereignis ended.
WebRTC-Remote-Tracks sind beim track-Ereignis oft zunächst muted. Das erste unmute zeigt dann an, dass tatsächlich Medien ankommen.
Wann genau mute/unmute feuern, unterscheidet sich zwischen Browsern und Betriebssystemen. Safari schaltet Tracks zum Beispiel beim Wechsel in den Hintergrund oder bei Unterbrechungen durch das System stumm. Chrome und Firefox verhalten sich teilweise anders. Verlass dich deshalb nicht auf ein bestimmtes Timing.
Das Ereignis ist in allen modernen Browsern verfügbar. Voraussetzung ist ein sicherer Kontext (HTTPS), weil getUserMedia nur dort funktioniert.

Siehe auch

MediaStreamTrack: mute MediaStreamTrack.muted MediaStreamTrack.enabled MediaStreamTrack: ended MediaStreamTrack MediaDevices.getUserMedia() RTCPeerConnection: track