chrome.tabCapture

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 da extensão. Isso é semelhante ao comportamento da permissão activeTab.

Preservar o áudio do sistema

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

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 fluxo. Para acessar um MediaStream do ID mais tarde, 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 de 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 caller. Isso significa que um ID de fluxo obtido em um service worker pode ser usado em um documento offscreen.

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

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 a tabCapture e APIs relacionadas para resolver vários casos de uso comuns.

Tipos

CaptureInfo

Propriedades

  • tela cheia

    booleano

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

  • O novo status de captura da guia.

  • tabId

    número

    O ID da guia cujo status foi alterado.

CaptureOptions

Propriedades

GetMediaStreamOptions

Chrome 71 ou mais recente

Propriedades

  • consumerTabId

    number optional

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

  • targetTabId

    number optional

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

MediaStreamConstraint

Propriedades

  • obrigatório

    objeto

  • opcional

    objeto opcional

TabCaptureState

Enumeração

"pending"

"ativo"

"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 no momento depois que a extensão for invocada, de maneira semelhante ao funcionamento da activeTab. A captura é mantida nas navegações de página na guia e para quando a guia é fechada ou o fluxo de mídia é fechado pela extensão.

Parâmetros

  • opções

    CaptureOptions

    Configura o fluxo de mídia retornado.

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (stream: LocalMediaStream) => void

    • stream

      LocalMediaStream

getCapturedTabs()

Promise 
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 de guia (ou para evitar solicitações redundantes para a mesma guia).

Parâmetros

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (result: CaptureInfo[]) => void

Retorna

  • Promise<CaptureInfo[]>

    Chrome 116 ou mais recente

    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 ou mais recente 
chrome.tabCapture.getMediaStreamId(
  options?: GetMediaStreamOptions,
  callback?: function,
): Promise<string>

Cria um ID de fluxo 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 opcional

    O parâmetro callback tem esta aparência: 

    (streamId: string) => void

    • streamId

      string

Retorna

  • Promise<string>

    Chrome 116 ou mais recente

    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 disparado 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 elementos da interface, como ações de página, sincronizados.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (info: CaptureInfo) => void