chrome.tabCapture

Beschreibung

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

Berechtigungen

tabCapture

Konzepte und Nutzung

Mit der chrome.tabCapture API können Sie auf ein MediaStream-Objekt mit Video- und Audioinhalt des aktuellen Tabs zugreifen. Sie kann nur aufgerufen werden, nachdem der Nutzer eine Erweiterung aufgerufen hat, z. B. durch Klicken auf die Aktionsschaltfläche der Erweiterung. Dies entspricht dem Verhalten der Berechtigung "activeTab".

Audio des Systems beibehalten

Wenn ein MediaStream für einen Tab abgerufen wird, werden Audioinhalte auf diesem Tab nicht mehr für den Nutzer abgespielt. Dies entspricht dem Verhalten der Funktion getDisplayMedia(), wenn das Flag suppressLocalAudioPlayback auf „true“ festgelegt ist.

So können Sie die Audiowiedergabe für den Nutzer fortsetzen:

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

Dadurch wird ein neues AudioContext erstellt und das Audio des MediaStream-Elements des Tabs 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 ein 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 dafür, wo die zurückgegebene Stream-ID verwendet werden kann:

  • Wenn consumerTabId angegeben ist, kann die ID von einem getUserMedia()-Aufruf in jedem Frame im gegebenen Tab verwendet werden, der dieselbe Sicherheitsherkunft hat.
  • Wenn dies nicht angegeben ist, kann die ID ab Chrome 116 in jedem Frame mit demselben Sicherheitsherkunft im selben Renderingprozess wie der Aufrufer verwendet werden. Das bedeutet, dass eine von einem Service Worker erhaltene Stream-ID in einem nicht sichtbaren Dokument verwendet werden kann.

Wenn vor Chrome 116 kein consumerTabId angegeben wurde, wurde die Stream-ID sowohl auf den Sicherheitsursprung, den Renderingprozess als auch den Rendering-Frame des Aufrufers beschränkt.

Weitere Informationen

Weitere Informationen zur Verwendung der chrome.tabCapture API findest du unter Audio- und Bildschirmaufnahme. Hier wird gezeigt, wie Sie mit tabCapture und zugehörigen APIs eine Reihe häufiger Anwendungsfälle lösen können.

Typen

CaptureInfo

Attribute

  • Vollbild

    boolean

    Gibt an, ob ein Element auf dem Tab, der aufgenommen wird, im Vollbildmodus ist.

  • 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

    Nummer optional

    Optionale Tab-ID des Tabs, der später getUserMedia() aufruft, um den Stream zu nutzen. Ist nichts angegeben, kann der resultierende Stream nur von der Anruferweiterung verwendet werden. Der Stream kann nur von Frames im jeweiligen Tab verwendet werden, deren Sicherheitsursprung mit dem Ursprung des Nutzer-Tabs übereinstimmt. Der Tab muss einen sicheren Ursprung haben, z.B. HTTPS.

  • targetTabId

    Nummer optional

    Optionale Tab-ID des erfassten Tabs. Wenn keine Angabe erfolgt, wird der aktuell aktive Tab ausgewählt. Nur Tabs, für die der Erweiterung die Berechtigung activeTab gewährt wurde, können als Ziel-Tab verwendet werden.

MediaStreamConstraint

Attribute

  • obligatorisch

    Objekt

  • optional

    Objekt optional

TabCaptureState

Enum

Methoden

capture()

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

Erfasst den sichtbaren Bereich des aktuell aktiven Tabs. Die Erfassung kann nur auf dem derzeit aktiven Tab gestartet werden, nachdem die Erweiterung aufgerufen wurde, ähnlich wie bei activeTab. Die Erfassung wird bei allen Seitennavigationen innerhalb des Tabs fortgesetzt und stoppt, wenn der Tab geschlossen oder der Medienstream durch die Erweiterung geschlossen wird.

Parameters

  • Optionen

    CaptureOptions

    Konfiguriert den zurückgegebenen Medienstream.

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    (stream: LocalMediaStream)=>void

    • stream

      LocalMediaStream

getCapturedTabs()

Versprechen 
chrome.tabCapture.getCapturedTabs(
  callback?: function,
)

Gibt eine Liste der Tabs zurück, die eine Erfassung angefordert haben oder gerade erfasst werden, d.h. status != stoppt und status != error. Dadurch kann der Nutzer durch Erweiterungen über eine vorhandene Tabaufnahme informiert werden, die die Erfassung eines neuen Tabs verhindert oder redundante Anfragen für denselben Tab verhindert.

Parameters

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (result: CaptureInfo[])=>void

Rückgaben

  • Promise<CaptureInfo[]>

    Chrome 116 oder höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

getMediaStreamId()

Versprechen Chrome 71 oder höher 
chrome.tabCapture.getMediaStreamId(
  options?: GetMediaStreamOptions,
  callback?: function,
)

Erstellt eine Stream-ID zur Erfassung des Ziel-Tabs Ähnlich der Methode chrome.tabCapture.Capture(), gibt jedoch anstelle eines Medienstreams eine Medienstream-ID an den Nutzer-Tab zurück.

Parameters

  • Optionen

    GetMediaStreamOptions optional

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (streamId: string)=>void

    • streamId

      String

Rückgaben

  • Versprechen<string>

    Chrome 116 oder höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

Veranstaltungen

onStatusChanged

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

Das Ereignis wird ausgelöst, wenn sich der Erfassungsstatus eines Tabs ändert. So können Entwickler von Erweiterungen den Erfassungsstatus von Tabs verfolgen, um UI-Elemente wie Seitenaktionen synchron zu halten.

Parameters