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 chamadagetUserMedia()
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.
-
status
O novo status de captura da guia.
-
tabId
number
O ID da guia cujo status foi alterado.
CaptureOptions
Propriedades
-
vários idiomas
booleano opcional
-
audioConstraints
MediaStreamConstraint opcional
-
Vídeo
booleano opcional
-
videoConstraints
MediaStreamConstraint opcional
GetMediaStreamOptions
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()
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
Configura o fluxo de mídia retornado.
-
callback
função
O parâmetro
callback
tem esta aparência:(stream: LocalMediaStream) => void
-
streaming
LocalMediaStream
-
getCapturedTabs()
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
-
resultado
-
Retorna
-
Promise<CaptureInfo[]>
Chrome 116 ou mais recentePromessas 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()
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 recentePromessas 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
-
informações
-