BrowserCaptureMediaStreamTrack — Schnittstelle · JavaScript-Referenz

Signatur

interface BrowserCaptureMediaStreamTrack extends MediaStreamTrack

Beschreibung

BrowserCaptureMediaStreamTrack gehört zur Screen Capture API und steht für eine einzelne Videospur, die aus einem Browser-Tab aufgenommen wird. Du bekommst eine solche Spur, wenn du navigator.mediaDevices.getDisplayMedia() aufrufst und der Nutzer einen Tab zur Freigabe auswählt. Meist ist das der aktuelle Tab, wenn du preferCurrentTab: true übergibst. Das Interface erbt alle Eigenschaften, Methoden und Ereignisse von MediaStreamTrack.

Zusätzlich gibt es zwei Methoden, mit denen du den aufgenommenen Inhalt einschränken kannst:

cropTo(cropTarget) (Region Capture): Schneidet das Video auf den sichtbaren Rechteck-Bereich eines Elements zu. Was dieses Element überdeckt, zum Beispiel Pop-ups oder Overlays, ist weiterhin zu sehen.
restrictTo(restrictionTarget) (Element Capture): Nimmt nur das Element selbst und seine Nachkommen auf. Überlagernde oder dahinterliegende Inhalte werden nicht mit aufgenommen.
clone(): Gibt eine neue BrowserCaptureMediaStreamTrack-Spur zurück. Zuschnitt und Einschränkung wirken nur auf die Spur, für die du sie aufrufst.

Typische Einsatzfälle: In Videokonferenz- oder Präsentations-Web-Apps soll nur ein Bereich des eigenen Tabs geteilt werden, etwa eine Folie, ein Editor oder ein Video. Andere Bereiche wie Chat, Teilnehmerliste oder persönliche Daten sollen nicht sichtbar sein. Übergibst du null, wird der Zuschnitt bzw. die Einschränkung wieder aufgehoben.

Parameter

Name	Typ	Default	Beschreibung
$cropTarget Pflicht	CropTarget \| null		Parameter von `cropTo()`: ein Ziel, das du mit `await CropTarget.fromElement(element)` erzeugst. Mit `null` hebst du den Zuschnitt auf.
$restrictionTarget Pflicht	RestrictionTarget \| null		Parameter von `restrictTo()`: ein Ziel, das du mit `await RestrictionTarget.fromElement(element)` erzeugst. Mit `null` hebst du die Einschränkung auf.

Beispiele

Eigenen Tab aufnehmen und auf ein Element zuschneiden (Region Capture)

const startCroppedCapture = async () => {
  const stage = document.querySelector('#praesentation');
  // CropTarget vor der Aufnahme erzeugen
  const cropTarget = await CropTarget.fromElement(stage);

  const stream = await navigator.mediaDevices.getDisplayMedia({
    video: true,
    preferCurrentTab: true
  });
  const [track] = stream.getVideoTracks();

  if (!('cropTo' in track)) {
    console.warn('Region Capture wird nicht unterstützt');
    return stream;
  }

  await track.cropTo(cropTarget);
  console.log('Aufnahme auf #praesentation zugeschnitten');
  document.querySelector('video#vorschau').srcObject = stream;
  return stream;
};

document.querySelector('#teilen').addEventListener('click', startCroppedCapture);

Aufnahme auf #praesentation zugeschnitten

Nur ein Element aufnehmen – ohne überlagernde Inhalte (Element Capture)

const captureElementOnly = async () => {
  const editor = document.querySelector('#editor');
  const stream = await navigator.mediaDevices.getDisplayMedia({
    video: true,
    preferCurrentTab: true
  });
  const [track] = stream.getVideoTracks();

  if ('RestrictionTarget' in window && 'restrictTo' in track) {
    const target = await RestrictionTarget.fromElement(editor);
    await track.restrictTo(target);
    console.log('Nur #editor wird übertragen');
  }
  return stream;
};

captureElementOnly().catch((err) => console.error(err.name, err.message));

Nur #editor wird übertragen

Zuschnitt aufheben und Spur beenden

let captureTrack;

const toggleCrop = async (element) => {
  if (element) {
    const target = await CropTarget.fromElement(element);
    await captureTrack.cropTo(target);
    console.log('Zuschnitt aktiv');
  } else {
    await captureTrack.cropTo(null); // ganzer Tab wieder sichtbar
    console.log('Zuschnitt aufgehoben');
  }
};

const init = async () => {
  const stream = await navigator.mediaDevices.getDisplayMedia({ video: true, preferCurrentTab: true });
  [captureTrack] = stream.getVideoTracks();
  captureTrack.addEventListener('ended', () => console.log('Freigabe beendet'));
  await toggleCrop(document.querySelector('main'));
  await toggleCrop(null);
  captureTrack.stop();
};

init();

Zuschnitt aktiv Zuschnitt aufgehoben

// Wichtig · Fallstricke

Browser-Unterstützung: Das Interface gibt es nur in Chromium-Browsern wie Chrome, Edge und Opera, und nur auf Desktop-Geräten. cropTo() ist ab Version 104 verfügbar, restrictTo() ab Version 132. Firefox und Safari unterstützen es nicht. Prüfe die Unterstützung vor der Nutzung, zum Beispiel mit 'cropTo' in track oder 'CropTarget' in window.
Nur für den eigenen Tab: Beide Methoden funktionieren nur, wenn der Tab aufgenommen wird, in dem sich das Zielelement befindet. Bei Aufnahmen eines Fensters oder des ganzen Bildschirms wird das Promise abgelehnt.
Nur Videospuren: Die Methoden gibt es nur für Videospuren. Du erhältst eine BrowserCaptureMediaStreamTrack nur, wenn der Nutzer einen Tab auswählt.
Ziel vorab erzeugen: Erzeuge CropTarget und RestrictionTarget mit fromElement(), das asynchron arbeitet. Ziele lassen sich per postMessage an andere Dokumente weitergeben, zum Beispiel an ein iframe. Beim Zusammenführen von Aufnahme und Ziel gilt ein Ursprung als Sicherheitsgrenze.
Unterschied zwischen den Methoden: cropTo() schneidet nur ein Rechteck aus, Elemente darüber bleiben also sichtbar. restrictTo() nimmt tatsächlich nur das Element auf. Für den Datenschutz ist restrictTo() deshalb meist die bessere Wahl.
Einschränkungen bei restrictTo(): Das Zielelement muss einen eigenen Stapelkontext (Stacking Context) bilden, zum Beispiel über isolation: isolate. Ist das Element nicht sichtbar, liefert die Spur keine Frames.
Einschränkungen bei cropTo(): Ist das Element nicht sichtbar oder außerhalb des Viewports, liefert die Spur ebenfalls keine Frames.
Datenschutz: Die Aufnahme verlangt immer eine Nutzeraktion und eine Freigabe über den Browser-Dialog. Beende die Spur mit stop(), wenn du sie nicht mehr brauchst.

Siehe auch

CanvasCaptureMediaStreamTrack MediaStreamTrack MediaStream MediaStreamEvent MediaStreamTrackEvent