chrome.tabCapture

Opis

Używaj interfejsu chrome.tabCapture API do interakcji ze strumieniami multimediów z karty.

Uprawnienia

tabCapture

Pojęcia i zastosowanie

Interfejs chrome.tabCapture API zapewnia dostęp do obszaru MediaStream z obrazem i dźwiękiem z bieżącej karty. Można ją wywołać tylko po wywołaniu rozszerzenia przez użytkownika, na przykład przez kliknięcie przycisku polecenia rozszerzenia. Jest to podobne do działania uprawnienia "activeTab".

Zachowaj dźwięk z systemu

Po uzyskaniu na potrzeby karty MediaStream dźwięk z tej karty nie będzie już odtwarzany użytkownikowi. Jest to podobne do działania funkcji getDisplayMedia(), gdy flaga suppressLocalAudioPlayback ma wartość Prawda.

Aby nadal odtwarzać dźwięk użytkownikowi, użyj tych opcji:

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

Spowoduje to utworzenie nowego AudioContext i połączenie dźwięku z elementu MediaStream karty z domyślnym miejscem docelowym.

Identyfikatory strumieni

Wywołanie chrome.tabCapture.getMediaStreamId() spowoduje zwrócenie identyfikatora strumienia. Aby później uzyskać dostęp do elementu MediaStream za pomocą identyfikatora, użyj tych poleceń:

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

Ograniczenia użytkowania

Po wywołaniu funkcji getMediaStreamId() obowiązują ograniczenia dotyczące miejsc, w których można używać zwróconego identyfikatora strumienia:

  • Jeśli określono consumerTabId, identyfikatora można użyć w wywołaniu getUserMedia() w dowolnej ramce na danej karcie, która ma to samo źródło zabezpieczenia.
  • Jeśli go nie podasz, od Chrome 116 identyfikator może być używany w dowolnej ramce z tym samym źródłem zabezpieczeń w tym samym procesie renderowania co element wywołujący. Oznacza to, że identyfikatora strumienia uzyskanych w skrypcie service worker można użyć w dokumencie nieekranowym.

W wersjach sprzed Chrome 116, gdy nie określono parametru consumerTabId, identyfikator strumienia był ograniczony zarówno do źródła zabezpieczeń, procesu renderowania, jak i renderowania ramki elementu wywołującego.

Więcej informacji

Więcej informacji o korzystaniu z interfejsu chrome.tabCapture API znajdziesz w artykule Nagrywanie dźwięku i przechwytywanie ekranu. To pokazuje, jak wykorzystać tabCapture i powiązane z nim interfejsy API w wielu typowych przypadkach użycia.

Typy

CaptureInfo

Właściwości

  • pełny ekran

    boolean

    Określa, czy element przechwytywanej karty jest w trybie pełnoekranowym.

  • Nowy stan przechwytywania karty.

  • tabId

    Liczba

    Identyfikator karty, której stan się zmienił.

CaptureOptions

Właściwości

GetMediaStreamOptions

Chrome 71 i nowsze wersje

Właściwości

  • consumerTabId

    Liczba opcjonalnie

    Opcjonalny identyfikator karty, która później wywoła funkcję getUserMedia() w celu wykorzystania strumienia. Jeśli nie określisz żadnej wartości, wygenerowanego strumienia może użyć tylko rozszerzenie wywołujące. Strumienia można używać tylko w przypadku ramek na danej karcie, których źródło zabezpieczeń jest zgodne ze źródłem karty użytkownika. Pochodzenie karty musi być bezpiecznym źródłem, np. HTTPS.

  • targetTabId

    Liczba opcjonalnie

    Opcjonalny identyfikator karty, która ma zostać przechwycona. Jeśli nie podasz żadnej wartości, zostanie wybrana bieżąca aktywna karta. Jako karty docelowej można używać tylko kart, w przypadku których rozszerzenie ma uprawnienie activeTab.

MediaStreamConstraint

Właściwości

  • obowiązkowe

    obiekt

  • opcjonalnie

    obiekt opcjonalnie

TabCaptureState

Enum

"stopped"

Metody

capture()

Tylko na pierwszym planie 
chrome.tabCapture.capture(
  options: CaptureOptions,
  callback: function,
)

Przechwytuje widoczny obszar aktywnej karty. Przechwytywanie można uruchomić tylko na aktualnie aktywnej karcie po wywołaniu rozszerzenia, podobnie jak działa activeTab. Przechwytywanie jest utrzymywane pomiędzy opcjami nawigacji na stronie na karcie i zatrzymywane po zamknięciu karty lub zamknięciu strumienia multimediów przez rozszerzenie.

Parametry

  • Konfiguruje zwrócony strumień multimediów.

  • wywołanie zwrotne

    funkcja

    Parametr callback wygląda tak: 

    (stream: LocalMediaStream)=>void

    • strumień

      LocalMediaStream

getCapturedTabs()

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

Zwraca listę kart, które zażądały przechwycenia lub są przechwytywane, tj. stan != zatrzymany oraz stan != error. Dzięki temu rozszerzenia będą informować użytkownika, że istnieje już przechwycona karta, która uniemożliwia przechwycenie nowej karty (lub zapobiega powielaniu żądań tej samej karty).

Parametry

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    (result: CaptureInfo[])=>void

Akcje powrotne

  • Promise<CaptureInfo[]>

    Chrome 116 i nowsze wersje

    Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.

getMediaStreamId()

Obietnica Chrome w wersji 71 lub nowszej 
chrome.tabCapture.getMediaStreamId(
  options?: GetMediaStreamOptions,
  callback?: function,
)

Tworzy identyfikator strumienia, aby przechwycić kartę docelową. Podobnie jak w przypadku metody chrome.tabCapture.capture(), ale zamiast strumienia multimediów na kartę klienta zwraca identyfikator strumienia multimediów.

Parametry

  • Opcje

    Opcjonalnie GetMediaStreamOptions

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    (streamId: string)=>void

    • streamId

      string,

Akcje powrotne

  • Obietnica<string>

    Chrome 116 i nowsze wersje

    Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.

Wydarzenia

onStatusChanged

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

Zdarzenie jest wywoływane po zmianie stanu karty. Dzięki temu autorzy rozszerzeń mogą śledzić stan przechwytywania kart, by synchronizować elementy interfejsu, takie jak działania na stronie.

Parametry