chrome.tabCapture

refresh date: 2026-09-25 robots: noindex

Descrição

Use a API chrome.tabCapture para interagir com streams de mídia de guias.

Permissões

tabCapture

Visão geral

A API chrome.tabCapture permite acessar um MediaStream que contém vídeo e áudio da guia atual. Ele só pode ser chamado depois que o usuário invoca uma extensão, por exemplo, clicando no botão de ação dela. Isso é semelhante ao comportamento da permissão activeTab.

Preservar o áudio do sistema

Quando um MediaStream é recebido para uma guia, o áudio nela não é mais reproduzido para o usuário. Isso é semelhante ao comportamento da função getDisplayMedia() quando a flag suppressLocalAudioPlayback é definida como verdadeira.

Para continuar reproduzindo áudio para o usuário, use o seguinte:

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

Isso cria um novo AudioContext e conecta o áudio do MediaStream da guia ao destino padrão.

IDs de stream

Chamar chrome.tabCapture.getMediaStreamId vai retornar um ID de stream. Para acessar um MediaStream pelo ID, use o seguinte:

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

Restrições de uso

Depois de chamar getMediaStreamId(), há restrições sobre onde o ID do stream retornado pode ser usado:

  • Se consumerTabId for especificado, o ID poderá ser usado por uma chamada getUserMedia() em qualquer frame na guia especificada que tenha a mesma origem de segurança.
  • Quando isso não é especificado, a partir do Chrome 116, o ID pode ser usado em qualquer frame com a mesma origem de segurança no mesmo processo de renderização do autor da chamada. Isso significa que um ID de stream recebido em um service worker pode ser usado em um documento fora da tela.

Antes do Chrome 116, quando um consumerTabId não era especificado, o ID do stream era restrito à origem de segurança, ao processo de renderização e ao frame de renderização do autor da chamada.

Saiba mais

Para saber mais sobre como usar a API chrome.tabCapture, consulte Gravação de áudio e captura de tela. Isso demonstra como usar tabCapture e as APIs relacionadas para resolver vários casos de uso comuns.

Tipos

CaptureInfo

Propriedades

  • tela cheia

    booleano

    Se um elemento na guia que está sendo capturada está no modo de tela cheia.

  • O novo status de captura da guia.

  • tabId

    número

    O ID da guia cujo status mudou.

CaptureOptions

Propriedades

GetMediaStreamOptions

Chrome 71+

Propriedades

  • consumerTabId

    número optional

    ID opcional da guia que vai invocar getUserMedia() para consumir o stream. Se não for especificado, o stream resultante só poderá ser usado pela extensão de chamada. O stream só pode ser usado por frames na guia em questão que tenham a mesma origem de segurança da guia do consumidor. A origem da guia precisa ser segura, por exemplo, HTTPS.

  • targetTabId

    número optional

    ID opcional da guia que será capturada. Se não for especificada, a guia ativa atual será selecionada. Somente as guias para as quais a extensão recebeu a permissão activeTab podem ser usadas como guia de destino.

MediaStreamConstraint

Propriedades

  • obrigatório

    objeto

  • opcional

    objeto optional

TabCaptureState

Enumeração

"pending"

"active"

"stopped"

"error"

Métodos

capture()

Somente em primeiro plano 
chrome.tabCapture.capture(
  options: CaptureOptions,
  callback: function,
): void

Captura a área visível da guia ativa no momento. A captura só pode ser iniciada na guia ativa depois que a extensão for invocada, de forma semelhante ao funcionamento de activeTab. A captura é mantida nas navegações de página dentro da guia e é interrompida quando a guia é fechada ou o stream de mídia é fechado pela extensão.

Parâmetros

  • opções

    CaptureOptions

    Configura o stream de mídia retornado.

  • callback

    função

    O parâmetro callback é semelhante a: 

    (stream: LocalMediaStream) => void

    • stream

      LocalMediaStream

getCapturedTabs()

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

Retorna uma lista de guias que solicitaram captura ou estão sendo capturadas, ou seja, status != stopped e status != error. Isso permite que as extensões informem ao usuário que há uma captura de guia em andamento que impediria uma nova captura (ou para evitar solicitações redundantes para a mesma guia).

Parâmetros

  • callback

    função optional

    O parâmetro callback é semelhante a: 

    (result: CaptureInfo[]) => void

Retorna

  • Promise<CaptureInfo[]>

    Chrome 116+

    Retorna uma promessa que é resolvida com CaptureInfo[] para guias capturadas.

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

getMediaStreamId()

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

Cria um ID de stream para capturar a guia de destino. Semelhante ao método chrome.tabCapture.capture(), mas retorna um ID de stream de mídia, em vez de um stream de mídia, para a guia do consumidor.

Parâmetros

  • opções

    GetMediaStreamOptions opcional

  • callback

    função optional

    O parâmetro callback é semelhante a: 

    (streamId: string) => void

    • streamId

      string

Retorna

  • Promise<string>

    Chrome 116+

    Retorna uma promessa que é resolvida com o resultado. Se for bem-sucedido, o resultado será uma string opaca que pode ser transmitida para a API getUserMedia() para gerar um stream de mídia que corresponde à guia de destino. O streamId criado só pode ser usado uma vez e expira após alguns segundos se não for usado.

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

Eventos

onStatusChanged

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

Evento acionado quando o status de captura de uma guia muda. Isso permite que os autores de extensões acompanhem o status de captura das guias para manter os elementos da interface, como ações de página, sincronizados.

Parâmetros

  • callback

    função

    O parâmetro callback é semelhante a: 

    (info: CaptureInfo) => void