new CaptureController() — Methode · JavaScript-Referenz

Signatur

new CaptureController()

Beschreibung

Der Konstruktor new CaptureController() erzeugt ein Steuerobjekt für eine einzelne Bildschirmaufnahme über die Screen Capture API. Das Objekt wird in der Option controller an navigator.mediaDevices.getDisplayMedia() übergeben und ist danach fest mit genau dieser Aufnahme verbunden.

Wichtigster Einsatzzweck ist setFocusBehavior(). Damit legst du fest, ob nach dem Start der Aufnahme der aufgenommene Tab bzw. das Fenster in den Vordergrund kommt oder ob der Fokus bei deiner Anwendung bleibt. Für Videokonferenz-Apps ist das nützlich: Die Nutzerin teilt ein Fenster und kann trotzdem sofort in der App weiterarbeiten.

In neueren Chromium-Versionen lässt sich die aufgenommene Oberfläche über den Controller auch fernsteuern (Captured Surface Control). Dazu gehören forwardWheel(), increaseZoomLevel(), decreaseZoomLevel(), resetZoomLevel(), die Eigenschaft zoomLevel und das Ereignis zoomlevelchange. Diese Funktionen brauchen eine eigene Berechtigung.

Rückgabewert

Typ

CaptureController

Beschreibung

Ein neues, noch nicht gebundenes CaptureController-Objekt. Es wird erst durch die Übergabe an getDisplayMedia() mit einer Aufnahme verknüpft.

Beispiele

Controller erzeugen und an getDisplayMedia übergeben

const controller = new CaptureController();

const startCapture = async () => {
  const stream = await navigator.mediaDevices.getDisplayMedia({
    video: true,
    controller
  });
  document.querySelector('video').srcObject = stream;
  return stream;
};

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

Fokus nach dem Teilen in der eigenen App behalten

const shareWithoutFocusChange = async () => {
  const controller = new CaptureController();
  const stream = await navigator.mediaDevices.getDisplayMedia({
    video: true,
    controller
  });

  const [track] = stream.getVideoTracks();
  const { displaySurface } = track.getSettings();

  // setFocusBehavior ist nur bei Tabs und Fenstern erlaubt
  if (displaySurface === 'browser' || displaySurface === 'window') {
    controller.setFocusBehavior('focus-capturing-application');
  }
  console.log('Geteilte Oberfläche:', displaySurface);
  return stream;
};

Geteilte Oberfläche: window

Feature-Erkennung mit Fallback

const captureScreen = async () => {
  const options = { video: true };

  if ('CaptureController' in window) {
    const controller = new CaptureController();
    // Vor dem Start setzen: gilt direkt beim Beginn der Aufnahme
    controller.setFocusBehavior('no-focus-change');
    options.controller = controller;
  } else {
    console.log('CaptureController nicht unterstützt – Standardverhalten');
  }

  return navigator.mediaDevices.getDisplayMedia(options);
};

CaptureController nicht unterstützt – Standardverhalten (z. B. in Firefox)

// Wichtig · Fallstricke

Nur einmal verwendbar: Ein Controller gehört genau zu einem Aufruf von getDisplayMedia(). Übergibst du ihn ein zweites Mal, wird das Promise mit einem InvalidStateError abgelehnt. Erzeuge daher pro Aufnahme einen neuen Controller.
Enges Zeitfenster für setFocusBehavior(): Rufe die Methode vor der Aufnahme oder unmittelbar nach dem Auflösen des Promises auf. Laut Spezifikation darfst du sie nur einmal aufrufen. Ein Aufruf nach etwa einer Sekunde oder ein zweiter Aufruf wirft einen InvalidStateError.
Nicht bei ganzen Bildschirmen: Bei displaySurface: 'monitor' ist ein Fokuswechsel sinnlos. Dann wirft setFocusBehavior() einen Fehler. Prüfe vorher track.getSettings().displaySurface.
Browser-Unterstützung: Nur Chromium-Browser (Chrome, Edge, Opera) ab Version 109. Firefox und Safari unterstützen die API nicht. Prüfe deshalb immer mit 'CaptureController' in window. Die Funktionen für Captured Surface Control (Scrollen, Zoom) sind neuer und brauchen die Berechtigung captured-surface-control.
Die API funktioniert nur in sicheren Kontexten (HTTPS). getDisplayMedia() muss durch eine Nutzeraktion ausgelöst werden, zum Beispiel einen Klick.

Siehe auch

CaptureController CaptureController.setFocusBehavior() MediaDevices.getDisplayMedia() MediaStream MediaStreamTrack.getSettings() new AbortController() new CountQueuingStrategy()