chrome.tabCapture

Beschreibung

Über die chrome.tabCapture API kannst du mit Tab-Medienstreams interagieren.

Berechtigungen

tabCapture

Konzepte und Verwendung

Mit der chrome.tabCapture API können Sie auf ein MediaStream zugreifen, das Videos und Audio des aktuellen Tabs. Sie kann nur aufgerufen werden, nachdem der Nutzer eine Erweiterung aufgerufen hat, z. B. durch indem Sie auf die Aktionsschaltfläche der Erweiterung klicken. Dies ähnelt dem Verhalten der "activeTab"-Berechtigung.

Systemaudio beibehalten

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

Verwenden Sie folgenden Code, um die Audiowiedergabe für den Nutzer fortzusetzen:

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

Dadurch wird ein neues AudioContext-Element erstellt und der Audioinhalt des MediaStream-Elements des Tabs wird mit dem Standardwert verknüpft. Ziel.

Stream-IDs

Beim Aufrufen von chrome.tabCapture.getMediaStreamId() wird eine Stream-ID zurückgegeben. Zu später greifen Sie ü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 im Hinblick darauf, wo der zurückgegebene Stream-ID kann verwendet werden:

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

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

Weitere Informationen

Weitere Informationen zur Verwendung der chrome.tabCapture API finden Sie unter Audio- und Bildschirmaufnahme: So wird gezeigt, wie Sie tabCapture und zugehörige APIs zur Lösung einer Reihe gängiger Anwendungsfälle.

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

    Zahl optional

    Optionale Tab-ID des Tabs, der später getUserMedia() aufruft, um den Stream zu verarbeiten. Wenn nicht angegeben, kann der resultierende Stream nur von der Anruferweiterung verwendet werden. Der Stream kann nur von Frames im jeweiligen Tab verwendet werden, deren Sicherheitsherkunft mit dem Ursprung des Consumber-Tabs übereinstimmt. Der Ursprung des Tabs muss ein sicherer Ursprung sein, z.B. HTTPS

  • targetTabId

    Zahl 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

"Ausstehend"

"aktiv"

"angehalten"

"Fehler"

Methoden

capture()

<ph type="x-smartling-placeholder"></ph> Nur Vordergrund 
chrome.tabCapture.capture(
  options: CaptureOptions,
  callback: function,
)

Erfasst den sichtbaren Bereich des aktuell aktiven Tabs. Die Erfassung kann erst auf dem derzeit aktiven Tab gestartet werden, nachdem die Erweiterung aufgerufen wurde. Dies funktioniert ähnlich wie activeTab. Die Erfassung wird über die Seitennavigation innerhalb des Tabs hinweg beibehalten und wird gestoppt, wenn der Tab oder der Mediastream durch die Erweiterung geschlossen wird.

Parameter

  • Optionen

    CaptureOptions

    Konfiguriert den zurückgegebenen Medienstream.

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    (stream: LocalMediaStream) => void

    • Stream

      LocalMediaStream

getCapturedTabs()

<ph type="x-smartling-placeholder"></ph> Versprechen 
chrome.tabCapture.getCapturedTabs(
  callback?: function,
)

Gibt eine Liste der Registerkarten zurück, die eine Aufnahme angefordert haben oder gerade erfasst werden, d.h. status != stoppt und status != error. Auf diese Weise können Erweiterungen den Nutzer darüber informieren, dass eine bestehende Tab-Erfassung vorhanden ist, durch die die Erfassung eines neuen Tabs verhindert oder redundante Anfragen für denselben Tab verhindert werden könnten.

Parameter

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (result: CaptureInfo[]) => void

Returns

  • Promise&lt;CaptureInfo[]&gt;

    Chrome 116 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

getMediaStreamId()

<ph type="x-smartling-placeholder"></ph> Versprechen Chrome 71 oder höher 
chrome.tabCapture.getMediaStreamId(
  options?: GetMediaStreamOptions,
  callback?: function,
)

Erstellt eine Stream-ID zum Erfassen des Zieltabs. Ähnlich wie die Methode „chrome.tabCapture.capture()“, gibt jedoch anstelle eines Medienstreams eine Mediastream-ID an den Tab „Nutzer“ zurück.

Parameter

  • Optionen

    GetMediaStreamOptions optional

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (streamId: string) => void

    • streamId

      String

Returns

  • Promise&lt;string&gt;

    Chrome 116 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

Ereignisse

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.

Parameter