Метод Navigator: getAutoplayPolicy()

Метод getAutoplayPolicy() API обнаружения политики автовоспроизведения предоставляет информацию о том, разрешено ли автовоспроизведение элементов медиа и аудиоконтекстов, запрещено ли оно или разрешено только в случае, если аудио выключено.

Приложения могут использовать эту информацию для обеспечения надлежащего пользовательского опыта. Например, если политика пользователя-агента допускает автовоспроизведение только незвучащего контента, приложение может выключить звук видео, чтобы оно всё равно могло автоматически воспроизводиться.

Метод может использоваться для получения общей политики автовоспроизведения для всех элементов определённого типа в документе или для конкретных элементов медиа или аудиоконтекстов.

Метод должен вызываться с одним (и только одним) из следующих трёх параметров:

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

Строка, указывающая функцию воспроизведения медиа, для которой требуется общая политика автовоспроизведения.

Поддерживаемые значения:

mediaelement

Получить общую политику автовоспроизведения для элементов медиа в документе. Элементы медиа — это HTMLMediaElement производные объекты, такие как HTMLAudioElement и HTMLVideoElement, и соответствующие теги <audio> и <video>.

audiocontext

Получить общую политику автовоспроизведения для плееров Web Audio API в документе.

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

Конкретный элемент медиа. Это должен быть HTMLMediaElement, включая производные элементы, такие как HTMLVideoElement и HTMLAudioElement.

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

Конкретный AudioContext.

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

allowed

Автовоспроизведение разрешено.

allowed-muted

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

disallowed

Автовоспроизведение запрещено.

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

TypeError

Переданный объекту метод не является допустимым типом. Допустимые типы включают HTMLMediaElement (или производный элемент, такой как HTMLVideoElement и HTMLAudioElement), или AudioContext.

"Автовоспроизведение" относится к любому элементу, который заставляет контент начинать воспроизведение без явного запроса пользователя начать воспроизведение. Это включает атрибут autoplay в HTML-элементах <video> и <audio>, и использование JavaScript-кода для запуска воспроизведения без взаимодействия пользователя.

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

Метод getAutoplayPolicy() предоставляет стандартный механизм для определения политики конкретного пользователя-агента для автовоспроизведения определённого типа или элемента контента. Это позволяет адаптировать приложение, например, автоматически выключать звук видео на сайтах, где автовоспроизведение звучащего контента запрещено, или изменять поведение приложения без автовоспроизведения.

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

if (navigator.getAutoplayPolicy("mediaelement") === "allowed") {
  // Do nothing. The content can autoplay.
} else if (navigator.getAutoplayPolicy("mediaelement") === "allowed-muted") {
  // Mute the video so it can autoplay.
} else {
  // Autoplay disallowed.
  // Add a play button to the video element.
}

Метод также может быть вызван для проверки политики автовоспроизведения для конкретного элемента медиа или аудиоконтекста. Как показано ниже, код выглядит точно так же, за исключением того, что вы передаёте конкретный элемент вместо строки type.

const video = document.getElementById("video_element_id");
if (navigator.getAutoplayPolicy(video) === "allowed") {
  // Do nothing. The content can autoplay.
} else if (navigator.getAutoplayPolicy(video) === "allowed-muted") {
  // Mute the video so it can autoplay.
} else {
  // Autoplay disallowed.
  // Add a play button to the video element.
}

При загрузке страницы, до взаимодействия пользователя со страницей или сайтом, политика автовоспроизведения для типа и отдельных элементов будет одинаковой. После того, как пользователь взаимодействует с сайтом, страницей или конкретными элементами, политика автовоспроизведения может измениться для всего type. Также возможно изменение политики для конкретного элемента, даже если общая политика для type не изменилась.

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

Код ниже демонстрирует, как проверить, поддерживается ли navigator.getAutoplayPolicy():

if (!navigator.getAutoplayPolicy) {
  log.textContent = "navigator.getAutoplayPolicy() not supported.";
} else {
  log.textContent = "navigator.getAutoplayPolicy() is supported.";
}

Результат выполнения кода на этой странице:

Этот пример демонстрирует, как проверить политику автовоспроизведения для типа элементов медиа.

Код создаёт элемент видео с атрибутом autoplay и по умолчанию без выключенного звука. Если политика автовоспроизведения равна "разрешено-выключено звук", видео будет выключено, чтобы оно могло воспроизводиться.

HTML

Нижеприведённый HTML содержит элемент div, используемый для ведения журнала, а также элемент <video> с атрибутом autoplay. По умолчанию звук не должен быть выключен, и видео должно автоматически воспроизводиться, если автовоспроизведение не заблокировано.

<div id="reportResult"></div>
<!-- Simple video example -->
<!-- 'Big Buck Bunny' licensed under CC 3.0 by the Blender foundation. Hosted by archive.org -->
<!-- Poster from peach.blender.org -->
<video
  id="bunny_vid"
  autoplay
  controls
  src="https://archive.org/download/BigBuckBunny_124/Content/big_buck_bunny_720p_surround.mp4"
  poster="https://peach.blender.org/wp-content/uploads/title_anouncement.jpg?x11217"
  width="620">
  Sorry, your browser doesn't support embedded videos, but don't worry, you can
  <a href="https://archive.org/details/BigBuckBunny_124">download it</a> and
  watch it with your favorite video player!
</video>

JavaScript

Код сообщает, поддерживается ли метод getAutoplayPolicy() и, если да, то какая политика для элементов медиа.

Если политика равна allowed-muted, только видео с выключенным звуком можно воспроизводить. В этом случае мы добавляем текст, объясняющий, что происходит, и отключаем звук видео.

const log = document.getElementById("reportResult");
const video = document.getElementById("bunny_vid");

if (!navigator.getAutoplayPolicy) {
  log.textContent =
    "navigator.getAutoplayPolicy() not supported. It may or may not autoplay, depending on the browser!";
} else {
  log.textContent = `Autoplay policy for media elements is: ${navigator.getAutoplayPolicy(
    "mediaelement",
  )}. `;

  if (navigator.getAutoplayPolicy("mediaelement") === "allowed-muted") {
    // Mute the video so it can autoplay
    video.muted = true;
    log.textContent += "Video has been muted to allow it to autoplay.";
  }
}

Обратите внимание, что вы также можете проверить allowed и disallowed.

Результат

Видео отображается ниже вместе с информацией о поддержке метода getAutoplayPolicy() и, если она поддерживается, о политике.

Если getAutoplayPolicy() поддерживается и политика равна allowed, видео будет автоматически воспроизводиться со звуком. Если политика равна allowed-muted, видео будет воспроизводиться без звука.

Обратите внимание, что если getAutoplayPolicy() не поддерживается, видео будет либо воспроизводиться с аудио, либо не будет воспроизводиться. Код не контролирует это поведение: вы зависите от реализации браузера!

Этот пример демонстрирует, как проверить, будет ли воспроизводиться определённый медиаэлемент автоматически. Он почти идентичен предыдущему примеру (проверка AudioContext также будет похожа). Обратите внимание, что определённые элементы могут воспроизводиться автоматически, даже если проверка типа mediaelement указывает, что автоматическое воспроизведение disallowed; другими словами, проверка конкретного элемента более надёжна (хотя это не имеет значения при загрузке страницы).

Код создаёт элемент видео, у которого есть атрибут autoplay. Если политика автоматического воспроизведения "разрешено-с-выключенным-звуком", видео будет воспроизводиться с выключенным звуком, чтобы разрешить его воспроизведение.

HTML

В приведенном ниже HTML есть элемент div, используемый в качестве отчётного журнала, а также элемент <video>, у которого есть атрибут autoplay. По умолчанию он не должен быть выключен, и должен автоматически воспроизводиться, если автоматическое воспроизведение не заблокировано.

<div id="reportResult"></div>
<!-- Simple video example -->
<!-- 'Big Buck Bunny' licensed under CC 3.0 by the Blender foundation. Hosted by archive.org -->
<!-- Poster from peach.blender.org -->
<video
  id="bunny_vid"
  autoplay
  controls
  src="https://archive.org/download/BigBuckBunny_124/Content/big_buck_bunny_720p_surround.mp4"
  poster="https://peach.blender.org/wp-content/uploads/title_anouncement.jpg?x11217"
  width="620">
  Sorry, your browser doesn't support embedded videos, but don't worry, you can
  <a href="https://archive.org/details/BigBuckBunny_124">download it</a> and
  watch it with your favorite video player!
</video>

JavaScript

Код сообщает, поддерживается ли метод getAutoplayPolicy(), и если поддерживается, то политика для медиаэлементов.

Если политика allowed-muted, то воспроизводиться могут только видео с выключенным звуком, поэтому код выключает звук видео.

const log = document.getElementById("reportResult");
const video = document.getElementById("bunny_vid");

if (!navigator.getAutoplayPolicy) {
  log.textContent =
    "navigator.getAutoplayPolicy() not supported. It may or may not autoplay, depending on the browser!";
} else {
  // Here we pass in the HTMLVideoElement to check
  log.textContent = `navigator.getAutoplayPolicy(video) == ${navigator.getAutoplayPolicy(
    "mediaelement",
  )}`;

  if (navigator.getAutoplayPolicy(video) === "allowed-muted") {
    // Mute the video so it can autoplay
    video.muted = true;
    log.textContent += "Video has been muted to allow it to autoplay.";
  }
}

Результат

Результат такой же, как и в предыдущем примере:

• Видео должно воспроизводиться автоматически с звуком, если возвращается allowed, и без звука, если возвращается allowed-muted.
• Если getAutoplayPolicy() не поддерживается, поведение автоматического воспроизведения видео зависит только от браузера.

• Руководство по автоматическому воспроизведению для медиа и API Web Audio