chrome.tabCapture

refresh date: 2026-09-25 robots: noindex

Descripción

Usa la API de chrome.tabCapture para interactuar con los flujos de contenido multimedia de las pestañas.

Permisos

tabCapture

Descripción general

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

Cómo conservar el audio del sistema

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

Para seguir reproduciendo audio para el usuario, usa lo siguiente:

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

Esto crea un AudioContext nuevo y conecta el audio del MediaStream de la pestaña al destino predeterminado.

IDs de transmisión

Si llamas a chrome.tabCapture.getMediaStreamId, se devolverá un ID de transmisión. Para acceder más adelante 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 marco de la pestaña determinada que tenga el mismo origen de seguridad.
  • Cuando no se especifica, 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

Para obtener más información sobre cómo usar la API de chrome.tabCapture, consulta Grabación de audio y captura de pantalla. En este documento, se muestra cómo usar tabCapture y las APIs relacionadas para resolver una serie de casos de uso comunes.

Tipos

CaptureInfo

Propiedades

  • pantalla completa

    booleano

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

  • Es el nuevo estado de captura de la pestaña.

  • tabId

    número

    Es el ID de la pestaña cuyo estado cambió.

CaptureOptions

Propiedades

GetMediaStreamOptions

Chrome 71 y versiones posteriores

Propiedades

  • consumerTabId

    number opcional

    ID de pestaña opcional de la pestaña que luego invocará a getUserMedia() para consumir la transmisión. Si no se especifica, la extensión que realiza la llamada solo puede usar la transmisión resultante. Solo los marcos de la 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 seguro, p.ej., HTTPS.

  • targetTabId

    number opcional

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

MediaStreamConstraint

Propiedades

  • obligatorio

    objeto

  • opcional

    objeto opcional

TabCaptureState

Enum

"pending"

"active"

"stopped"

"error"

Métodos

capture()

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

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

Parámetros

  • opciones

    CaptureOptions

    Configura el flujo de contenido multimedia que se devuelve.

  • callback

    función

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

    (stream: LocalMediaStream) => void

    • transmisión

      LocalMediaStream

getCapturedTabs()

Promise 
chrome.tabCapture.getCapturedTabs(
  callback?: function,
): Promise<CaptureInfo[]>

Devuelve una lista de pestañas que solicitaron la captura o que se están capturando, es decir, estado != detenido y estado != error. Esto permite que las extensiones informen al usuario que hay una captura de pestaña existente que impediría que se realice una nueva captura de pestaña (o que se 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

Muestra

  • Promise<CaptureInfo[]>

    Chrome 116 y versiones posteriores

    Devuelve una promesa que se resuelve con CaptureInfo[] para las pestañas capturadas.

    Las promesas solo se admiten en Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

getMediaStreamId()

Promise Chrome 71 y versiones posteriores 
chrome.tabCapture.getMediaStreamId(
  options?: GetMediaStreamOptions,
  callback?: function,
): Promise<string>

Crea un ID de transmisión para capturar la pestaña de destino. Es similar al método chrome.tabCapture.capture(), pero devuelve un ID de transmisión de contenido multimedia, en lugar de una transmisión de contenido multimedia, a la pestaña del consumidor.

Parámetros

  • opciones

    GetMediaStreamOptions opcional

  • callback

    función opcional

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

    (streamId: string) => void

    • streamId

      string

Muestra

  • Promise<string>

    Chrome 116 y versiones posteriores

    Devuelve una promesa que se resuelve con el resultado. Si se realiza correctamente, el resultado es una cadena opaca que se puede pasar a la API de getUserMedia() para generar una transmisión de contenido multimedia que corresponda a la pestaña de destino. El streamId creado solo se puede usar una vez y vence después de unos segundos si no se usa.

    Las promesas solo se admiten en Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

Eventos

onStatusChanged

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

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

Parámetros

  • callback

    función

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

    (info: CaptureInfo) => void