chrome.tabCapture

refresh date: 2026-09-25 robots: noindex

Description

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

Autorisations

tabCapture

Présentation

L'API chrome.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 chrome.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 chrome.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 ou version ultérieure

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 
chrome.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()

Promise 
chrome.tabCapture.getCapturedTabs(
  callback?: function,
): 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).

Paramètres

  • callback

    function facultatif

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

    (result: CaptureInfo[]) => void

Renvoie

  • Promise<CaptureInfo[]>

    Chrome 116 ou version ultérieure

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

    Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

getMediaStreamId()

Promise Chrome 71 et versions ultérieures 
chrome.tabCapture.getMediaStreamId(
  options?: GetMediaStreamOptions,
  callback?: function,
): 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

  • options

    GetMediaStreamOptions facultatif

  • callback

    function facultatif

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

    (streamId: string) => void

    • streamId

      chaîne

Renvoie

  • Promise<string>

    Chrome 116 ou version ultérieure

    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é.

    Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

Événements

onStatusChanged

chrome.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