BrowserCaptureMediaStreamTrack.clone() — Methode · JavaScript-Referenz

Signatur

BrowserCaptureMediaStreamTrack.prototype.clone()

Beschreibung

Die Methode clone() überschreibt MediaStreamTrack.prototype.clone(). Sie gibt einen neuen BrowserCaptureMediaStreamTrack zurück, der dieselbe Aufnahmequelle nutzt, also denselben aufgenommenen Tab. Der Klon bekommt eine neue id. Er übernimmt die Einschränkungen (Constraints) sowie die Werte von enabled und muted des Originals. Weil der Rückgabewert wieder ein BrowserCaptureMediaStreamTrack ist, stehen auf dem Klon auch cropTo() (Region Capture) und restrictTo() (Element Capture) zur Verfügung.

Das ist praktisch, wenn Sie denselben Tab-Mitschnitt auf verschiedene Arten verwenden wollen. Beispiel: Die Originalspur zeigt den ganzen Tab in einer lokalen Vorschau. Der Klon wird mit cropTo() auf einen bestimmten Bereich zugeschnitten und per WebRTC an andere Teilnehmer geschickt. Zuschneiden, Einschränken, applyConstraints() und stop() wirken immer nur auf die Spur, auf der Sie sie aufrufen.

Einen BrowserCaptureMediaStreamTrack erhalten Sie nur über navigator.mediaDevices.getDisplayMedia(), und nur wenn der Nutzer einen Browser-Tab zur Aufnahme auswählt. Bei Fenster- oder Bildschirmaufnahmen bekommen Sie einen normalen MediaStreamTrack.

Rückgabewert

Typ

BrowserCaptureMediaStreamTrack

Beschreibung

Eine neue, unabhängige Spur mit eigener id, die dieselbe Tab-Aufnahmequelle nutzt wie das Original.

Beispiele

Tab aufnehmen und Spur klonen

const startCapture = async () => {
  const stream = await navigator.mediaDevices.getDisplayMedia({
    video: true,
    preferCurrentTab: true // nur Chromium
  });
  const [track] = stream.getVideoTracks();

  if (typeof BrowserCaptureMediaStreamTrack === 'undefined' ||
      !(track instanceof BrowserCaptureMediaStreamTrack)) {
    console.log('Kein Tab-Mitschnitt oder Browser ohne Unterstützung');
    return;
  }

  const copy = track.clone();
  console.log(copy instanceof BrowserCaptureMediaStreamTrack);
  console.log(copy.id !== track.id);
  console.log(copy.kind);
};

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

true true video

Original als Vollbild-Vorschau, Klon zugeschnitten (Region Capture)

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

  // Klon für den zugeschnittenen Bereich
  const croppedTrack = fullTrack.clone();
  const area = document.querySelector('#presentation');
  const cropTarget = await CropTarget.fromElement(area);
  await croppedTrack.cropTo(cropTarget);

  // Lokale Vorschau: ganzer Tab
  document.querySelector('#preview').srcObject = new MediaStream([fullTrack]);
  // Nur der zugeschnittene Bereich wird geteilt
  document.querySelector('#shared').srcObject = new MediaStream([croppedTrack]);

  return { fullTrack, croppedTrack };
};

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

Klone unabhängig voneinander stoppen

const demo = async () => {
  const stream = await navigator.mediaDevices.getDisplayMedia({ video: true });
  const [track] = stream.getVideoTracks();
  const copy = track.clone();

  copy.stop();
  console.log(copy.readyState);  // Klon beendet
  console.log(track.readyState); // Original läuft weiter

  // Aufnahme erst vollständig beenden, wenn alle Spuren gestoppt sind
  track.stop();
};

document.querySelector('#demo').addEventListener('click', demo);

ended live

// Wichtig · Fallstricke

Browser-Unterstützung: Das Interface gibt es nur in Chromium-basierten Browsern (ab Version 104), nicht in Firefox und Safari. Prüfen Sie vorher mit typeof BrowserCaptureMediaStreamTrack !== 'undefined' und instanceof, ob es verfügbar ist.
Nur bei Tab-Aufnahmen: Wählt der Nutzer ein Fenster oder den ganzen Bildschirm, gibt getDisplayMedia() einen normalen MediaStreamTrack zurück. Dann gibt es weder cropTo() noch restrictTo().
Zustand beim Zuschneiden: Verlassen Sie sich nicht darauf, dass der Klon einen vorhandenen Zuschnitt oder eine Einschränkung vom Original übernimmt. Rufen Sie cropTo() bzw. restrictTo() auf dem Klon ausdrücklich auf. Spätere Aufrufe auf einer Spur verändern die andere Spur nicht.
Ressourcen: Die Tab-Aufnahme (und damit die Aufnahme-Anzeige im Browser) läuft so lange, bis alle Klone gestoppt sind. Rufen Sie deshalb für jeden Klon stop() auf, damit keine Aufnahme unbemerkt weiterläuft.
Sicherer Kontext: getDisplayMedia() funktioniert nur über HTTPS und nur nach einer Nutzeraktion, zum Beispiel einem Klick.

Siehe auch

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