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

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

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

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

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

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

  • идентификатор табуляции

    число

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

CaptureOptions

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

  • аудио

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

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

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

  • видео

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

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

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

GetMediaStreamOptions

Хром 71+

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

  • потребительTabId

    номер необязательно

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

  • таргеттабид

    номер необязательно

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

MediaStreamConstraint

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

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

    объект

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

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

TabCaptureState

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

"в ожидании"

"активный"

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

"ошибка"

Методы

capture()

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

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

Параметры

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

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

    функция

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

    (stream: LocalMediaStream) => void

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

      ЛокалМедиаСтрим

getCapturedTabs()

Обещать
chrome.tabCapture.getCapturedTabs(
  callback?: function,
)

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

Параметры

Возврат

  • Обещание< CaptureInfo []>

    Хром 116+

    Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

getMediaStreamId()

Обещание Chrome 71+
chrome.tabCapture.getMediaStreamId(
  options?: GetMediaStreamOptions,
  callback?: function,
)

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

Параметры

  • параметры

    GetMediaStreamOptions необязательно.

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

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

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

    (streamId: string) => void

    • идентификатор потока

      нить

Возврат

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

    Хром 116+

    Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

События

onStatusChanged

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

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

Параметры

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

    функция

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

    (info: CaptureInfo) => void