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

Хром 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[]>

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

Возврат

getMediaStreamId()

Хром 71+
chrome.tabCapture.getMediaStreamId(
  options?: GetMediaStreamOptions,
): Promise<string>

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

Параметры

Возврат

  • Обещание<строка>

    Хром 116+

События

onStatusChanged

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

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

Параметры

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

    функция

    Параметр callback выглядит так: 

    (info: CaptureInfo) => void