chrome.tabCapture

Descrizione

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

Autorizzazioni

tabCapture

Panoramica

L'API chrome.tabCapture 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 in quella scheda non verrà più riprodotto per l'utente. Questo è simile al comportamento 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 della scheda MediaStream viene collegato alla destinazione predefinita.

ID stream

La chiamata a 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 che ha 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 sia all'origine di sicurezza, sia 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 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 (facoltativo)

    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 (facoltativo)

    (Facoltativo) ID della scheda che verrà acquisita. Se non specificata, verrà 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 nelle pagine all'interno della scheda e si interrompe quando la scheda viene chiusa o il flusso 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()

Promessa 
chrome.tabCapture.getCapturedTabs(
  callback?: function,
): Promise<CaptureInfo[]>

Restituisce un elenco di schede che hanno richiesto l'acquisizione o che sono in fase di acquisizione, ovvero status != stopped e status != 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 evitare richieste ridondanti per la stessa scheda).

Parametri

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (result: CaptureInfo[]) => void

Resi

  • Promise<CaptureInfo[]>

    Chrome 116+

    Le promesse sono supportate solo per Manifest V3 e versioni successive, le altre piattaforme devono utilizzare i callback.

getMediaStreamId()

Promise Chrome 71+ 
chrome.tabCapture.getMediaStreamId(
  options?: GetMediaStreamOptions,
  callback?: function,
): 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

  • opzioni

    GetMediaStreamOptions facoltativo

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (streamId: string) => void

    • streamId

      stringa

Resi

  • Promise<string>

    Chrome 116+

    Le promesse sono supportate solo per Manifest V3 e versioni successive, le altre piattaforme devono utilizzare i callback.

Eventi

onStatusChanged

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

Evento attivato quando cambia lo stato di acquisizione di una scheda. 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 della pagina.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (info: CaptureInfo) => void