chrome.tabCapture

Aktualisierungsdatum: 2026-09-25 robots: noindex

Beschreibung

Verwenden Sie die chrome.tabCapture API, um mit Tab-Media-Streams zu interagieren.

Berechtigungen

tabCapture

Übersicht

Mit der chrome.tabCapture API können Sie auf einen MediaStream zugreifen, der Video und Audio des aktuellen Tabs enthält. Sie kann nur aufgerufen werden, nachdem der Nutzer eine Erweiterung aufgerufen hat, z. B. durch Klicken auf die Aktionsschaltfläche der Erweiterung. Das ähnelt dem Verhalten der Berechtigung activeTab.

Systemaudio beibehalten

Wenn ein MediaStream für einen Tab abgerufen wird, wird Audio auf diesem Tab nicht mehr für den Nutzer wiedergegeben. Das ähnelt dem Verhalten der Funktion getDisplayMedia(), wenn das Flag suppressLocalAudioPlayback auf „true“ gesetzt ist.

Verwenden Sie Folgendes, um die Audioausgabe für den Nutzer fortzusetzen:

const output = new AudioContext();
const source = output.createMediaStreamSource(stream);
source.connect(output.destination);

Dadurch wird ein neuer AudioContext erstellt und das Audio des MediaStream des Tabs wird mit dem Standardziel verbunden.

Stream-IDs

Beim Aufrufen von chrome.tabCapture.getMediaStreamId wird eine Stream-ID zurückgegeben. So greifen Sie später über die ID auf einen MediaStream zu:

navigator.mediaDevices.getUserMedia({
  audio: {
    mandatory: {
      chromeMediaSource: "tab",
      chromeMediaSourceId: id,
    },
  },
  video: {
    mandatory: {
      chromeMediaSource: "tab",
      chromeMediaSourceId: id,
    },
  },
});

Nutzungsbeschränkungen

Nach dem Aufrufen von getMediaStreamId() gibt es Einschränkungen, wo die zurückgegebene Stream-ID verwendet werden kann:

  • Wenn consumerTabId angegeben ist, kann die ID von einem getUserMedia()-Aufruf in einem beliebigen Frame auf dem angegebenen Tab mit demselben Sicherheitsursprung verwendet werden.
  • Wenn dies nicht angegeben ist, kann die ID ab Chrome 116 in jedem Frame mit demselben Sicherheitsursprung im selben Renderingprozess wie der Aufrufer verwendet werden. Das bedeutet, dass eine Stream-ID, die in einem Service Worker abgerufen wurde, in einem Offscreen-Dokument verwendet werden kann.

Vor Chrome 116 war die Stream-ID, wenn kein consumerTabId angegeben war, auf den Sicherheitsursprung, den Renderingprozess und den Renderingframe des Aufrufers beschränkt.

Weitere Informationen

Weitere Informationen zur Verwendung der chrome.tabCapture API finden Sie unter Audioaufnahme und Bildschirmaufnahme. Hier wird gezeigt, wie Sie tabCapture und zugehörige APIs verwenden, um eine Reihe gängiger Anwendungsfälle zu lösen.

Typen

CaptureInfo

Attribute

  • Vollbild

    boolean

    Gibt an, ob sich ein Element auf dem erfassten Tab im Vollbildmodus befindet.

  • Der neue Erfassungsstatus des Tabs.

  • tabId

    Zahl

    Die ID des Tabs, dessen Status sich geändert hat.

CaptureOptions

Attribute

GetMediaStreamOptions

Chrome 71 und höher

Attribute

  • consumerTabId

    number optional

    Optionale Tab-ID des Tabs, auf dem später getUserMedia() aufgerufen wird, um den Stream zu nutzen. Wenn nicht angegeben, kann der resultierende Stream nur von der aufrufenden Erweiterung verwendet werden. Der Stream kann nur von Frames auf dem angegebenen Tab verwendet werden, deren Sicherheitsursprung mit dem Ursprung des Consumertabs übereinstimmt. Der Ursprung des Tabs muss ein sicherer Ursprung sein, z.B. HTTPS.

  • targetTabId

    number optional

    Optionale Tab-ID des Tabs, der erfasst werden soll. Wenn nicht angegeben, wird der aktuell aktive Tab ausgewählt. Als Zieltab können nur Tabs verwendet werden, für die der Erweiterung die Berechtigung activeTab erteilt wurde.

MediaStreamConstraint

Attribute

  • obligatorisch

    Objekt

  • optional

    object optional

TabCaptureState

Enum

"pending"

„active“

„stopped“

"error"

Methoden

capture()

Nur im Vordergrund 
chrome.tabCapture.capture(
  options: CaptureOptions,
  callback: function,
): void

Erfasst den sichtbaren Bereich des aktuell aktiven Tabs. Die Aufzeichnung kann nur auf dem aktuell aktiven Tab gestartet werden, nachdem die Erweiterung aufgerufen wurde. Das funktioniert ähnlich wie bei activeTab. Die Aufnahme wird bei Seitenwechseln innerhalb des Tabs fortgesetzt und beendet, wenn der Tab geschlossen wird oder der Media-Stream von der Erweiterung geschlossen wird.

Parameter

  • Optionen

    CaptureOptions

    Konfiguriert den zurückgegebenen Media-Stream.

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    (stream: LocalMediaStream) => void

    • Stream

      LocalMediaStream

getCapturedTabs()

Promise 
chrome.tabCapture.getCapturedTabs(
  callback?: function,
): Promise<CaptureInfo[]>

Gibt eine Liste von Tabs zurück, für die die Aufnahme angefordert wurde oder die gerade aufgenommen werden, d.h. status != stopped und status != error. So können Erweiterungen den Nutzer darüber informieren, dass eine Tab-Aufzeichnung vorhanden ist, die eine neue Tab-Aufzeichnung verhindert (oder redundante Anfragen für denselben Tab verhindern).

Parameter

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (result: CaptureInfo[]) => void

Ausgabe

  • Promise<CaptureInfo[]>

    Chrome 116 und höher

    Gibt ein Promise zurück, das mit CaptureInfo[] für erfasste Tabs aufgelöst wird.

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

getMediaStreamId()

Promise Chrome 71+ 
chrome.tabCapture.getMediaStreamId(
  options?: GetMediaStreamOptions,
  callback?: function,
): Promise<string>

Erstellt eine Stream-ID zum Erfassen des Zieltabs. Ähnlich wie die Methode chrome.tabCapture.capture(), gibt aber eine Media-Stream-ID anstelle eines Media-Streams an den Tab des Nutzers zurück.

Parameter

  • Optionen

    GetMediaStreamOptions optional

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (streamId: string) => void

    • streamId

      String

Ausgabe

  • Promise<string>

    Chrome 116 und höher

    Gibt ein Promise zurück, das mit dem Ergebnis aufgelöst wird. Bei Erfolg ist das Ergebnis ein undurchsichtiger String, der an die getUserMedia() API übergeben werden kann, um einen Media-Stream zu generieren, der dem Zieltab entspricht. Die erstellte streamId kann nur einmal verwendet werden und läuft nach einigen Sekunden ab, wenn sie nicht verwendet wird.

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

Ereignisse

onStatusChanged

chrome.tabCapture.onStatusChanged.addListener(
  callback: function,
)

Ereignis, das ausgelöst wird, wenn sich der Erfassungsstatus eines Tabs ändert. So können Erweiterungsentwickler den Erfassungsstatus von Tabs im Blick behalten, um UI-Elemente wie Seitenaktionen zu synchronisieren.

Parameter