BrowserCaptureMediaStreamTrack.cropTo() — Methode · JavaScript-Referenz

Signatur

BrowserCaptureMediaStreamTrack.prototype.cropTo(cropTarget)

Beschreibung

cropTo() gehört zur Region Capture API. Nimmt eine Seite sich selbst per navigator.mediaDevices.getDisplayMedia() auf (Selbstaufnahme des aktuellen Tabs), liefert die Videospur normalerweise den gesamten sichtbaren Tab-Inhalt. Mit cropTo() lässt sich dieses Bild auf die Fläche eines einzelnen Elements beschränken – etwa auf eine Präsentation, ein Canvas oder ein eingebettetes <iframe>. Kopfzeile, Chat oder Steuerelemente der Web-App bleiben so aus dem geteilten Bild heraus.

Als Argument erwartet die Methode ein CropTarget, kein Element. Dieses Objekt erzeugt man vorher mit await CropTarget.fromElement(element). Ein CropTarget ist serialisierbar und lässt sich per postMessage() an andere Dokumente weitergeben. So kann zum Beispiel ein eingebettetes Iframe festlegen, welcher Bereich aufgenommen wird, während die Hauptseite die Aufnahme steuert.

Der Zuschnitt folgt dem Element live: Wenn es sich verschiebt, seine Größe ändert oder gescrollt wird, passt sich der Bildausschnitt automatisch an. Inhalte, die das Element überdecken (z. B. Pop-ups oder Overlays), werden trotzdem mit aufgenommen, denn es wird der gerenderte Bildbereich ausgeschnitten, nicht das Element für sich allein. Wer nur das Element selbst ohne überdeckende Inhalte aufnehmen will, braucht restrictTo() (Element Capture).

Übergibt man null oder undefined, wird ein vorhandener Zuschnitt wieder aufgehoben und die Spur zeigt erneut den ganzen Tab. Das zurückgegebene Promise wird erfüllt, sobald der neue Zuschnitt greift. Alle Frames, die danach geliefert werden, sind also bereits zugeschnitten.

Parameter

Name	Typ	Default	Beschreibung
$cropTarget Pflicht	CropTarget \| null \| undefined		Ein mit `CropTarget.fromElement()` erzeugtes Ziel, auf dessen Fläche das Video zugeschnitten wird. Mit `null` bzw. `undefined` wird der Zuschnitt aufgehoben.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das ohne Wert erfüllt wird, sobald der Zuschnitt aktiv ist. Es wird mit einer DOMException abgelehnt, wenn die Spur keine Selbstaufnahme-Videospur ist, bereits beendet wurde (readyState === "ended") oder das CropTarget ungültig ist.

Beispiele

Eigenen Tab aufnehmen und auf ein Element zuschneiden

const startRegionCapture = async () => {
  // Aktuellen Tab bevorzugt zur Auswahl anbieten
  const stream = await navigator.mediaDevices.getDisplayMedia({
    video: true,
    preferCurrentTab: true
  });
  const [track] = stream.getVideoTracks();

  const area = document.querySelector('#presentation');
  const cropTarget = await CropTarget.fromElement(area);

  await track.cropTo(cropTarget);
  console.log('Zuschnitt aktiv');

  document.querySelector('video#preview').srcObject = stream;
};

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

Zuschnitt aktiv

Feature-Erkennung und Zuschnitt wieder aufheben

const supportsRegionCapture = 'CropTarget' in window &&
  typeof CropTarget.fromElement === 'function';

const toggleCrop = async (track, element, enabled) => {
  if (!supportsRegionCapture) {
    console.warn('Region Capture wird nicht unterstützt');
    return;
  }
  try {
    const target = enabled ? await CropTarget.fromElement(element) : null;
    await track.cropTo(target);
    console.log(enabled ? 'Zugeschnitten' : 'Ganzer Tab sichtbar');
  } catch (err) {
    // z. B. wenn der Nutzer einen anderen Tab/Bildschirm gewählt hat
    console.error(`${err.name}: ${err.message}`);
  }
};

Zugeschnitten Ganzer Tab sichtbar

CropTarget aus einem Iframe an die Hauptseite senden

// Im Iframe (gleicher Tab):
const sendTarget = async () => {
  const canvas = document.querySelector('canvas');
  const cropTarget = await CropTarget.fromElement(canvas);
  window.parent.postMessage({ type: 'crop-target', cropTarget }, 'https://app.example.com');
};
sendTarget();

// In der Hauptseite:
let videoTrack; // zuvor per getDisplayMedia() ermittelt
window.addEventListener('message', async (event) => {
  if (event.origin !== 'https://widget.example.com') return;
  if (event.data?.type !== 'crop-target') return;
  await videoTrack.cropTo(event.data.cropTarget);
  console.log('Auf Iframe-Canvas zugeschnitten');
});

Auf Iframe-Canvas zugeschnitten

// Wichtig · Fallstricke

Kompatibilität: Nur in Chromium-Browsern auf dem Desktop (ab Version 104). Firefox und Safari unterstützen es nicht. Vorher per Feature-Erkennung prüfen ('CropTarget' in window) und eine Ausweichlösung ohne Zuschnitt vorsehen.
Nur Selbstaufnahme: Das funktioniert nur, wenn der Nutzer im Auswahldialog den aktuellen Tab gewählt hat. Bei einem fremden Tab, einem Fenster oder dem ganzen Bildschirm wird das Promise abgelehnt. Mit preferCurrentTab: true lässt sich die passende Wahl nahelegen, erzwingen lässt sie sich nicht.
Kein Element, sondern CropTarget: Wer track.cropTo(element) direkt aufruft, bekommt einen Fehler. Immer zuerst await CropTarget.fromElement(element) aufrufen.
Sichtbarkeit: Ist das Ziel-Element nicht gerendert (z. B. display: none oder aus dem DOM entfernt), liefert die Spur keine neuen Frames mehr. Ist es nur teilweise im sichtbaren Bereich, wird auch nur der sichtbare Teil aufgenommen.
Überdeckende Inhalte: Alles, was über dem Element liegt (Tooltips, Modals, Benachrichtigungen), ist im Bild zu sehen. Vertrauliche Inhalte also nicht über dem Zielbereich einblenden – oder restrictTo() verwenden.
Kopierte Spuren: Nach track.clone() können Original und Kopie unabhängig voneinander zugeschnitten werden.
Die Methode ist nur in einem sicheren Kontext (HTTPS) verfügbar, genau wie getDisplayMedia().

Siehe auch

BrowserCaptureMediaStreamTrack.clone() BrowserCaptureMediaStreamTrack.restrictTo() CanvasCaptureMediaStreamTrack.requestFrame() MediaStreamTrack.clone() MediaStreamTrack.stop()