CaptureController — Schnittstelle · JavaScript-Referenz

Signatur

interface CaptureController extends EventTarget

Beschreibung

CaptureController ist ein Steuerobjekt für eine Bildschirmaufnahme. Du erzeugst es mit new CaptureController() und übergibst es in der Option controller an navigator.mediaDevices.getDisplayMedia(). Danach gehört der Controller fest zu dieser einen Aufnahmesitzung.

Die wichtigste Methode ist setFocusBehavior(focusBehavior). Normalerweise wechselt der Browser zum ausgewählten Tab oder Fenster, sobald die Aufnahme startet. Für Videokonferenz-Apps ist das oft unpraktisch: Die Nutzerin soll in der eigenen App bleiben und dort die Vorschau sehen. Mit "no-focus-change" bleibt der Fokus deshalb bei der aufnehmenden Seite. "focus-captured-surface" ist das Standardverhalten und wechselt zur erfassten Oberfläche.

Neuere Chromium-Versionen ergänzen die Schnittstelle um die Captured Surface Control API. Damit kann die aufnehmende Seite Scroll-Ereignisse an den erfassten Tab weiterleiten und dessen Zoom steuern:

forwardWheel(element): leitet Mausrad-Ereignisse auf einem Element (z. B. dem Vorschau-<video>) an den erfassten Tab weiter.
getSupportedZoomLevels(), increaseZoomLevel(), decreaseZoomLevel(), resetZoomLevel(): fragen die Zoomstufe des erfassten Tabs ab oder ändern sie.
zoomLevel: aktuelle Zoomstufe in Prozent (nur lesbar).
Ereignis capturedzoomlevelchange bzw. oncapturedzoomlevelchange: wird ausgelöst, wenn sich die Zoomstufe ändert.

Parameter

Name	Typ	Default	Beschreibung
$focusBehavior Pflicht	"focus-captured-surface" \| "no-focus-change"		Parameter von `setFocusBehavior()`. `"focus-captured-surface"` bringt den erfassten Tab bzw. das erfasste Fenster in den Vordergrund (Standard). `"no-focus-change"` lässt den Fokus bei der aufnehmenden Seite.
$element Pflicht	HTMLElement		Parameter von `forwardWheel()`. Element, dessen `wheel`-Ereignisse an den erfassten Tab weitergeleitet werden. Mit `null` beendest du die Weiterleitung.

Rückgabewert

Typ

CaptureController

Beschreibung

new CaptureController() liefert eine neue, noch ungebundene Instanz. setFocusBehavior() gibt undefined zurück. forwardWheel() und die Zoom-Methoden liefern ein Promise<void>. getSupportedZoomLevels() liefert ein number[].

Beispiele

Tab teilen, ohne den Fokus zu verlieren

const startShare = async () => {
  const controller = new CaptureController();

  const stream = await navigator.mediaDevices.getDisplayMedia({
    video: true,
    controller,
  });

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

  // Fokussteuerung gibt es nur bei Tabs und Fenstern
  if (displaySurface === 'browser' || displaySurface === 'window') {
    controller.setFocusBehavior('no-focus-change');
  }

  document.querySelector('#preview').srcObject = stream;
  console.log('Erfasst:', displaySurface);
};

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

Erfasst: browser

Fokus schon vor der Auswahl festlegen

const controller = new CaptureController();

// Darf vor dem Erfüllen des Promise aufgerufen werden
controller.setFocusBehavior('no-focus-change');

try {
  const stream = await navigator.mediaDevices.getDisplayMedia({
    video: { displaySurface: 'browser' },
    controller,
  });
  console.log('Aufnahme läuft:', stream.active);
} catch (err) {
  console.error('Abgebrochen oder verweigert:', err.name);
}

Aufnahme läuft: true

Funktion erkennen und Zoom des geteilten Tabs steuern

const supportsFocus = 'CaptureController' in window &&
  'setFocusBehavior' in CaptureController.prototype;
console.log('Fokussteuerung verfügbar:', supportsFocus);

const controller = new CaptureController();
const stream = await navigator.mediaDevices.getDisplayMedia({ video: true, controller });
const video = document.querySelector('#preview');
video.srcObject = stream;

if ('forwardWheel' in controller) {
  // Muss durch eine Nutzeraktion ausgelöst werden
  document.querySelector('#enable-control').addEventListener('click', async () => {
    await controller.forwardWheel(video);
    console.log('Zoomstufen:', controller.getSupportedZoomLevels());
  });

  document.querySelector('#zoom-in').addEventListener('click', () =>
    controller.increaseZoomLevel());

  controller.addEventListener('capturedzoomlevelchange', () => {
    console.log('Neuer Zoom:', controller.zoomLevel + ' %');
  });
}

Fokussteuerung verfügbar: true Zoomstufen: [25, 33, 50, 67, 75, 80, 90, 100, 110, 125, ...] Neuer Zoom: 110 %

// Wichtig · Fallstricke

Browser-Unterstützung: Nur in Chromium-Browsern (ab Chrome/Edge 109). Firefox und Safari unterstützen die Schnittstelle nicht. Prüfe deshalb vorher mit 'CaptureController' in window. Die Captured-Surface-Control-Methoden (forwardWheel(), Zoom-Methoden) sind neuer, gelten noch als experimentell und können eine Berechtigungsabfrage (captured-surface-control) auslösen.
Zeitfenster: Du musst setFocusBehavior() vor dem Erfüllen des getDisplayMedia()-Promise aufrufen oder direkt danach. Nach etwa einer Sekunde, oder wenn die Aufnahme beendet ist, wirft die Methode einen InvalidStateError.
Nur Tabs und Fenster: Wird ein ganzer Bildschirm erfasst (displaySurface: "monitor"), führt ein Aufruf nach dem Erfüllen des Promise ebenfalls zu einem InvalidStateError.
Einmalige Verwendung: Ein Controller gehört fest zu genau einem getDisplayMedia()-Aufruf. Wird er ein zweites Mal übergeben, wird das Promise mit InvalidStateError abgelehnt. Lege also für jede Aufnahme eine neue Instanz an.
Sichere Umgebung: Wie getDisplayMedia() funktioniert die Schnittstelle nur in sicheren Kontexten (HTTPS) und nach einer Nutzeraktion.
Datenschutz: Gibst du Scroll- und Zoom-Steuerung an den geteilten Tab weiter, kann die aufnehmende Seite dessen Inhalt beeinflussen. Aktiviere das deshalb nur nach einer ausdrücklichen Nutzeraktion.

Siehe auch

AbortController TaskController MediaRecorder AbstractRange AudioDecoder NavigationPrecommitController