browser.tabCapture

Description

Utilisez l'API chrome.tabCapture pour interagir avec les flux multimédias des onglets.

Autorisations

tabCapture

Concepts et utilisation

L'API browser.tabCapture vous permet d'accéder à un MediaStream contenant la vidéo et l'audio de l'onglet actuel. Elle ne peut être appelée qu'après l'appel d'une extension par l'utilisateur, par exemple en cliquant sur le bouton d'action de l'extension. Ce comportement est semblable à celui de l'autorisation "activeTab".

Conserver l'audio du système

Lorsqu'un MediaStream est obtenu pour un onglet, l'audio de cet onglet n'est plus diffusé pour l'utilisateur. Ce comportement est semblable à celui de la fonction getDisplayMedia() lorsque l'option suppressLocalAudioPlayback est définie sur "true".

Pour continuer à diffuser du contenu audio à l'utilisateur, utilisez la commande suivante :

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

Cette opération crée un AudioContext et connecte l'audio de l'MediaStream de l'onglet à la destination par défaut.

ID des flux

L'appel de browser.tabCapture.getMediaStreamId() renvoie un ID de flux. Pour accéder ultérieurement à un MediaStream à partir de l'ID, utilisez la commande suivante :

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

Restrictions d'utilisation

Après l'appel de getMediaStreamId(), l'utilisation de l'ID de flux renvoyé est soumise à des restrictions :

  • Si consumerTabId est spécifié, l'ID peut être utilisé par un appel getUserMedia() dans n'importe quel frame de l'onglet donné ayant la même origine de sécurité.
  • Si ce paramètre n'est pas spécifié, à partir de Chrome 116, l'ID peut être utilisé dans n'importe quel frame ayant la même origine de sécurité dans le même processus de rendu que l'appelant. Cela signifie qu'un ID de flux obtenu dans un service worker peut être utilisé dans un document hors écran.

Avant Chrome 116, lorsqu'aucun consumerTabId n'était spécifié, l'ID de flux était limité à l'origine de sécurité, au processus d'affichage et au frame d'affichage de l'appelant.

En savoir plus

Pour en savoir plus sur l'utilisation de l'API browser.tabCapture, consultez Enregistrement audio et capture d'écran. Cela montre comment utiliser tabCapture et les API associées pour résoudre un certain nombre de cas d'utilisation courants.

Types

CaptureInfo

Propriétés

  • plein écran

    booléen

    Indique si un élément de l'onglet capturé est en mode plein écran.

  • Nouvel état de capture de l'onglet.

  • tabId

    nombre

    ID de l'onglet dont l'état a changé.

CaptureOptions

Propriétés

GetMediaStreamOptions

Chrome 71+ browser.* depuis Chrome 148

Propriétés

  • consumerTabId

    number facultatif

    ID d'onglet facultatif de l'onglet qui appellera ultérieurement getUserMedia() pour consommer le flux. Si ce paramètre n'est pas spécifié, le flux obtenu ne peut être utilisé que par l'extension appelante. Le flux ne peut être utilisé que par les frames de l'onglet donné dont l'origine de sécurité correspond à l'origine de l'onglet consommateur. L'origine de l'onglet doit être une origine sécurisée, par exemple HTTPS.

  • targetTabId

    number facultatif

    ID facultatif de l'onglet qui sera capturé. Si aucune valeur n'est spécifiée, l'onglet actif est sélectionné. Seuls les onglets pour lesquels l'extension a reçu l'autorisation activeTab peuvent être utilisés comme onglet cible.

MediaStreamConstraint

Propriétés

  • obligatoire

    objet

  • facultatif

    objet facultatif

TabCaptureState

Énumération

"pending"

"active"

"stopped"

"error"

Méthodes

capture()

Premier plan uniquement 
browser.tabCapture.capture(
  options: CaptureOptions,
  callback: function,
): void

Capture la zone visible de l'onglet actuellement actif. La capture ne peut être lancée que sur l'onglet actuellement actif après l'appel de l'extension, de la même manière que activeTab. La capture est maintenue lors de la navigation sur les pages de l'onglet et s'arrête lorsque l'onglet est fermé ou que le flux multimédia est fermé par l'extension.

Paramètres

  • options

    CaptureOptions

    Configure le flux multimédia renvoyé.

  • callback

    fonction

    Le paramètre callback se présente comme suit : 

    (stream: LocalMediaStream) => void

    • flux

      LocalMediaStream

getCapturedTabs()

browser.tabCapture.getCapturedTabs(): Promise<CaptureInfo[]>

Renvoie la liste des onglets qui ont demandé une capture ou qui sont en cours de capture, c'est-à-dire dont l'état est différent de "arrêté" et "erreur". Cela permet aux extensions d'informer l'utilisateur qu'une capture d'onglet existante empêcherait une nouvelle capture d'onglet de réussir (ou d'éviter les requêtes redondantes pour le même onglet).

Renvoie

  • Promise<CaptureInfo[]>

    Chrome 116+ browser.* depuis Chrome 148

    Renvoie une promesse qui se résout avec CaptureInfo[] pour les onglets capturés.

getMediaStreamId()

Chrome 71+ browser.* depuis Chrome 148 
browser.tabCapture.getMediaStreamId(
  options?: GetMediaStreamOptions,
): Promise<string>

Crée un ID de flux pour capturer l'onglet cible. Semblable à la méthode chrome.tabCapture.capture(), mais renvoie un ID de flux multimédia, au lieu d'un flux multimédia, à l'onglet consommateur.

Paramètres

Renvoie

  • Promise<string>

    Chrome 116+ browser.* depuis Chrome 148

    Renvoie une promesse qui se résout avec le résultat. Si l'opération réussit, le résultat est une chaîne opaque qui peut être transmise à l'API getUserMedia() pour générer un flux multimédia correspondant à l'onglet cible. Le streamId créé ne peut être utilisé qu'une seule fois et expire après quelques secondes s'il n'est pas utilisé.

Événements

onStatusChanged

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

Événement déclenché lorsque l'état de capture d'un onglet change. Cela permet aux auteurs d'extensions de suivre l'état de capture des onglets afin de synchroniser les éléments d'interface utilisateur tels que les actions sur la page.

Paramètres

  • callback

    fonction

    Le paramètre callback se présente comme suit : 

    (info: CaptureInfo) => void