chrome.tabCapture

refresh date: 2026-09-25 robots: noindex

Beschrijving

Gebruik de chrome.tabCapture API om te communiceren met mediastreamtabbladen.

Rechten

tabCapture

Overzicht

Met de chrome.tabCapture API heb je toegang tot een MediaStream met video en audio van het huidige tabblad. Deze kan alleen worden aangeroepen nadat de gebruiker een extensie heeft aangeroepen, bijvoorbeeld door op de actieknop van de extensie te klikken. Dit is vergelijkbaar met het gedrag van het recht activeTab.

Systeemaudio behouden

Als een MediaStream wordt verkregen voor een tabblad, wordt de audio op dat tabblad niet meer afgespeeld voor de gebruiker. Dit is vergelijkbaar met het gedrag van de functie getDisplayMedia() als de markering suppressLocalAudioPlayback is ingesteld op waar.

Gebruik het volgende om audio te blijven afspelen voor de gebruiker:

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

Hiermee wordt een nieuwe AudioContext gemaakt en wordt de audio van de MediaStream van het tabblad gekoppeld aan de standaardbestemming.

Stream-ID's

Als je chrome.tabCapture.getMediaStreamId aanroept, wordt er een stream-ID geretourneerd. Gebruik het volgende om later toegang te krijgen tot een MediaStream via de ID:

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

Gebruiksbeperkingen

Nadat je getMediaStreamId() hebt aangeroepen, gelden er beperkingen voor waar de geretourneerde stream-ID kan worden gebruikt:

  • Als consumerTabId is ingevoerd, kan de ID worden gebruikt door een getUserMedia()-aanroep in elk frame op het aangegeven tabblad met dezelfde beveiligingsoorsprong.
  • Als dit niet is gespecificeerd, kan de ID vanaf Chrome 116 worden gebruikt in elk frame met dezelfde beveiligingsoorsprong in hetzelfde weergaveproces als de beller. Dit betekent dat een stream-ID die is verkregen in een servicemedewerker, kan worden gebruikt in een offscreen document.

Als vóór Chrome 116 geen consumerTabId was opgegeven, werd de stream-ID beperkt tot de beveiligingsoorsprong, het weergaveproces en het weergaveframe van de beller.

Meer informatie

Ga naar Audio-opname en schermopname voor meer informatie over hoe je de chrome.tabCapture API gebruikt. Hier wordt uitgelegd hoe je tabCapture en gerelateerde API's gebruikt om een aantal veelvoorkomende use cases op te lossen.

Typen

CaptureInfo

Eigenschappen

  • volledig scherm

    booleaans

    Of een element in het tabblad dat wordt vastgelegd, in de modus voor volledig scherm staat.

  • De nieuwe opnamestatus van het tabblad.

  • tabId

    getal

    De ID van het tabblad waarvan de status is gewijzigd.

CaptureOptions

Eigenschappen

GetMediaStreamOptions

Chrome 71 of hoger

Eigenschappen

  • consumerTabId

    number optioneel

    Optionele tabblad-ID van het tabblad dat later getUserMedia() aanroept om de stream te gebruiken. Als je niets invoert, kan de resulterende stream alleen worden gebruikt door de aanroepende extensie. De stream kan alleen worden gebruikt door frames op het aangegeven tabblad waarvan de beveiligingsoorsprong overeenkomt met de oorsprong van het tabblad van de consument. De oorsprong van het tabblad moet een beveiligde oorsprong zijn, bijvoorbeeld HTTPS.

  • targetTabId

    number optioneel

    Optionele tabblad-ID van het tabblad dat wordt vastgelegd. Als je niets opgeeft, wordt het huidige actieve tabblad geselecteerd. Alleen tabbladen waarvoor de extensie het recht activeTab heeft gekregen, kunnen worden gebruikt als doeltabblad.

MediaStreamConstraint

Eigenschappen

  • verplicht

    object

  • optioneel

    object optioneel

TabCaptureState

Enum

"pending"

active

"stopped"

"error"

Methoden

capture()

Alleen voorgrond 
chrome.tabCapture.capture(
  options: CaptureOptions,
  callback: function,
): void

Legt het zichtbare gebied van het actieve tabblad vast. Opname kan alleen worden gestart op het op dat moment actieve tabblad nadat de extensie is aangeroepen, vergelijkbaar met de manier waarop activeTab werkt. De opname wordt gehandhaafd tijdens paginanavigatie binnen het tabblad en stopt als het tabblad wordt gesloten of als de mediastream wordt gesloten door de extensie.

Parameters

  • Hiermee stel je de geretourneerde mediastream in.

  • callback

    functie

    De parameter callback ziet er zo uit: 

    (stream: LocalMediaStream) => void

    • stream

      LocalMediaStream

getCapturedTabs()

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

Retourneert een lijst met tabbladen die om vastlegging hebben gevraagd of worden vastgelegd, d.w.z. status != gestopt en status != fout. Zo kunnen extensies de gebruiker laten weten dat er een bestaande tabbladopname is die voorkomt dat een nieuwe tabbladopname lukt (of om overbodige verzoeken voor hetzelfde tabblad te voorkomen).

Parameters

  • callback

    functie optioneel

    De parameter callback ziet er zo uit: 

    (result: CaptureInfo[]) => void

Retourzendingen

  • Promise<CaptureInfo[]>

    Chrome 116 of hoger

    Retourneert een Promise die wordt omgezet met CaptureInfo[] voor vastgelegde tabbladen.

    Promises worden alleen ondersteund voor Manifest V3 en hoger. Andere platforms moeten callbacks gebruiken.

getMediaStreamId()

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

Maakt een stream-ID om het doeltabblad vast te leggen. Vergelijkbaar met de methode chrome.tabCapture.capture(), maar retourneert een mediastream-ID in plaats van een mediastream naar het consumententabblad.

Parameters

  • opties

    GetMediaStreamOptions optioneel

  • callback

    functie optioneel

    De parameter callback ziet er zo uit: 

    (streamId: string) => void

    • streamId

      tekenreeks

Retourzendingen

  • Promise<string>

    Chrome 116 of hoger

    Retourneert een Promise die wordt omgezet met het resultaat. Als dit lukt, is het resultaat een ondoorzichtige tekenreeks die kan worden doorgegeven aan de getUserMedia() API om een mediastream te genereren die overeenkomt met het doeltabblad. De gemaakte streamId kan maar één keer worden gebruikt en verloopt na een paar seconden als deze niet wordt gebruikt.

    Promises worden alleen ondersteund voor Manifest V3 en hoger. Andere platforms moeten callbacks gebruiken.

Evenementen

onStatusChanged

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

Gebeurtenis die wordt geactiveerd als de opnamestatus van een tabblad verandert. Zo kunnen auteurs van extensies de vastlegstatus van tabbladen bijhouden om UI-elementen zoals pagina-acties gesynchroniseerd te houden.

Parameters