chrome.tabCapture

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 que l'utilisateur a appelé une extension, par exemple en cliquant sur le bouton d'action de l'extension. Cela est semblable au comportement de l' activeTab.

Conserver l'audio du système

Lorsqu'un MediaStream est obtenu pour un onglet, l'audio de cet onglet n'est plus lu pour l'utilisateur. Cela est semblable au comportement de la getDisplayMedia() fonction lorsque l'indicateur suppressLocalAudioPlayback est défini sur "true".

Pour continuer à lire l'audio pour l'utilisateur, procédez comme suit :

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

Cette opération crée un AudioContext et connecte l'audio du 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, procédez comme suit :

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

Restrictions d'utilisation

Après avoir appelé 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é qui a la même origine de sécurité.
  • Lorsque cette valeur n'est pas spécifiée, à 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'un consumerTabId n'était pas spécifié, l'ID de flux était limité à l'origine de sécurité, au processus de rendu et au frame de rendu 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. Vous y découvrirez 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.

  • Le 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+

Propriétés

  • consumerTabId

    nombre facultatif

    ID d'onglet facultatif de l'onglet qui appellera ultérieurement getUserMedia() pour consommer le flux. Si cette valeur n'est pas spécifiée, le flux résultant 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

    nombre facultatif

    ID d'onglet facultatif de l'onglet à capturer. Si cette valeur n'est pas spécifiée, l'onglet actif actuel 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 actif. La capture ne peut être lancée sur l'onglet actif qu'après l'appel de l'extension, de la même manière qu'activeTab. La capture est conservée lors des navigations entre 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()

Promesse 
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 "stopped" et de "error". Cela permet aux extensions d'informer l'utilisateur qu'une capture d'onglet existante empêcherait la réussite d'une nouvelle capture d'onglet (ou d'empêcher les requêtes redondantes pour le même onglet).

Paramètres

  • callback

    fonction facultative

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

    (result: CaptureInfo[]) => void

Renvoie

  • Promise<CaptureInfo[]>

    Chrome 116+

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

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

getMediaStreamId()

Promesse Chrome 71+ 
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

    fonction facultative

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

    (streamId: string) => void

    • streamId

      chaîne

Renvoie

  • Promise<string>

    Chrome 116+

    Renvoie une promesse qui se résout avec le résultat. En cas de réussite, 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 au bout de quelques secondes s'il n'est pas utilisé.

    Les promesses ne sont compatibles qu'avec Manifest V3 et 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 pour synchroniser les éléments d'interface utilisateur tels que les actions de page.

Paramètres

  • callback

    fonction

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

    (info: CaptureInfo) => void