chrome.tabCapture

refresh date: 2026-09-25 robots: noindex

Beschreibung

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

Berechtigungen

tabCapture

Übersicht

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

Systemaudio beibehalten

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

Wenn du die Audiowiedergabe für den Nutzer fortsetzen möchtest, verwende Folgendes:

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

Dadurch wird ein neues AudioContext erstellt und die Audioausgabe des MediaStream des Tabs mit dem Standardziel verbunden.

Stream-IDs

Wenn Sie chrome.tabCapture.getMediaStreamId aufrufen, wird eine Stream-ID zurückgegeben. Wenn Sie später über die ID auf einen MediaStream zugreifen möchten, verwenden Sie Folgendes:

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

Nutzungsbeschränkungen

Nach dem Aufruf von getMediaStreamId() gelten Einschränkungen für die Verwendung der zurückgegebenen Stream-ID:

  • 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 diese Richtlinie nicht konfiguriert ist, kann die ID ab Chrome 116 in jedem Frame mit demselben Sicherheitsursprung im selben Renderprozess wie der Aufrufer verwendet werden. Das bedeutet, dass eine in einem Service Worker abgerufene Stream-ID in einem Offscreen-Dokument verwendet werden kann.

Vor Chrome 116 wurde die Stream-ID, wenn keine consumerTabId angegeben war, auf den Sicherheitsursprung, den Renderprozess und den Renderframe 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 für eine Reihe gängiger Anwendungsfälle verwenden.

Typen

CaptureInfo

Attribute

  • Vollbild

    boolean

    Gibt an, ob sich ein Element im aufgenommenen Tab im Vollbildmodus befindet.

  • Der neue Aufnahmestatus des Tabs.

  • tabId

    Zahl

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

CaptureOptions

Attribute

GetMediaStreamOptions

Chrome 71 oder höher

Attribute

  • consumerTabId

    number optional

    Optionale Tab-ID des Tabs, der später getUserMedia() aufruft, 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 im angegebenen Tab verwendet werden, deren Sicherheitsursprung mit dem Ursprung des Consumer-Tabs übereinstimmt. Der Ursprung des Tabs muss ein sicherer Ursprung sein, z.B. HTTPS.

  • targetTabId

    number optional

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

MediaStreamConstraint

Attribute

  • obligatorisch

    Objekt

  • optional

    Objekt 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 Aufnahme kann nur auf dem aktuell aktiven Tab gestartet werden, nachdem die Erweiterung aufgerufen wurde, ähnlich wie bei activeTab. Die Aufnahme wird bei der Seitennavigation innerhalb des Tabs beibehalten und beendet, wenn der Tab geschlossen oder der Mediastream von der Erweiterung geschlossen wird.

Parameter

  • Optionen

    CaptureOptions

    Konfiguriert den zurückgegebenen Mediastream.

  • 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 der Tabs zurück, die eine Aufnahme angefordert haben oder aufgenommen werden, d.h. Status != „Beendet“ und Status != „Fehler“. So können Erweiterungen den Nutzer darüber informieren, dass bereits ein Tab aufgenommen wird und eine neue Tabaufnahme deshalb nicht möglich ist (oder redundante Anfragen für denselben Tab verhindert werden).

Parameter

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    (result: CaptureInfo[]) => void

Ausgabe

  • Promise<CaptureInfo[]>

    Chrome 116 oder höher

    Gibt ein Promise zurück, das mit CaptureInfo[] für aufgenommene 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, um den Zieltab zu erfassen. Ähnlich wie die Methode „chrome.tabCapture.capture()“, gibt aber eine Mediastream-ID anstelle eines Mediastreams an den Consumer-Tab zurück.

Parameter

  • Optionen

    GetMediaStreamOptions optional

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    (streamId: string) => void

    • streamId

      String

Ausgabe

  • Promise<string>

    Chrome 116 oder höher

    Gibt ein Promise zurück, das mit dem Ergebnis aufgelöst wird. Wenn der Vorgang erfolgreich ist, wird ein nicht transparenter String zurückgegeben, der an die getUserMedia() API übergeben werden kann, um einen Medienstream zu generieren, der dem Zieltab entspricht. Der erstellte streamId kann nur einmal verwendet werden und läuft nach einigen Sekunden ab, wenn er 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 Aufnahmestatus eines Tabs ändert. So können Autoren von Erweiterungen den Aufnahmestatus von Tabs im Blick behalten, um UI-Elemente wie Seitenaktionen synchron zu halten.

Parameter