MediaSession.setCameraActive() — Methode · JavaScript-Referenz

Signatur

MediaSession.prototype.setCameraActive(active)

Beschreibung

Mit navigator.mediaSession.setCameraActive() meldet eine Webanwendung, meist eine Videokonferenz- oder Streaming-App, dem Browser (Nutzeragenten) den aktuellen Kamerastatus. Der Browser kann diese Information nutzen, um Bedienelemente wie eine Kamera-Umschalttaste im Bild-im-Bild-Fenster, in der Medienbenachrichtigung oder in anderen Systemoberflächen richtig darzustellen (Kamera an oder aus).

Die Methode schaltet die Kamera nicht selbst ein oder aus. Sie gibt nur einen Status weiter. Das eigentliche Stummschalten übernimmt die Anwendung, z. B. über MediaStreamTrack.enabled oder MediaStreamTrack.stop(). Üblicherweise kombiniert man setCameraActive() mit einem Aktions-Handler für "togglecamera", den man über navigator.mediaSession.setActionHandler() registriert: Klickt der Nutzer auf die Browser-Schaltfläche, ändert der Handler den Track-Zustand und meldet danach den neuen Status mit setCameraActive() zurück.

Das Gegenstück für das Mikrofon ist setMicrophoneActive(). Zusammen mit der Aktion "hangup" lassen sich damit vollständige Anrufsteuerungen in Browser-Oberflächen einbinden.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. Die Methode gibt nur den Status an den Browser weiter.

Beispiele

Kamerastatus melden (mit Feature-Erkennung)

const reportCamera = (isOn) => {
  if ('mediaSession' in navigator && 'setCameraActive' in navigator.mediaSession) {
    navigator.mediaSession.setCameraActive(isOn);
    console.log(`Kamerastatus gemeldet: ${isOn ? 'an' : 'aus'}`);
  } else {
    console.log('setCameraActive() wird nicht unterstützt');
  }
};

reportCamera(true);

Kamerastatus gemeldet: an

„togglecamera“-Aktion in einer Videokonferenz

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

navigator.mediaSession.setCameraActive(cameraActive);

try {
  navigator.mediaSession.setActionHandler('togglecamera', () => {
    cameraActive = !cameraActive;
    videoTrack.enabled = cameraActive;              // eigentliches Stummschalten
    navigator.mediaSession.setCameraActive(cameraActive); // Browser-UI aktualisieren
    console.log('Kamera:', cameraActive ? 'an' : 'aus');
  });
} catch (err) {
  console.warn('Aktion "togglecamera" nicht unterstützt:', err.name);
}

Kamera: aus // nach Klick auf die Kamera-Taste im Browser

Kamera und Mikrofon gemeinsam synchronisieren

const syncCallState = ({ camera, mic }) => {
  const ms = navigator.mediaSession;
  if (!ms?.setCameraActive || !ms?.setMicrophoneActive) return false;
  ms.setCameraActive(camera);
  ms.setMicrophoneActive(mic);
  return true;
};

// z. B. nach Klick auf einen eigenen Button in der Seite
document.querySelector('#video-off')?.addEventListener('click', () => {
  syncCallState({ camera: false, mic: true });
});

// Wichtig · Fallstricke

Nur ein Status-Hinweis: Die Methode steuert keine Hardware. Wer nur setCameraActive(false) aufruft, sendet weiterhin Video. Den Track also immer selbst über enabled oder stop() anpassen.
Synchron halten: Ändert sich der Kamerastatus über die eigene Oberfläche der Seite, muss setCameraActive() ebenfalls aufgerufen werden. Sonst zeigt die Browser-Oberfläche einen falschen Zustand an.
Kompatibilität: Die Methode ist experimentell und bisher im Wesentlichen nur in Chromium-Browsern verfügbar. Firefox und Safari unterstützen sie nicht (Stand der Recherche). Deshalb immer per Feature-Erkennung prüfen ('setCameraActive' in navigator.mediaSession). setActionHandler('togglecamera', …) kann in nicht unterstützenden Browsern einen TypeError werfen, daher in try/catch einschließen.
Die zugehörigen Bedienelemente erscheinen meist nur in bestimmten Situationen, z. B. im Bild-im-Bild-Fenster, und nur bei aktiver Mediensitzung.
Die Media-Session-API steht nur in sicheren Kontexten (HTTPS) sicher zur Verfügung.

Siehe auch

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