browser.tabCapture

Opis

Użyj interfejsu API chrome.tabCapture, aby korzystać ze strumieni multimediów na kartach.

Uprawnienia

tabCapture

Pojęcia i użycie

Interfejs browser.tabCapture API umożliwia dostęp do obiektu MediaStream zawierającego obraz i dźwięk z bieżącej karty. Można ją wywołać tylko po wywołaniu rozszerzenia przez użytkownika, np. przez kliknięcie przycisku polecenia rozszerzenia. Działa to podobnie jak uprawnienie "activeTab".

Zachowaj dźwięk systemowy

Gdy karta uzyska 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ść true.

Aby kontynuować odtwarzanie dźwięku użytkownikowi, użyj tych opcji:

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

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

Identyfikatory strumieni

Wywołanie browser.tabCapture.getMediaStreamId() zwróci identyfikator strumienia. Aby później uzyskać dostęp do MediaStream z identyfikatora, użyj tych funkcji:

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

Ograniczenia w zakresie użytkowania

Po wywołaniu metody getMediaStreamId() obowiązują ograniczenia dotyczące tego, gdzie można używać zwróconego identyfikatora strumienia:

  • Jeśli podano consumerTabId, identyfikator może być używany przez wywołanie getUserMedia() w dowolnej ramce na danej karcie, która ma to samo źródło zabezpieczeń.
  • Jeśli nie jest określony, od wersji 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 identyfikator strumienia uzyskany w skrypcie service worker może być używany w dokumencie poza ekranem.

Przed wersją Chrome 116, gdy nie określono consumerTabId, identyfikator strumienia był ograniczony do źródła zabezpieczeń, procesu renderowania i ramki renderowania elementu wywołującego.

Więcej informacji

Więcej informacji o korzystaniu z interfejsu API browser.tabCapture znajdziesz w artykule Nagrywanie dźwięku i przechwytywanie zawartości ekranu. Pokazuje, jak używać tabCapture i powiązanych interfejsów API do rozwiązywania wielu typowych problemów.

Typy

CaptureInfo

Właściwości

  • pełny ekran

    wartość logiczna

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

  • Nowy stan przechwytywania karty.

  • tabId

    liczba

    Identyfikator karty, której stan uległ zmianie.

CaptureOptions

Właściwości

GetMediaStreamOptions

Chrome 71 lub nowsza wersja browser.* od Chrome 148

Właściwości

  • consumerTabId

    number optional

    Opcjonalny identyfikator karty, która później wywoła getUserMedia(), aby wykorzystać strumień. Jeśli nie zostanie określony, wynikowy strumień może być używany tylko przez rozszerzenie wywołujące. Strumień może być używany tylko przez ramki na danej karcie, których źródło zabezpieczeń jest zgodne ze źródłem karty konsumenta. Źródło karty musi być bezpieczne, np. HTTPS.

  • targetTabId

    number optional

    Opcjonalny identyfikator karty, która zostanie przechwycona. Jeśli nie zostanie określona, zostanie wybrana aktualnie aktywna karta. Jako karty docelowej można używać tylko kart, dla których rozszerzenie ma uprawnienie activeTab.

MediaStreamConstraint

Właściwości

  • obowiązkowe

    obiekt

  • opcjonalnie

    object opcjonalny

TabCaptureState

Typ wyliczeniowy

"pending"

"active"

"stopped"

"error"

Metody

capture()

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

Przechwytuje widoczny obszar aktywnej karty. Przechwytywanie można rozpocząć tylko na obecnie aktywnej karcie po wywołaniu rozszerzenia, podobnie jak w przypadku activeTab. Przechwytywanie jest utrzymywane podczas nawigacji na stronie na karcie i zatrzymuje się, gdy karta zostanie zamknięta lub strumień multimediów zostanie zamknięty przez rozszerzenie.

Parametry

  • Konfiguruje zwrócony strumień multimediów.

  • callback

    funkcja

    Parametr callback wygląda tak:

    (stream: LocalMediaStream) => void

    • strumień

      LocalMediaStream

getCapturedTabs()

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

Zwraca listę kart, które zażądały przechwytywania lub są przechwytywane, tzn. stan != zatrzymany i stan != błąd. Dzięki temu rozszerzenia mogą informować użytkownika, że istnieje już przechwytywanie karty, które uniemożliwiłoby nowe przechwytywanie karty (lub zapobiegać zbędnym żądaniom dotyczącym tej samej karty).

Zwroty

  • Promise<CaptureInfo[]>

    Chrome 116 lub nowsza wersja browser.* od Chrome 148

    Zwraca obiekt Promise, który jest rozwiązywany za pomocą obiektu CaptureInfo[] w przypadku przechwyconych kart.

getMediaStreamId()

Chrome 71 lub nowsza wersja browser.* od Chrome 148 
browser.tabCapture.getMediaStreamId(
  options?: GetMediaStreamOptions,
): Promise<string>

Tworzy identyfikator strumienia, aby przechwycić docelową kartę. Podobnie jak metoda chrome.tabCapture.capture(), ale zwraca identyfikator strumienia multimediów, a nie strumień multimediów, do karty klienta.

Parametry

Zwroty

  • Promise<string>

    Chrome 116 lub nowsza wersja browser.* od Chrome 148

    Zwraca obiekt Promise, który rozwiązuje się z wynikiem. Jeśli się powiedzie, wynikiem będzie nieprzezroczysty ciąg znaków, który można przekazać do interfejsu API getUserMedia(), aby wygenerować strumień multimediów odpowiadający docelowej karcie. Utworzony streamId może zostać użyty tylko raz i wygaśnie po kilku sekundach, jeśli nie zostanie użyty.

Wydarzenia

onStatusChanged

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

Zdarzenie wywoływane, gdy zmienia się stan przechwytywania karty. Dzięki temu autorzy rozszerzeń mogą śledzić stan przechwytywania kart, aby synchronizować elementy interfejsu, takie jak działania na stronie.

Parametry