chrome.tabCapture

Descrizione

Usa l'API chrome.tabCapture per interagire con gli stream multimediali delle schede.

Autorizzazioni

tabCapture

Concetti e utilizzo

L'API chrome.tab Capture ti consente di accedere a un elemento MediaStream contenente video e audio della scheda corrente. Può essere chiamata solo dopo che l'utente richiama un'estensione, ad esempio facendo clic sul pulsante di azione dell'estensione. Questo è simile al comportamento dell'autorizzazione "activeTab".

Mantieni l'audio di sistema

Quando si ottiene un MediaStream per una scheda, l'audio della scheda in questione non viene più riprodotto all'utente. Questo è simile al comportamento della funzione getDisplayMedia() quando il flag suppressLocalAudioPlayback è impostato su true.

Per continuare a riprodurre l'audio per l'utente, usa quanto segue:

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

Viene creato un nuovo AudioContext e l'audio del MediaStream della scheda viene collegato alla destinazione predefinita.

ID stream

La chiamata a chrome.tabCapture.getMediaStreamId() restituirà un ID stream. Per accedere a MediaStream in un secondo momento dall'ID, utilizza quanto segue:

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

Restrizioni all'uso

Dopo la chiamata a getMediaStreamId(), sono previste limitazioni su dove è possibile utilizzare l'ID streaming restituito:

  • Se consumerTabId è specificato, l'ID può essere utilizzato da una chiamata getUserMedia() in qualsiasi frame nella scheda specificata che ha la stessa origine di sicurezza.
  • Se questo non è specificato, a partire dalla versione 116 di Chrome, l'ID può essere utilizzato in qualsiasi frame con la stessa origine di sicurezza nello stesso processo di rendering del chiamante. Ciò significa che un ID stream ottenuto in un service worker può essere utilizzato in un documento fuori schermo.

Prima di Chrome 116, quando non veniva specificato un consumerTabId, l'ID stream era limitato sia all'origine della sicurezza, al processo di rendering e al frame di rendering del chiamante.

Scopri di più

Per scoprire di più su come utilizzare l'API chrome.tabCapture, consulta Registrazione audio e acquisizione schermo. Questo dimostra come utilizzare tabCapture e le relative API per risolvere una serie di casi d'uso comuni.

Tipi

CaptureInfo

Proprietà

  • schermo intero

    boolean

    Indica se un elemento della scheda acquisito è in modalità a schermo intero.

  • Il nuovo stato di acquisizione della scheda.

  • tabId

    numero

    L'ID della scheda il cui stato è cambiato.

CaptureOptions

Proprietà

GetMediaStreamOptions

Chrome 71 e versioni successive

Proprietà

  • consumerTabId

    numero facoltativo

    ID scheda facoltativo della scheda che in seguito richiamerà getUserMedia() per consumare il flusso. Se non specificata, lo stream risultante può essere utilizzato solo dall'estensione di chiamata. Il flusso può essere utilizzato solo dai frame nella scheda specificata la cui origine di sicurezza corrisponde a quella della scheda di accettazione. L'origine della scheda deve essere un'origine sicura, ad esempio HTTPS.

  • targetTabId

    numero facoltativo

    ID scheda facoltativo della scheda che verrà acquisita. Se non specificata, verrà selezionata la scheda attiva corrente. Solo le schede per cui all'estensione è stata concessa l'autorizzazione activeTab possono essere utilizzate come scheda di destinazione.

MediaStreamConstraint

Proprietà

  • obbligatorio

    oggetto

  • facoltativo

    oggetto facoltativo

TabCaptureState

Enum

Metodi

capture()

Solo in primo piano 
chrome.tabCapture.capture(
  options: CaptureOptions,
  callback: function,
)

Acquisisce l'area visibile della scheda attualmente attiva. L'acquisizione può essere avviata solo nella scheda attualmente attiva dopo che l'estensione è stata chiamata, in modo simile al funzionamento di activeTab. L'acquisizione viene mantenuta durante le navigazioni tra le pagine all'interno della scheda e si interrompe quando la scheda viene chiusa o lo stream multimediale viene chiuso dall'estensione.

Parametri

  • opzioni

    CaptureOptions

    Configura lo stream multimediale restituito.

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (stream: LocalMediaStream)=>void

    • streaming

      LocalMediaStream

getCapturedTabs()

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

Restituisce un elenco di schede che hanno richiesto l'acquisizione o che vengono acquisite, ad esempio stato != interrotto e stato != errore. In questo modo le estensioni possono informare l'utente che è già presente un'acquisizione di schede che impedirebbe l'acquisizione di una nuova scheda (o impedire richieste ridondanti per la stessa scheda).

Parametri

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (result: CaptureInfo[])=>void

Ritorni

  • Promise<CaptureInfo[]>

    Chrome 116 e versioni successive

    Le promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.

getMediaStreamId()

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

Crea un ID stream per acquisire la scheda di destinazione. Simile al metodo chrome.tab Capture.capture(), ma restituisce un ID stream multimediale invece di uno stream multimediale alla scheda Consumatori.

Parametri

  • opzioni

    GetMediaStreamOptions facoltativo

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (streamId: string)=>void

    • streamId

      stringa

Ritorni

  • Promessa<string>

    Chrome 116 e versioni successive

    Le promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.

Eventi

onStatusChanged

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

L'evento viene attivato quando lo stato di acquisizione di una scheda cambia. In questo modo gli autori delle estensioni possono tenere traccia dello stato di acquisizione delle schede per mantenere sincronizzati gli elementi dell'interfaccia utente, come le azioni sulle pagine.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (info: CaptureInfo)=>void