MediaSession.setMicrophoneActive() — Methode · JavaScript-Referenz

Signatur

MediaSession.prototype.setMicrophoneActive(active)

Beschreibung

Mit navigator.mediaSession.setMicrophoneActive() meldet eine Videokonferenz- oder Sprach-App dem Browser, ob das Mikrofon in der App gerade aktiv oder stummgeschaltet ist. Der Browser kann diesen Zustand dann in seinen eigenen Bedienelementen anzeigen, etwa im Bild-in-Bild-Fenster, in Systemsteuerungen oder in Mediensteuerungen des Betriebssystems.

Gedacht ist die Methode für das Zusammenspiel mit dem Aktions-Handler "togglemicrophone", den man über setActionHandler() registriert. Drückt der Nutzer im Browser-Bedienelement auf „Mikrofon umschalten“, ruft der Browser deinen Handler auf. Du schaltest dann die Audiospur an oder aus (z. B. über MediaStreamTrack.enabled) und bestätigst den neuen Zustand mit setMicrophoneActive(). Bei Änderungen in der eigenen Oberfläche der App solltest du die Methode ebenfalls aufrufen, damit beide Anzeigen übereinstimmen.

Wichtig: Die Methode schaltet das Mikrofon nicht selbst stumm. Sie beeinflusst nur, was der Browser anzeigt. Das eigentliche Stummschalten musst du über die MediaStreamTrack-Objekte erledigen. Das Gegenstück für die Kamera ist setCameraActive().

Parameter

Name	Typ	Default	Beschreibung
$active Pflicht	boolean		`true`, wenn das Mikrofon aktiv ist (Ton wird übertragen), `false`, wenn es in der App stummgeschaltet ist.

Rückgabewert

Typ

Promise<undefined> | undefined

Beschreibung

Laut Spezifikation ein Promise, das mit undefined erfüllt wird, sobald der Browser den Zustand übernommen hat. Ältere Implementierungen geben direkt undefined zurück. Mit await funktionieren beide Fälle.

Beispiele

Mikrofonzustand mit Funktionsprüfung melden

const reportMicState = async (active) => {
  const session = navigator.mediaSession;
  if (session && typeof session.setMicrophoneActive === 'function') {
    await session.setMicrophoneActive(active);
    console.log(`Browser informiert: Mikrofon ${active ? 'aktiv' : 'stumm'}`);
  } else {
    console.log('setMicrophoneActive() wird nicht unterstützt');
  }
};

reportMicState(false);

Browser informiert: Mikrofon stumm

„togglemicrophone“-Aktion in einer Videokonferenz

const stream = await navigator.mediaDevices.getUserMedia({ audio: true, video: true });
const [audioTrack] = stream.getAudioTracks();
let micActive = true;

const setMic = async (active) => {
  micActive = active;
  audioTrack.enabled = active; // wirklich stummschalten
  document.querySelector('#mic-btn').textContent = active ? 'Stumm schalten' : 'Stummschaltung aufheben';
  await navigator.mediaSession.setMicrophoneActive?.(active); // Browser-Anzeige anpassen
};

try {
  navigator.mediaSession.setActionHandler('togglemicrophone', () => setMic(!micActive));
} catch {
  console.log('Aktion togglemicrophone nicht unterstützt');
}

// Button der eigenen Oberfläche
document.querySelector('#mic-btn').addEventListener('click', () => setMic(!micActive));

await setMic(true);

Zusammen mit der Kamera und „hangup“ verwenden

const session = navigator.mediaSession;

const endCall = async () => {
  await session.setMicrophoneActive?.(false);
  await session.setCameraActive?.(false);
  for (const action of ['togglemicrophone', 'togglecamera', 'hangup']) {
    try { session.setActionHandler(action, null); } catch {}
  }
  console.log('Anruf beendet');
};

try { session.setActionHandler('hangup', endCall); } catch {}

// Wichtig · Fallstricke

Nur Anzeige: Die Methode schaltet kein Mikrofon stumm. Ohne track.enabled = false bzw. track.stop() wird weiterhin Ton übertragen. Das kann ein Datenschutzproblem werden, wenn Anzeige und tatsächlicher Zustand nicht übereinstimmen.
Kompatibilität: Experimentell und bisher nur in Chromium-Browsern verfügbar. Prüfe vorher, ob die Methode existiert (typeof navigator.mediaSession?.setMicrophoneActive === 'function'), oder rufe sie optional mit ?.() auf. setActionHandler('togglemicrophone', …) kann in nicht unterstützenden Browsern einen TypeError auslösen, also in try/catch einschließen.
Der Browser entscheidet selbst, ob und wo er den Zustand anzeigt. Oft geschieht das nur, wenn ein togglemicrophone-Handler registriert ist, zum Beispiel im Bild-in-Bild-Fenster.
Rufe die Methode bei jeder Änderung auf, auch wenn der Nutzer die Stummschaltung über die eigene Oberfläche der App ändert. Nur so bleibt die Anzeige im Browser richtig.
Nur in sicheren Kontexten (HTTPS) sinnvoll, weil getUserMedia() dort vorausgesetzt wird.

Siehe auch

MediaKeys.setServerCertificate() MediaSession.setCameraActive() MediaSession.setScreenshareActive() MediaSession.setActionHandler() MediaSession.setPositionState()