chrome.tabCapture

Descrição

Use a API chrome.tabCapture para interagir com fluxos de mídia da guia.

Permissões

tabCapture

Conceitos e uso

A API chrome.tabCapture permite acessar uma MediaStream contendo o vídeo e o áudio da guia atual. Ele só pode ser chamado depois que o usuário invoca uma extensão, como clicar no botão de ação dela. Esse comportamento é semelhante ao da permissão "activeTab".

Preservar o áudio do sistema

Quando um MediaStream for recebido para uma guia, o áudio dela não será mais reproduzido para o usuário. Isso é semelhante ao comportamento da função getDisplayMedia() quando a flag suppressLocalAudioPlayback está 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 de MediaStream da guia ao destino padrão.

IDs de stream

Chamar chrome.tabCapture.getMediaStreamId() retornará um ID de stream. Para acessar mais tarde um MediaStream do 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 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 com 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 que o 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 ficava 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 a tabCapture e APIs relacionadas para resolver vários casos de uso comuns.

Tipos

CaptureInfo

Propriedades

  • modo tela cheia

    boolean

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

  • O novo status de captura da guia.

  • tabId

    number

    O ID da guia cujo status foi alterado.

CaptureOptions

Propriedades

GetMediaStreamOptions

Chrome 71 ou mais recente

Propriedades

  • consumerTabId

    número opcional

    ID da guia opcional da guia que mais tarde 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 especificada cuja origem de segurança corresponda à origem da guia "Consumo". A origem da guia precisa ser segura, por exemplo, HTTPS.

  • targetTabId

    número opcional

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

MediaStreamConstraint

Propriedades

  • obrigatório

    objeto

  • opcional

    objeto opcional

TabCaptureState

Tipo enumerado

Métodos

capture()

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

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 é invocada, da mesma forma que activeTab. A captura é mantida durante as navegações nas páginas da guia e é interrompida quando ela é fechada ou o stream 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

    • streaming

      LocalMediaStream

getCapturedTabs()

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

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

Parâmetros

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    (result: CaptureInfo[])=>void

Retorna

  • Promise<CaptureInfo[]>

    Chrome 116 ou mais recente

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

getMediaStreamId()

Promessa Chrome 71+ 
chrome.tabCapture.getMediaStreamId(
  options?: GetMediaStreamOptions,
  callback?: function,
)

Cria um ID de stream para capturar a guia de destino. Semelhante ao método chrome.tabCapture.capture(), mas retorna um ID de fluxo 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 tem esta aparência: 

    (streamId: string)=>void

    • streamId

      string

Retorna

  • Promessa<string>

    Chrome 116 ou mais recente

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

Eventos

onStatusChanged

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

Evento disparado quando o status de captura de uma guia é alterado. Isso permite que os autores de extensões acompanhem o status de captura das guias para manter a sincronia entre elementos da IU, como ações da página.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (info: CaptureInfo)=>void