chrome.tabCapture

refresh date: 2026-09-25 robots: noindex

Описание

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

Разрешения

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

Свойства

  • аудио

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

  • audioConstraints

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

  • видео

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

  • videoConstraints

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

GetMediaStreamOptions

Chrome 71 и более поздних версий;

Свойства

  • consumerTabId

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

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

  • targetTabId

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

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

MediaStreamConstraint

Свойства

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

    Объект

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

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

TabCaptureState

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

"pending"

"active"

"stopped"

"error"

Методы

capture()

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

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

Параметры

  • Параметры

    CaptureOptions

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

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

    function

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

    (stream: LocalMediaStream) => void

    • Поток

      LocalMediaStream

getCapturedTabs()

Promise 
chrome.tabCapture.getCapturedTabs(
  callback?: function,
): Promise<CaptureInfo[]>

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

Параметры

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

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

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

    (result: CaptureInfo[]) => void

Возвраты

  • Promise<CaptureInfo[]>

    Chrome 116 и более поздних версий

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

    Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

getMediaStreamId()

Promise Chrome 71 и более поздних версий 
chrome.tabCapture.getMediaStreamId(
  options?: GetMediaStreamOptions,
  callback?: function,
): Promise<string>

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

Параметры

  • Параметры

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

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

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

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

    (streamId: string) => void

    • streamId

      string

Возвраты

  • Promise<string>

    Chrome 116 и более поздних версий

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

    Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

События

onStatusChanged

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

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

Параметры

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

    function

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

    (info: CaptureInfo) => void