chrome.tabCapture

Opis

Użyj interfejsu chrome.tabCapture API, aby wchodzić w interakcje ze strumieniami multimediów z kart.

Uprawnienia

tabCapture

Przegląd

Interfejs chrome.tabCapture API umożliwia dostęp do MediaStream zawierającego obraz i dźwięk z bieżącej karty. Można go wywołać tylko wtedy, gdy użytkownik wywoła rozszerzenie, np. klikając przycisk polecenia rozszerzenia. Jest to podobne do działania uprawnienia activeTab.

Zachowywanie dźwięku z systemu

Gdy dla karty zostanie uzyskany MediaStream, dźwięk na tej karcie nie będzie już odtwarzany użytkownikowi. Jest to podobne do działania funkcji getDisplayMedia() , gdy flaga suppressLocalAudioPlayback jest ustawiona na true.

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

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 MediaStream karty z domyślnym miejscem docelowym.

Identyfikatory strumieni

Wywołanie chrome.tabCapture.getMediaStreamId zwróci identyfikator strumienia. Aby później uzyskać dostęp do MediaStream na podstawie identyfikatora, użyj tych elementów:

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

Ograniczenia w zakresie użytkowania

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

  • Jeśli określono 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 to określone, począwszy 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 wywołujący. Oznacza to, że identyfikator strumienia uzyskany w skrypcie service worker może być używany w dokumencie poza ekranem.

Przed 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 chrome.tabCapture API znajdziesz w artykule Nagrywanie dźwięku i przechwytywanie ekranu. Pokazuje on, jak używać tabCapture i powiązanych interfejsów API do rozwiązywania wielu typowych przypadków użycia.

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 się zmienił.

CaptureOptions

Właściwości

GetMediaStreamOptions

Chrome 71+

Właściwości

  • consumerTabId

    liczba opcjonalnie

    Opcjonalny identyfikator karty, która później wywoła getUserMedia() , aby użyć strumienia. Jeśli nie zostanie określony, wynikowy strumień może być używany tylko przez wywołujące rozszerzenie. 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

    liczba opcjonalnie

    Opcjonalny identyfikator karty, która będzie przechwytywana. Jeśli nie zostanie określony, zostanie wybrana bieżąca aktywna karta. Jako karta docelowa mogą być używane tylko karty, dla których rozszerzenie ma uprawnienie activeTab.

MediaStreamConstraint

Właściwości

  • obowiązkowe

    obiekt

  • opcjonalnie

    obiekt opcjonalnie

TabCaptureState

Typ wyliczeniowy

"pending"

"active"

"stopped"

"error"

Metody

capture()

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

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

Parametry

  • Konfiguruje zwracany strumień multimediów.

  • callback

    funkcja

    Parametr callback wygląda tak: 

    (stream: LocalMediaStream) => void

    • strumień

      LocalMediaStream

getCapturedTabs()

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

Zwraca listę kart, które poprosiły o przechwytywanie lub są przechwytywane, czyli status != stopped i status != error. Dzięki temu rozszerzenia mogą informować użytkownika, że istnieje już przechwytywanie karty, które uniemożliwi pomyślne przechwytywanie nowej karty (lub zapobiec zbędnym żądaniom dotyczącym tej samej karty).

Parametry

  • callback

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    (result: CaptureInfo[]) => void

Zwroty

  • Promise<CaptureInfo[]>

    Chrome 116+

    Zwraca obietnicę, która jest spełniana z CaptureInfo[] dla przechwyconych kart.

    Obietnice są obsługiwane tylko w przypadku manifestu V3 i nowszych wersji. Na innych platformach trzeba używać wywołań zwrotnych.

getMediaStreamId()

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

Tworzy identyfikator strumienia do przechwytywania karty docelowej. Podobnie jak metoda chrome.tabCapture.capture(), ale zamiast strumienia multimediów zwraca identyfikator strumienia multimediów na kartę konsumenta.

Parametry

  • Opcje

    GetMediaStreamOptions opcjonalnie

  • callback

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    (streamId: string) => void

    • streamId

      ciąg znaków

Zwroty

  • Promise<string>

    Chrome 116+

    Zwraca obietnicę, która jest spełniana z wynikiem. Jeśli operacja się powiedzie, wynikiem jest nieprzezroczysty ciąg znaków, który można przekazać do interfejsu getUserMedia() API, aby wygenerować strumień multimediów odpowiadający karcie docelowej. Utworzony streamId może być użyty tylko raz i wygasa po kilku sekundach, jeśli nie zostanie użyty.

    Obietnice są obsługiwane tylko w przypadku manifestu V3 i nowszych wersji. Na innych platformach trzeba używać wywołań zwrotnych.

Wydarzenia

onStatusChanged

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

Zdarzenie wywoływane, gdy zmieni 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