chrome.tabCapture

Description

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

Autorisations

tabCapture

Concepts et utilisation

L'API chrome.tabCapture vous permet d'accéder à une MediaStream contenant la vidéo et l'audio de l'onglet actif. 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. Ce comportement est semblable à celui de l'autorisation "activeTab".

Préserver l'audio du système

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

Pour continuer à lire l'audio auprès de l'utilisateur, utilisez le code suivant:

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

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

ID de flux

Appeler chrome.tabCapture.getMediaStreamId() renvoie un ID de flux. Pour accéder ultérieurement à un MediaStream à partir de l'ID, utilisez le code suivant:

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

Restrictions d'utilisation

Après avoir appelé getMediaStreamId(), des restrictions s'appliquent à l'emplacement d'utilisation de l'ID de flux renvoyé:

  • Si consumerTabId est spécifié, l'ID peut être utilisé par un appel getUserMedia() dans n'importe quel frame de l'onglet concerné, ayant la même origine de sécurité.
  • Lorsqu'il n'est pas spécifié, à partir de Chrome 116, l'ID peut être utilisé dans n'importe quelle image 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 auprès d'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 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. 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

    boolean

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

  • Nouvel état de capture de l'onglet.

  • tabId

    number

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

CaptureOptions

Propriétés

GetMediaStreamOptions

Chrome 71 et versions ultérieures

Propriétés

  • consumerTabId

    numéro facultatif

    ID d'onglet facultatif de l'onglet qui appellera plus tard getUserMedia() pour utiliser le flux. S'il n'est pas spécifié, le flux obtenu ne peut être utilisé que par l'extension d'appel. Le flux ne peut être utilisé que par les frames de l'onglet donné dont l'origine de sécurité correspond à celle de l'onglet de consommation. L'origine de l'onglet doit être une origine sécurisée (HTTPS, par exemple).

  • targetTabId

    numéro facultatif

    ID d'onglet facultatif de l'onglet qui sera capturé. Si vous n'indiquez aucune valeur, l'onglet actif actuel sera 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

  • facultative

    objet facultatif

TabCaptureState

Enum

"active"

"error"

Méthodes

capture()

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

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

Paramètres

  • options

    CaptureOptions

    Configure le flux multimédia renvoyé.

  • rappel

    function

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

    (stream: LocalMediaStream)=>void

    • lire en streaming

      LocalMediaStream

getCapturedTabs()

Promesse 
chrome.tabCapture.getCapturedTabs(
  callback?: function,
)

Renvoie la liste des onglets qui ont demandé une capture ou qui sont en cours de capture, c'est-à-dire statut != arrêté et état != erreur. Les extensions peuvent ainsi informer l'utilisateur qu'une capture d'onglet existante empêche la réussite d'une nouvelle capture d'onglet (ou empêche les demandes redondantes pour le même onglet).

Paramètres

  • rappel

    fonction facultative

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

    (result: CaptureInfo[])=>void

Renvoie

  • Promise<CaptureInfo[]>

    Chrome 116 et versions ultérieures

    Les promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.

getMediaStreamId()

Promesse Chrome 71 et versions ultérieures 
chrome.tabCapture.getMediaStreamId(
  options?: GetMediaStreamOptions,
  callback?: function,
)

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

Paramètres

  • options

    GetMediaStreamOptions facultatif

  • rappel

    fonction facultative

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

    (streamId: string)=>void

    • streamId

      chaîne

Renvoie

  • Promesse<chaîne>

    Chrome 116 et versions ultérieures

    Les promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.

É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 de l'interface utilisateur tels que les actions sur les pages.

Paramètres

  • rappel

    function

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

    (info: CaptureInfo)=>void