chrome.tabCapture

Описание

Используйте API chrome.tabCapture для взаимодействия с медиапотоками вкладок.

Разрешения

tabCapture

Обзор

API chrome.tabCapture позволяет получить доступ к MediaStream, содержащему видео и аудио текущей вкладки. Вызов возможен только после того, как пользователь активирует расширение, например, нажав кнопку действия расширения. Это аналогично поведению разрешения activeTab .

Сохранение системного звука

Когда для вкладки получен MediaStream , воспроизведение звука в этой вкладке для пользователя прекращается. Это аналогично поведению функции getDisplayMedia() , когда флаг suppressLocalAudioPlayback установлен в значение true.

Для продолжения воспроизведения звука пользователю используйте следующее:

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

Это создает новый AudioContext и подключает MediaStream вкладки к месту назначения по умолчанию.

Идентификаторы потоков

Вызов метода chrome.tabCapture.getMediaStreamId вернет идентификатор потока. Для последующего доступа к MediaStream по этому идентификатору используйте следующий код:

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

Ограничения на использование

После вызова функции getMediaStreamId() существуют ограничения на то, где можно использовать возвращаемый идентификатор потока:

  • Если указан параметр consumerTabId , этот идентификатор может быть использован в вызове getUserMedia() в любом фрейме на данной вкладке, имеющем тот же источник безопасности.
  • Если это не указано, начиная с Chrome 116, идентификатор может использоваться в любом фрейме с тем же источником безопасности в том же процессе рендеринга, что и вызывающий объект. Это означает, что идентификатор потока, полученный в сервис-воркере, может использоваться в документе, находящемся вне экрана .

До версии Chrome 116, если consumerTabId не был указан, идентификатор потока ограничивался источником безопасности, процессом рендеринга и кадром рендеринга вызывающей стороны.

Узнать больше

To learn more about how to use the chrome.tabCapture API, see Audio recording and screen capture . This demonstrates how to use tabCapture and related APIs to solve a number of common use cases.

Типы

CaptureInfo

Характеристики

  • полноэкранный

    логический

    Указывает, находится ли элемент во вкладке, данные с которой захватываются, в полноэкранном режиме.

  • статус

    TabCaptureState

    Новый статус захвата вкладки.

  • tabId

    число

    Идентификатор вкладки, статус которой изменился.

CaptureOptions

Характеристики

  • аудио

    логический необязательный

  • аудиоограничения

    MediaStreamConstraint необязательный

  • видео

    логический необязательный

  • видеоограничения

    MediaStreamConstraint необязательный

GetMediaStreamOptions

Chrome 71+

Характеристики

  • consumerTabId

    число необязательно

    Необязательный идентификатор вкладки, которая впоследствии вызовет getUserMedia() для обработки потока. Если не указан, результирующий поток может использоваться только вызывающим расширением. Поток может использоваться только фреймами в данной вкладке, чей источник безопасности совпадает с источником вкладки-потребителя. Источник вкладки должен быть защищенным, например, HTTPS.

  • targetTabId

    число необязательно

    Optional tab id of the tab which will be captured. If not specified then the current active tab will be selected. Only tabs for which the extension has been granted the activeTab permission can be used as the target tab.

MediaStreamConstraint

Характеристики

  • обязательный

    объект

  • необязательный

    объект необязательный

TabCaptureState

Перечисление

"в ожидании"

"активный"

"остановился"

"ошибка"

Методы

capture()

Только передний план
chrome.tabCapture.capture(
  options: CaptureOptions,
  callback: function,
): void

Захватывает видимую область текущей активной вкладки. Захват может быть начат только на текущей активной вкладке после вызова расширения, аналогично тому, как работает activeTab . Захват сохраняется при переходе между страницами внутри вкладки и прекращается при закрытии вкладки или при закрытии медиапотока расширением.

Параметры

  • параметры

    CaptureOptions

    Настраивает возвращаемый медиапоток.

  • перезвонить

    функция

    Параметр callback выглядит следующим образом: 

    (stream: LocalMediaStream) =& gt;void

    • транслировать

      LocalMediaStream

getCapturedTabs()

Обещать
chrome.tabCapture.getCapturedTabs(
  callback?: function,
): Promise<CaptureInfo[]>

Returns a list of tabs that have requested capture or are being captured, ie status != stopped and status != error. This allows extensions to inform the user that there is an existing tab capture that would prevent a new tab capture from succeeding (or to prevent redundant requests for the same tab).

Параметры

  • перезвонить

    функция необязательна

    Параметр callback выглядит следующим образом: 

    (result: CaptureInfo[]) =& gt;void

Возвраты

  • Promise< CaptureInfo []>

    Chrome 116+

    Возвращает Promise, который разрешается с массивом CaptureInfo[] для захваченных вкладок.

    Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

getMediaStreamId()

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

Создает идентификатор потока для захвата целевой вкладки. Аналогичен методу chrome.tabCapture.capture(), но возвращает идентификатор медиапотока, а не сам медиапоток, для вкладки-потребителя.

Параметры

  • параметры

    GetMediaStreamOptions ( необязательный параметр)

  • перезвонить

    функция необязательна

    Параметр callback выглядит следующим образом: 

    (streamId: string) =& gt;void

    • streamId

      нить

Возвраты

  • Promise<string>

    Chrome 116+

    Returns a Promise which resolves with the result. If successful, the result is an opaque string that can be passed to the getUserMedia() API to generate a media stream that corresponds to the target tab. The created streamId can only be used once and expires after a few seconds if it is not used.

    Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

События

onStatusChanged

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

Событие срабатывает при изменении статуса захвата вкладки. Это позволяет разработчикам расширений отслеживать статус захвата вкладок для синхронизации элементов пользовательского интерфейса, таких как действия на страницах.

Параметры

  • перезвонить

    функция

    Параметр callback выглядит следующим образом: 

    (info: CaptureInfo) =& gt;void