browser.tabCapture

Описание

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

Разрешения

tabCapture

Основные понятия и использование

API browser.tabCapture позволяет получить доступ к объекту MediaStream, содержащему видео и аудио текущей вкладки. Его можно вызвать только после того, как пользователь запустит расширение, например нажав кнопку действия. Это похоже на поведение разрешения "activeTab".

Сохранить системное аудио

Если для вкладки получен MediaStream, аудио на ней больше не будет воспроизводиться. Это похоже на поведение функции getDisplayMedia(), когда для флага suppressLocalAudioPlayback задано значение true.

Чтобы продолжить воспроизведение аудио, используйте следующее:

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

При этом создается новый объект AudioContext, а аудио из объекта MediaStream вкладки подключается к месту назначения по умолчанию.

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

Вызов browser.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 не был указан, идентификатор потока ограничивался источником безопасности, процессом отрисовки и фреймом отрисовки вызывающего объекта.

Подробнее…

Подробнее о том, как использовать API browser.tabCapture, рассказывается в статье Запись аудио и захват экрана. В нем показано, как использовать tabCapture и связанные API для решения ряда распространенных задач.

Типы

CaptureInfo

Свойства

  • полноэкранный режим

    Логическое значение

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

  • статус

    TabCaptureState

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

  • tabId

    число

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

CaptureOptions

Свойства

  • аудио

    Логическое значение (необязательно)

  • audioConstraints

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

  • видео

    Логическое значение (необязательно)

  • videoConstraints

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

GetMediaStreamOptions

Chrome 71 и более поздних версий browser.* начиная с Chrome 148

Свойства

  • consumerTabId

    number (необязательно)

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

  • targetTabId

    number (необязательно)

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

MediaStreamConstraint

Свойства

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

    Объект

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

    Объект (необязательно)

TabCaptureState

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

"pending"

"active"

"stopped"

"error"

Методы

capture()

Только в активном режиме 
browser.tabCapture.capture(
  options: CaptureOptions,
  callback: function,
): void

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

Параметры

  • Параметры

    CaptureOptions

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

  • обратный вызов

    function

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

    (stream: LocalMediaStream) => void

    • Поток

      LocalMediaStream

getCapturedTabs()

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

Возвращает список вкладок, для которых запрошена запись или которые записываются, то есть статус не равен "остановлено" и "ошибка". Это позволяет расширениям сообщать пользователю о том, что запись вкладки уже выполняется и новую начать нельзя (или предотвращать повторные запросы для одной и той же вкладки).

Возвраты

  • Promise<CaptureInfo[]>

    Chrome 116+ browser.* начиная с Chrome 148

    Возвращает объект Promise, который распознается с помощью CaptureInfo[] для записанных вкладок.

getMediaStreamId()

Chrome 71 и более поздних версий browser.* начиная с Chrome 148 
browser.tabCapture.getMediaStreamId(
  options?: GetMediaStreamOptions,
): Promise<string>

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

Параметры

Возвраты

  • Promise<string>

    Chrome 116+ browser.* начиная с Chrome 148

    Возвращает объект Promise, который распознается с результатом. В случае успеха результатом будет непрозрачная строка, которую можно передать в API getUserMedia(), чтобы сгенерировать медиапоток, соответствующий целевой вкладке. Созданный streamId можно использовать только один раз. Если он не будет использован, то через несколько секунд срок его действия истечет.

События

onStatusChanged

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

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

Параметры

  • обратный вызов

    function

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

    (info: CaptureInfo) => void