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

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

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

Типы

CaptureInfo

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

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

    логический

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

  • статус

    TabCaptureState

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

  • tabId

    число

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

CaptureOptions

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

  • аудио

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

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

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

  • видео

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

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

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

GetMediaStreamOptions

Chrome 71+

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

  • consumerTabId

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

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

  • targetTabId

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

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

MediaStreamConstraint

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

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

    объект

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

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

TabCaptureState

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

"в ожидании"

"активный"

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

"ошибка"

Методы

capture()

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

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

Параметры

  • параметры

    CaptureOptions

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

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

    функция

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

    (stream: LocalMediaStream) => void

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

      LocalMediaStream

getCapturedTabs()

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

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

Возвраты

  • Promise< CaptureInfo []>

    Chrome 116+

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

getMediaStreamId()

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

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

Параметры

Возвраты

  • Promise<string>

    Chrome 116+

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

События

onStatusChanged

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

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

Параметры

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

    функция

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

    (info: CaptureInfo) => void