MediaSession.setScreenshareActive() — Methode · JavaScript-Referenz

Signatur

MediaSession.prototype.setScreenshareActive(active)

Beschreibung

Mit navigator.mediaSession.setScreenshareActive() meldet eine Web-App, meist für Videokonferenzen oder Streaming, dem Browser, ob der Benutzer gerade seinen Bildschirm teilt. Der Browser kann diesen Zustand in eigenen Bedienelementen anzeigen, zum Beispiel in einer Steuerung für Bild-im-Bild-Fenster, in der Medienanzeige des Betriebssystems oder in einem Tab-Symbol. So stimmt die Anzeige des Browsers mit dem Zustand der App überein.

Die Methode gehört zu einer Gruppe von Konferenz-Methoden der Media Session API, zusammen mit setMicrophoneActive() und setCameraActive(). Sie wird typischerweise mit einem Action-Handler kombiniert, den man über setActionHandler() registriert. Der Browser meldet damit den Wunsch des Benutzers, die Übertragung umzuschalten. Die App startet oder beendet dann die Übertragung und meldet danach den neuen Zustand mit setScreenshareActive() zurück.

Wichtig: Die Methode startet und beendet keine Bildschirmübertragung. Das geschieht weiter über navigator.mediaDevices.getDisplayMedia() und das Stoppen der zugehörigen MediaStreamTracks. setScreenshareActive() meldet nur den Zustand.

Parameter

Name	Typ	Default	Beschreibung
$active Pflicht	boolean		`true`, wenn die Bildschirmübertragung aktiv ist, sonst `false`.

Beispiele

Zustand nach dem Start der Übertragung melden

const startScreenshare = async () => {
  const stream = await navigator.mediaDevices.getDisplayMedia({ video: true });

  // Prüfen, ob der Browser die Methode kennt
  if ('setScreenshareActive' in navigator.mediaSession) {
    navigator.mediaSession.setScreenshareActive(true);
  }

  // Wenn der Benutzer über den Browser-Dialog stoppt, Zustand zurücksetzen
  const [track] = stream.getVideoTracks();
  track.addEventListener('ended', () => {
    navigator.mediaSession.setScreenshareActive?.(false);
    console.log('Bildschirmübertragung beendet');
  });

  return stream;
};

document.querySelector('#share').addEventListener('click', startScreenshare);

Bildschirmübertragung beendet (nach dem Stoppen)

Umschalten über die Browser-Steuerung

let screenStream = null;

const setShareState = (active) => {
  navigator.mediaSession.setScreenshareActive?.(active);
  console.log(`Screenshare aktiv: ${active}`);
};

const toggleScreenshare = async () => {
  if (screenStream) {
    screenStream.getTracks().forEach((t) => t.stop());
    screenStream = null;
    setShareState(false);
  } else {
    screenStream = await navigator.mediaDevices.getDisplayMedia({ video: true });
    setShareState(true);
  }
};

try {
  // Action-Name laut aktuellem Entwurf; nicht überall unterstützt
  navigator.mediaSession.setActionHandler('togglescreenshare', toggleScreenshare);
} catch {
  console.warn('Action "togglescreenshare" wird nicht unterstützt');
}

Screenshare aktiv: true Screenshare aktiv: false

Alle Konferenz-Zustände zusammen melden

const syncConferenceState = ({ mic, camera, screen }) => {
  const ms = navigator.mediaSession;
  if (!ms) return;
  ms.setMicrophoneActive?.(mic);
  ms.setCameraActive?.(camera);
  ms.setScreenshareActive?.(screen);
};

syncConferenceState({ mic: true, camera: false, screen: true });

// Wichtig · Fallstricke

Experimentell: Die Methode ist erst in einzelnen Chromium-Versionen vorhanden, Firefox und Safari kennen sie nicht. Vor dem Aufruf immer die Unterstützung prüfen ('setScreenshareActive' in navigator.mediaSession oder optionaler Aufruf mit ?.()). Name und Verhalten können sich noch ändern.
Die Methode startet oder beendet keine Übertragung. Sie meldet nur den Zustand. Wer sie nicht aufruft oder vergisst, sie nach dem Stoppen zurückzusetzen, zeigt dem Benutzer einen falschen Zustand an. Deshalb auf das ended-Ereignis des Tracks reagieren, denn Benutzer beenden die Übertragung oft über die Browser-Leiste.
setActionHandler() wirft einen TypeError, wenn der Browser einen Action-Namen nicht kennt. Die Registrierung daher in try…catch einschließen.
Es kann eine Weile dauern, bis der Browser seine Anzeige aktualisiert. Außerdem kann der Browser den Zustand ignorieren, etwa wenn gerade keine Medienaufnahme läuft.
Die Media Session API setzt einen sicheren Kontext (HTTPS) voraus.

Siehe auch

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