chrome.tabCapture

Descripción

Usa la API de chrome.tabCapture para interactuar con las transmisiones multimedia de pestañas.

Permisos

tabCapture

Conceptos y uso

La API de chrome.tabCapture te permite acceder a un objeto MediaStream que contiene video y audio de la pestaña actual. Solo se puede llamar a esta después de que el usuario invoca una extensión, por ejemplo, con un clic en el botón de acción de la extensión. Esto es similar al comportamiento del permiso "activeTab".

Conservar el audio del sistema

Cuando se obtiene una MediaStream para una pestaña, el usuario deja de reproducir el audio de esa pestaña. Esto es similar al comportamiento de la función getDisplayMedia() cuando la marca suppressLocalAudioPlayback se establece como verdadera.

Para seguir reproduciendo audio al usuario, usa lo siguiente:

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

De esta manera, se crea una AudioContext nueva y se conecta el audio del MediaStream de la pestaña al destino predeterminado.

IDs de transmisión

Si llamas a chrome.tabCapture.getMediaStreamId(), se mostrará un ID de transmisión. Para acceder más tarde a un MediaStream desde el ID, usa lo siguiente:

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

Restricciones de uso

Después de llamar a getMediaStreamId(), existen restricciones sobre dónde se puede usar el ID de transmisión que se muestra:

  • Si se especifica consumerTabId, una llamada a getUserMedia() puede usar el ID en cualquier fotograma de la pestaña determinada que tenga el mismo origen de seguridad.
  • Si no se especifica esto, a partir de Chrome 116, el ID se puede usar en cualquier marco con el mismo origen de seguridad en el mismo proceso de renderización que el emisor. Esto significa que un ID de transmisión obtenido en un service worker se puede usar en un documento fuera de pantalla.

Antes de Chrome 116, cuando no se especificaba un consumerTabId, el ID de transmisión se restringía al origen de seguridad, al proceso de renderización y al marco de renderización del emisor.

Más información

Si quieres obtener más información para usar la API de chrome.tabCapture, consulta Grabación de audio y captura de pantalla. Aquí se demuestra cómo usar tabCapture y las APIs relacionadas para resolver varios casos de uso comunes.

Tipos

CaptureInfo

Propiedades

  • pantalla completa

    boolean

    Indica si un elemento de la pestaña que se está capturando está en modo de pantalla completa.

  • El nuevo estado de captura de la pestaña.

  • tabId

    número

    El ID de la pestaña cuyo estado cambió.

CaptureOptions

Propiedades

GetMediaStreamOptions

Chrome 71 y versiones posteriores

Propiedades

  • consumerTabId

    número opcional

    ID de pestaña opcional de la pestaña que más tarde invocará a getUserMedia() para consumir la transmisión. Si no se especifica, solo la extensión de llamada puede usar la transmisión resultante. Solo los marcos de una pestaña determinada cuyo origen de seguridad coincida con el origen de la pestaña del consumidor pueden usar la transmisión. El origen de la pestaña debe ser un origen seguro, p.ej., HTTPS.

  • targetTabId

    número opcional

    ID de pestaña opcional de la pestaña que se capturará. Si no se especifica, se seleccionará la pestaña activa actual. Solo se pueden usar como pestaña de destino las pestañas a las que se les otorgó el permiso activeTab.

MediaStreamConstraint

Propiedades

  • obligatorio

    objeto

  • opcional

    objeto opcional

TabCaptureState

Enum

Métodos

capture()

Solo en primer plano 
chrome.tabCapture.capture(
  options: CaptureOptions,
  callback: function,
)

Captura el área visible de la pestaña activa en ese momento. La captura solo se puede iniciar en la pestaña activa actualmente después de invocar la extensión, de manera similar a como funciona activeTab. La captura se mantiene en todas las navegaciones de páginas dentro de la pestaña y se detiene cuando la pestaña se cierra o la extensión cierra la transmisión de contenido multimedia.

Parámetros

  • Opciones

    CaptureOptions

    Configura la transmisión multimedia que se muestra.

  • callback

    la función

    El parámetro callback se ve de la siguiente manera: 

    (stream: LocalMediaStream)=>void

    • novedades

      LocalMediaStream

getCapturedTabs()

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

Muestra una lista de pestañas que solicitaron la captura o que se están capturando, es decir, estado != detenida y estado != error. Esto permite que las extensiones informen al usuario que hay una captura de pestaña existente que evitaría que se realice correctamente una captura de pestaña nueva (o que eviten solicitudes redundantes para la misma pestaña).

Parámetros

  • callback

    Función opcional

    El parámetro callback se ve de la siguiente manera: 

    (result: CaptureInfo[])=>void

Devuelve

  • Promise<CaptureInfo[]>

    Chrome 116 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.

getMediaStreamId()

Promesa Chrome 71 y versiones posteriores 
chrome.tabCapture.getMediaStreamId(
  options?: GetMediaStreamOptions,
  callback?: function,
)

Crea un ID de flujo para capturar la pestaña de destino. Es similar al método chrome.tabCapture.capture(), pero muestra un ID de flujo de medios, en lugar de un flujo de medios, a la pestaña consumidor.

Parámetros

  • Opciones

    GetMediaStreamOptions opcional

  • callback

    Función opcional

    El parámetro callback se ve de la siguiente manera: 

    (streamId: string)=>void

    • streamId

      cadena

Devuelve

  • Promesa<string>

    Chrome 116 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.

Eventos

onStatusChanged

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

El evento se activa cuando cambia el estado de captura de una pestaña. Esto permite a los autores de extensiones hacer un seguimiento del estado de captura de las pestañas para mantener sincronizados los elementos de la IU, como las acciones de la página.

Parámetros

  • callback

    la función

    El parámetro callback se ve de la siguiente manera: 

    (info: CaptureInfo)=>void