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 ressemble au comportement 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 lu pour l'utilisateur. Cela ressemble au comportement de la fonction getDisplayMedia() lorsque l'indicateur suppressLocalAudioPlayback est défini sur "true".

Pour continuer à lire l'audio à l'utilisateur, utilisez ce qui 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, utilisez ce qui suit :

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'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 donné qui a la même origine de sécurité.
  • Si ce n'est pas spécifié, à partir de Chrome 116, l'ID peut être utilisé dans n'importe quel frame avec 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. 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

    Total

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

CaptureOptions

Propriétés

GetMediaStreamOptions

Chrome 71 et versions ultérieures

Propriétés

  • consumerTabId

    number facultatif

    ID d'onglet facultatif de l'onglet qui appellera ultérieurement getUserMedia() pour consommer le flux. Si aucune valeur n'est 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 à celle de l'onglet consommateur. L'origine de l'onglet doit être sécurisée (HTTPS, par exemple).

  • targetTabId

    number facultatif

    ID facultatif de l'onglet qui sera capturé. Si aucune n'est spécifiée, 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

  • facultatif

    object 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 actif après l'appel de l'extension, de la même manière que activeTab. La capture est maintenue lors des navigations sur la page 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 pour lesquels la capture a été demandée ou est en cours (c'est-à-dire, état != arrêté et état != erreur). 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 demandes 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 et versions ultérieures

    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 et versions ultérieures

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