chrome.tabCapture

Opis

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

Uprawnienia

tabCapture

Pojęcia i zastosowanie

Interfejs chrome.tabCapture API umożliwia dostęp do obiektu MediaStream zawierającego wideo i dźwięk z bieżącej karty. Można go wywołać tylko po tym, jak użytkownik uruchomi rozszerzenie, np. klikając przycisk działania rozszerzenia. Działa to podobnie jak uprawnienie "activeTab".

Zachowaj dźwięk z systemu

Gdy karta uzyska MediaStream, dźwięk na tej karcie nie będzie już odtwarzany użytkownikowi. Działa to podobnie do funkcji getDisplayMedia(), gdy flaga suppressLocalAudioPlayback ma wartość true.

Aby nadal odtwarzać dźwięk użytkownikowi, użyj tego kodu:

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

Identyfikatory strumieni

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

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

Ograniczenia w zakresie użytkowania

Po wywołaniu funkcji getMediaStreamId() istnieją 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 zostanie to określone, począwszy od Chrome 116, identyfikator może być używany w dowolnej ramce o tym samym pochodzeniu zabezpieczeń w tym samym procesie renderowania co wywołujący. Oznacza to, że identyfikator strumienia danych uzyskany w usłudze 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 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, jak używać interfejsów API tabCapture i powiązanych z nimi interfejsów API w celu rozwiązania wielu typowych problemów.

Typy

CaptureInfo

Właściwości

  • pełny ekran

    Wartość logiczna

    Czy element na karcie, która jest rejestrowana, 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 w wersji 71 lub nowszej

Właściwości

  • consumerTabId

    number opcjonalny

    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 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

    number opcjonalny

    Opcjonalny identyfikator karty, która zostanie zarejestrowana. Jeśli nie zostanie podana, zostanie wybrana bieżąca aktywna karta. Jako kartę docelową można wykorzystać tylko te karty, w przypadku których rozszerzenie ma uprawnienie activeTab.

MediaStreamConstraint

Właściwości

  • obowiązkowe

    obiekt

  • opcjonalnie

    obiekt opcjonalny

TabCaptureState

Typ wyliczeniowy

„pending”

„aktywny”

„zatrzymano”

„error”

Metody

capture()

Tylko pierwszy plan 
chrome.tabCapture.capture(
  options: CaptureOptions,
  callback: function,
): void

Zapisuje widoczny obszar aktywnej karty. Przechwytywanie można rozpocząć tylko na aktualnie aktywnej karcie po wywołaniu rozszerzenia, podobnie jak w przypadku funkcji activeTab. Przechwytywanie jest utrzymywane podczas nawigacji po stronie w obrębie karty i zatrzymuje się po zamknięciu karty lub strumienia multimediów przez rozszerzenie.

Parametry

  • Konfiguruje zwracany strumień multimediów.

  • callback

    funkcja

    Parametr callback wygląda tak:

    (stream: LocalMediaStream) => void

    • strumień

      LocalMediaStream

getCapturedTabs()

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

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

Zwroty

  • Promise<CaptureInfo[]>

    Chrome 116 lub nowsza

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

getMediaStreamId()

Chrome w wersji 71 lub nowszej 
chrome.tabCapture.getMediaStreamId(
  options?: GetMediaStreamOptions,
): Promise<string>

Tworzy identyfikator strumienia, aby rejestrować kartę docelową. Podobnie jak metoda chrome.tabCapture.capture(), ale zamiast strumienia multimediów zwraca do karty konsumenckiej identyfikator strumienia multimediów.

Parametry

Zwroty

  • Promise<string>

    Chrome 116 lub nowsza

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

Wydarzenia

onStatusChanged

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

Zdarzenie wywoływane, gdy zmienia się stan przechwytywania karty. Umożliwia to autorom rozszerzeń śledzenie stanu przechwytywania kart, aby elementy interfejsu, takie jak działania na stronie, były zsynchronizowane.

Parametry