MediaDevices: метод getDisplayMedia()

Метод getDisplayMedia() интерфейса MediaDevices предлагает пользователю выбрать и предоставить разрешение на захват содержимого дисплея или его части (например, окна) в виде MediaStream.

Полученный поток затем можно записать с помощью API записи потока MediaStream или передать в качестве части сессии WebRTC.

Дополнительные сведения и примеры см. в разделе Использование API захвата экрана.

options Необязательно

Необязательный объект, определяющий требования к возвращаемому MediaStream. Опции для getDisplayMedia() работают так же, как ограничения для метода MediaDevices.getUserMedia(), хотя в этом случае можно указать только audio и video. Список возможных свойств опций для getDisplayMedia() следующий:

video Необязательно

Булево значение или экземпляр MediaTrackConstraints; значение по умолчанию — true. Если этот параметр опущен или установлен в true, в потоке будет присутствовать видеодорожка. Значение true указывает, что возвращаемый MediaStream будет содержать видеодорожку. Поскольку getDisplayMedia() требует видеодорожки, если этот параметр установлен в false, обещание отклонится с ошибкой TypeError.

audio Необязательно

Булево значение или экземпляр MediaTrackConstraints; значение по умолчанию — false. Значение true указывает, что возвращаемый MediaStream будет содержать аудиодорожку, если аудио поддерживается и доступно для поверхности дисплея, выбранной пользователем.

controller Экспериментальная Необязательно

Экземпляр объекта CaptureController с методами, которые можно использовать для дальнейшего управления сессией захвата, если он включён.

monitorTypeSurfaces Необязательно

Перечисление, указывающее, должен ли браузер предлагать целые экраны в параметрах захвата экрана пользователю наряду с параметрами вкладок и окон. Этот параметр предназначен для защиты компаний от утечки конфиденциальной информации из-за ошибки сотрудника при использовании приложений для видеоконференций. Возможные значения — include, что предполагает включение параметров экрана, и exclude, что предполагает их исключение. Значение по умолчанию не предписано спецификацией; см. раздел Совместимость браузеров для значений по умолчанию для отдельных браузеров.

Примечание: Вы не можете установить monitorTypeSurfaces: "exclude" одновременно с displaySurface: "monitor", так как эти два параметра противоречат друг другу. Попытка сделать это приведёт к отказу вызова getDisplayMedia() с ошибкой TypeError.

preferCurrentTab Нестандартный Экспериментальная Необязательно

Булево значение; значение true указывает браузеру предложить текущую вкладку в качестве наиболее важного источника захвата, т.е. отдельным пунктом «Эта вкладка» в параметрах «Выберите, что нужно поделиться». Это полезно, так как многие типы приложений обычно хотят поделиться только текущей вкладкой. Например, приложение для демонстрации слайдов может позволить пользователю транслировать текущую вкладку с презентацией на виртуальную конференцию. Значение по умолчанию не предписано спецификацией; см. раздел Совместимость браузеров для значений по умолчанию для отдельных браузеров.

selfBrowserSurface Экспериментальная Необязательно

Перечисление, указывающее, должен ли браузер позволить пользователю выбрать текущую вкладку для захвата. Это помогает избежать эффекта «бесконечного зеркала» при случайном обмене собственным дисплеем приложением для видеоконференций. Возможные значения — include, что подразумевает включение текущей вкладки в список предложений для захвата, и exclude, что подразумевает её исключение. Значение по умолчанию не предписано спецификацией; см. раздел Совместимость браузеров для значений по умолчанию для отдельных браузеров.

surfaceSwitching Экспериментальная Необязательно

Перечисление, указывающее, должен ли браузер отображать элемент управления для динамического переключения вкладки во время совместного использования экрана. Это намного удобнее, чем проходить весь процесс совместного использования заново каждый раз, когда пользователь хочет переключиться на другую вкладку. Возможные значения — include, что подразумевает включение элемента управления, и exclude, что подразумевает его отсутствие. Значение по умолчанию не предписано спецификацией; см. раздел Совместимость браузеров для значений по умолчанию для отдельных браузеров.

systemAudio Экспериментальная Необязательно

Перечисление, указывающее, должен ли браузер включать системный звук среди возможных источников аудио, предлагаемых пользователю. Возможные значения — include, что подразумевает включение системного звука в список вариантов, и exclude, что подразумевает его исключение. Значение по умолчанию не предписано спецификацией; см. раздел Совместимость браузеров для значений по умолчанию для отдельных браузеров.

monitorTypeSurfaces Экспериментальная Необязательно

Перечисление, указывающее, хочет ли приложение, чтобы пользовательский агент предлагал пользователю возможность выбора поверхностей дисплея, тип которых — монитор. Возможные значения — include, что подразумевает включение поверхностей дисплея, тип которых — монитор, и exclude, что подразумевает их исключение. Значение по умолчанию не предписано спецификацией; см. раздел Совместимость браузеров для значений по умолчанию для отдельных браузеров.

Обещание Promise, которое разрешается в MediaStream, содержащий видеодорожку, содержимое которой взято с выбранной пользователем области экрана, а также необязательную аудиодорожку.

AbortError DOMException

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

InvalidStateError DOMException

Бросается, если вызов getDisplayMedia() не был выполнен из кода, выполняемого из-за временного активации, например, обработчика событий. Или если контекст браузера не полностью активен или не сфокусирован. Или если опции controller уже использовались при создании другого MediaStream.

NotAllowedError DOMException

Бросается, если пользователь отказал в разрешении доступа к области экрана, или текущая сессия просмотра не имеет разрешения на совместное использование экрана (например, по политике Permissions Policy).

NotFoundError DOMException

Бросается, если нет доступных источников видео с экрана для захвата.

NotReadableError DOMException

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

OverconstrainedError DOMException

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

TypeError

Бросается, если указанные options включают значения, которые не разрешены при вызове getDisplayMedia(), например, свойство video установлено в false, или если какие-либо указанные MediaTrackConstraints не разрешены. Значения min и exact не разрешены в ограничениях, используемых в вызовах getDisplayMedia().

Поскольку getDisplayMedia() может использоваться в злонамеренных целях, это может быть источником серьезных проблем с конфиденциальностью и безопасностью. По этой причине спецификация подробно описывает меры, которые браузеры должны принять для обеспечения полной поддержки getDisplayMedia().

• Указанные параметры не могут использоваться для ограничения выбора, доступного пользователю. Вместо этого они должны применяться после того, как пользователь выберет источник, чтобы сгенерировать выходные данные, соответствующие параметрам.
• Разрешение на использование getDisplayMedia() не может сохраняться для повторного использования. Пользователь должен получать разрешение каждый раз.
• Временная активация пользователя обязательна. Пользователь должен взаимодействовать со страницей или элементом пользовательского интерфейса, чтобы эта функция работала.
• Браузеры рекомендуют отображать предупреждение пользователям о совместном использовании дисплеев или окон, содержащих браузеры, и следить за тем, какой другой контент может быть захвачен и показан другим пользователям.

В примере ниже создается метод startCapture(), который инициирует захват экрана с заданными параметрами, указанными параметром displayMediaOptions.

const displayMediaOptions = {
  video: {
    displaySurface: "browser",
  },
  audio: {
    suppressLocalAudioPlayback: false,
  },
  preferCurrentTab: false,
  selfBrowserSurface: "exclude",
  systemAudio: "include",
  surfaceSwitching: "include",
  monitorTypeSurfaces: "include",
};

async function startCapture(displayMediaOptions) {
  let captureStream;

  try {
    captureStream =
      await navigator.mediaDevices.getDisplayMedia(displayMediaOptions);
  } catch (err) {
    console.error(`Error: ${err}`);
  }
  return captureStream;
}

В данном примере используется await для асинхронного ожидания разрешения getDisplayMedia() с MediaStream, который содержит содержимое дисплея в соответствии с указанными параметрами. Затем поток возвращается вызывающей стороне для использования, возможно, для добавления в вызов WebRTC с помощью RTCPeerConnection.addTrack() для добавления видеодорожки из потока.

• API захвата экрана
• Использование API захвата экрана
• API захвата медиа и потоков
• API WebRTC
• getUserMedia(): Запись медиа с камеры и/или микрофона