chrome.tabCapture

Descrição

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

Permissões

tabCapture

Conceitos e uso

A API chrome.tabCapture permite acessar uma MediaStream que contém vídeos e o áudio da guia atual. Só pode ser chamado depois que o usuário invocar uma extensão, como por clicar no botão de ação da extensão. Isso é semelhante ao comportamento Permissão "activeTab".

Preservar o áudio do sistema

Quando uma MediaStream for recebida para uma guia, o áudio dela não será mais reproduzido para o usuário. Esse comportamento é semelhante ao comportamento da função getDisplayMedia() quando a flag suppressLocalAudioPlayback está definida como verdadeira.

Para continuar a tocar áudio para o usuário, faça 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.

IDs de stream

Chamar chrome.tabCapture.getMediaStreamId() retornará um ID de stream. Para depois 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 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 determinada guia que tem a mesma origem de segurança.
  • Quando isso não for especificado, a partir do Chrome 116, o ID poderá ser usado em qualquer frame com o 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 de stream era restrito a ambos. a origem de segurança, o processo de renderização e o 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 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

    number

    O ID da guia cujo status foi alterado.

CaptureOptions

Propriedades

GetMediaStreamOptions

Chrome 71 ou superior

Propriedades

  • consumerTabId

    número opcional

    ID da guia opcional da guia que depois invocará getUserMedia() para consumir o stream. Se não for especificado, o stream resultante poderá ser usado apenas pela extensão de chamada. O stream só pode ser usado por frames em determinada guia cuja origem de segurança corresponda à origem da guia do consumidor. 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 para as quais 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

Enumeração

"pendente"

"ativo"

"interrompido"

"erro"

Métodos

capture()

Somente 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 for invocada, semelhante à forma como activeTab funciona. A captura é mantida nas navegações de páginas da guia e é interrompida quando a guia 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

    • stream

      LocalMediaStream

getCapturedTabs()

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

Retorna uma lista de guias que solicitaram captura ou que estão sendo capturadas, ou seja, status != interrompido e status != erro. Isso permite que as extensões informem ao usuário que há uma captura de guia existente que impediria a captura de uma nova guia (ou impediria 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 versões mais recentes

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

getMediaStreamId()

Promessa Chrome 71 ou mais recente 
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 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

  • Promessa<string>

    Chrome 116 ou versões mais recentes

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

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

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (info: CaptureInfo) => void