chrome.tabCapture

Descrizione

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

Autorizzazioni

tabCapture

Concetti e utilizzo

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

Preservare l'audio di sistema

Quando viene ottenuto un MediaStream per una scheda, l'audio della scheda non verrà più riprodotto per l'utente. Questo comportamento è simile a quello della funzione getDisplayMedia() quando il flag suppressLocalAudioPlayback è impostato su true.

Per continuare a riprodurre l'audio per l'utente, utilizza 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 chrome.tabCapture.getMediaStreamId() restituirà un ID stream. Per accedere in un secondo momento a un MediaStream dall'ID, utilizza quanto segue:

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

Limitazioni all'utilizzo

Dopo aver chiamato getMediaStreamId(), esistono limitazioni relative all'utilizzo dell'ID stream restituito:

  • Se viene specificato consumerTabId, l'ID può essere utilizzato da una chiamata getUserMedia() in qualsiasi frame della scheda specificata con la stessa origine di sicurezza.
  • Se non viene specificato, a partire da Chrome 116, 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 offscreen.

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

Scopri di più

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

Tipi

CaptureInfo

Proprietà

  • schermo intero

    booleano

    Indica se un elemento nella scheda acquisita è 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+

Proprietà

  • consumerTabId

    number optional

    ID scheda facoltativo della scheda che richiamerà in seguito getUserMedia() per utilizzare lo stream. Se non specificato, lo stream risultante può essere utilizzato solo dall'estensione chiamante. Lo stream può essere utilizzato solo dai frame nella scheda specificata la cui origine di sicurezza corrisponde all'origine della scheda consumer. L'origine della scheda deve essere un'origine sicura, ad esempio HTTPS.

  • targetTabId

    number optional

    (Facoltativo) ID della scheda che verrà acquisita. Se non specificato, viene selezionata la scheda attiva corrente. Solo le schede per le quali è stata concessa l'autorizzazione activeTab possono essere utilizzate come scheda di destinazione.

MediaStreamConstraint

Proprietà

  • obbligatorio

    oggetto

  • facoltativo

    oggetto facoltativo

TabCaptureState

Enum

"pending"

"active"

"stopped"

"error"

Metodi

capture()

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

Acquisisce l'area visibile della scheda attualmente attiva. L'acquisizione può essere avviata solo nella scheda attualmente attiva dopo che l'estensione è stata richiamata, in modo simile al funzionamento di activeTab. La registrazione viene mantenuta durante la navigazione 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 il flusso multimediale restituito.

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (stream: LocalMediaStream) => void

    • flusso

      LocalMediaStream

getCapturedTabs()

chrome.tabCapture.getCapturedTabs(): Promise<CaptureInfo[]>

Restituisce un elenco di schede che hanno richiesto l'acquisizione o che sono in fase di acquisizione, ovvero stato != stopped e stato != error. In questo modo, le estensioni possono informare l'utente che esiste una registrazione della scheda che impedirebbe la riuscita di una nuova registrazione della scheda (o per impedire richieste ridondanti per la stessa scheda).

Resi

  • Promise<CaptureInfo[]>

    Chrome 116+

    Restituisce una promessa che viene risolta con CaptureInfo[] per le schede acquisite.

getMediaStreamId()

Chrome 71+ 
chrome.tabCapture.getMediaStreamId(
  options?: GetMediaStreamOptions,
): Promise<string>

Crea un ID stream per acquisire la scheda di destinazione. Simile al metodo chrome.tabCapture.capture(), ma restituisce un ID flusso multimediale, anziché un flusso multimediale, alla scheda consumer.

Parametri

Resi

  • Promise<string>

    Chrome 116+

    Restituisce una promessa che viene risolta con il risultato. In caso di esito positivo, il risultato è una stringa opaca che può essere passata all'API getUserMedia() per generare un flusso multimediale corrispondente alla scheda di destinazione. Il streamId creato può essere utilizzato una sola volta e scade dopo pochi secondi se non viene utilizzato.

Eventi

onStatusChanged

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

Evento attivato quando cambia lo stato di acquisizione di una scheda. Ciò consente agli autori delle estensioni di tenere traccia dello stato di acquisizione delle schede per mantenere sincronizzati gli elementi dell'interfaccia utente come le azioni della pagina.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (info: CaptureInfo) => void