chrome.tabCapture

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. Dies ä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. Dies ähnelt dem Verhalten der Funktion getDisplayMedia(), wenn das Flag suppressLocalAudioPlayback auf „true“ gesetzt ist.

Wenn Sie weiterhin Audio für den Nutzer abspielen möchten, verwenden Sie Folgendes:

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

Dadurch wird ein neues AudioContext erstellt und die Audioausgabe des Tabs MediaStream wird an das Standardziel weitergeleitet.

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 wird, in einem Offscreen-Dokument verwendet werden kann.

Vor Chrome 116 war die Stream-ID, wenn kein consumerTabId angegeben wurde, 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 Audioaufzeichnung 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 Aufnahmestatus 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 Consumber-Tabs ü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. Nur Tabs, für die der Erweiterung die Berechtigung activeTab erteilt wurde, können als Zieltab verwendet werden.

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 Aufnahme 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 eine Aufzeichnung angefordert wurde oder die aufgezeichnet werden, d.h. status != stopped und status != error. So können Erweiterungen den Nutzer darüber informieren, dass bereits 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

    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

    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,
)

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

Parameter