<video> элемент встраивания видео HTML

Элемент <video> HTML встраивает в документ медиаплеер с поддержкой воспроизведения видео. <video> можно использовать и для аудиоконтента, но элемент <audio> может обеспечить более подходящий пользовательский интерфейс.

Попробуйте

<video controls width="250">
  <source src="/shared-assets/videos/flower.webm" type="video/webm" />

  <source src="/shared-assets/videos/flower.mp4" type="video/mp4" />

  Download the
  <a href="/shared-assets/videos/flower.webm">WEBM</a>
  or
  <a href="/shared-assets/videos/flower.mp4">MP4</a>
  video.
</video>

В приведённом выше примере показано, как использовать элемент <video>. Как и в случае с элементом <img>, мы указываем путь к отображаемому медиафайлу в атрибуте src; можно добавить и другие атрибуты, чтобы указать такие параметры, как ширина и высота видео, необходимость автоматического воспроизведения и зацикливания или отображения стандартных элементов управления видео в браузере и так далее.

Содержимое между открывающим и закрывающим тегами <video></video> отображается как резервный вариант в браузерах, не поддерживающих этот элемент.

Атрибуты

Как и все остальные элементы HTML, этот элемент поддерживает глобальные атрибуты.

autoplay

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

Примечание: Современные браузеры блокируют автоматическое воспроизведение аудио (или видео со звуковой дорожкой без отключённого звука), поскольку сайты, автоматически воспроизводящие звук, могут вызывать у пользователей неприятные ощущения. Дополнительную информацию о правильном использовании автоматического воспроизведения см. в нашем руководстве по автоматическому воспроизведению.

Чтобы отключить автоматическое воспроизведение видео, autoplay="false" не сработает: видео будет воспроизводиться автоматически, если атрибут вообще присутствует в теге <video>. Чтобы отключить автоматическое воспроизведение, атрибут нужно полностью удалить.

Примечание: Видео с заданным атрибутом loading="lazy" не начнёт загружаться и воспроизводиться автоматически, пока элемент не окажется рядом с областью просмотра или внутри неё.

controls

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

controlslist

Указанный атрибут controlslist помогает браузеру выбирать элементы управления, отображаемые для элемента video, когда браузер показывает собственный набор элементов управления (то есть когда указан атрибут controls).

Допустимые значения: nodownload, nofullscreen и noremoteplayback.

Используйте атрибут disablepictureinpicture, если хотите отключить режим «Картинка в картинке» (и соответствующий элемент управления).

crossorigin

Этот перечисляемый атрибут указывает, следует ли использовать CORS для получения соответствующего видео. Ресурсы с поддержкой CORS можно повторно использовать в элементе <canvas>, не помечая их как загрязнённые. Допустимые значения:

anonymous

Отправляет междоменный запрос без учётных данных. Другими словами, отправляет заголовок HTTP Origin: без cookie, сертификата X.509 и без выполнения базовой HTTP-аутентификации. Если сервер не предоставляет учётные данные исходному сайту (не устанавливая заголовок HTTP Access-Control-Allow-Origin:), ресурс будет загрязнён, а его использование ограничено.

use-credentials

Отправляет междоменный запрос с учётными данными. Другими словами, отправляет заголовок HTTP Origin: с cookie, сертификатом или выполнением базовой HTTP-аутентификации. Если сервер не предоставляет учётные данные исходному сайту (через заголовок HTTP Access-Control-Allow-Credentials:), ресурс будет загрязнён, а его использование ограничено.

Если атрибут отсутствует, ресурс загружается без запроса CORS (то есть без отправки заголовка HTTP Origin:), что препятствует его использованию без загрязнения в элементах <canvas>. Если значение недопустимо, оно обрабатывается так, как если бы использовалось перечисляемое ключевое слово anonymous. Дополнительную информацию см. в разделе атрибуты настроек CORS.

disablepictureinpicture

Не позволяет браузеру предлагать контекстное меню «Картинка в картинке» или автоматически запрашивать режим «Картинка в картинке» в некоторых случаях.

disableremoteplayback

Логический атрибут, отключающий возможность удалённого воспроизведения на устройствах, подключённых с помощью проводных технологий (HDMI, DVI и т. д.) и беспроводных технологий (Miracast, Chromecast, DLNA, AirPlay и т. д.).

В Safari в качестве резервного варианта можно использовать x-webkit-airplay="deny".

height

Высота области отображения видео в пикселях CSS (только абсолютные значения; процентные значения не допускаются).

loading

Указывает, как браузер должен загружать видео (включая изображение заставки):

eager

Немедленно загружает видео, независимо от того, находится ли оно в видимой области просмотра (это значение по умолчанию).

lazy

Откладывает загрузку видео, пока оно не окажется на рассчитанном браузером расстоянии от области просмотра.

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

Хотя для всех видео рекомендуется явно указывать атрибуты width и height, чтобы избежать сдвига макета, для видео с отложенной загрузкой это особенно важно. Видео с отложенной загрузкой никогда не загрузятся, если не пересекают видимую часть элемента, даже если их загрузка изменила бы это, поскольку незагруженные видео имеют width и height, равные 0. Если содержимое, видимое в области просмотра, перекомпоновывается прямо во время чтения, это ещё сильнее ухудшает пользовательский опыт.

Видео с отложенной загрузкой, расположенные в области просмотра, могут быть ещё не видны в момент срабатывания события load объекта Window. Это происходит потому, что событие срабатывает с учётом видео с немедленной загрузкой: видео с отложенной загрузкой не учитываются, даже если при первоначальной загрузке страницы они находятся в области просмотра.

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

Примечание: Атрибут loading="lazy" также влияет на атрибуты autoplay, poster и preload, как описано в соответствующих разделах этой страницы.

loop

Логический атрибут; если он указан, браузер автоматически перейдёт к началу видео после достижения его конца.

muted

Логический атрибут, задающий состояние звука видео по умолчанию. Если он установлен, звук изначально будет отключён. Значение по умолчанию — false, то есть при воспроизведении видео будет слышен звук.

playsinline

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

poster

URL изображения, отображаемого во время загрузки видео. Если этот атрибут не указан, до появления первого кадра ничего не отображается, а затем первый кадр показывается как изображение-заставка.

Примечание: Видео с заданным атрибутом loading="lazy" загружают ресурс poster только тогда, когда видео находится рядом с областью просмотра или внутри неё.

preload

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

• none: указывает, что видео не следует предварительно загружать.
• metadata: указывает, что загружаются только метаданные видео (например, длительность).
• auto: указывает, что можно загрузить весь видеофайл, даже если не ожидается, что пользователь будет его просматривать.
• пустая строка: синоним значения auto.

Значение по умолчанию различается в разных браузерах. Спецификация рекомендует задавать значение metadata.

Примечание:

• Для видео с заданным атрибутом loading="lazy" поведение preload применяется только тогда, когда видео находится рядом с областью просмотра или внутри неё.
• Атрибут autoplay имеет приоритет над preload. Если указан autoplay, браузеру, очевидно, потребуется начать загрузку видео для воспроизведения.
• Спецификация не обязывает браузер следовать значению этого атрибута; это лишь подсказка.

src

URL встраиваемого видео. Этот атрибут необязателен: вместо него можно использовать элемент <source> внутри блока видео, чтобы указать встраиваемое видео.

width

Ширина области отображения видео в пикселях CSS (только абсолютные значения; процентные значения не допускаются).

События

audioprocess

Входной буфер ScriptProcessorNode готов к обработке.

canplay

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

canplaythrough

Браузер считает, что может воспроизвести медиафайл до конца без остановки для буферизации содержимого.

complete

Рендеринг OfflineAudioContext завершён.

durationchange

Атрибут duration был обновлён.

emptied

Медиафайл стал пустым; например, это событие отправляется, если медиафайл уже был загружен (полностью или частично), а для его повторной загрузки вызывается метод load().

ended

Воспроизведение остановлено, поскольку достигнут конец медиафайла.

error

При получении данных медиафайла произошла ошибка либо формат ресурса не поддерживается для воспроизведения медиа.

loadeddata

Загрузка первого кадра медиафайла завершена.

loadedmetadata

Метаданные загружены.

loadstart

Срабатывает, когда браузер начинает загружать ресурс.

pause

Воспроизведение приостановлено.

play

Воспроизведение началось.

playing

Воспроизведение готово возобновиться после паузы или задержки из-за нехватки данных.

progress

Срабатывает периодически, пока браузер загружает ресурс.

ratechange

Скорость воспроизведения изменилась.

seeked

Операция перемотки завершена.

seeking

Операция перемотки началась.

stalled

Пользовательский агент пытается получить данные медиафайла, но данные неожиданно не поступают.

suspend

Загрузка данных медиафайла приостановлена.

timeupdate

Время, указанное атрибутом currentTime, обновлено.

volumechange

Громкость изменилась.

waiting

Воспроизведение остановлено из-за временной нехватки данных.

Примечания по использованию

Не все браузеры поддерживают одинаковые форматы видео; можно указать несколько источников во вложенных элементах <source>, и браузер использует первый из поддерживаемых.

<video controls>
  <source src="myVideo.webm" type="video/webm" />
  <source src="myVideo.mp4" type="video/mp4" />
  <p>
    Your browser doesn't support HTML video. Here is a
    <a href="myVideo.mp4" download="myVideo.mp4">link to the video</a> instead.
  </p>
</video>

При использовании элементов <source> браузер пытается последовательно загрузить каждый источник. Если источник не загружается (например, из-за недействительного URL или неподдерживаемого формата), браузер пытается загрузить следующий и так далее. После сбоя всех источников на элементе <video> срабатывает событие error; события error не срабатывают для каждого отдельного элемента <source>.

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

Другие примечания по использованию:

• Если не указать атрибут controls, видео не будет содержать стандартные элементы управления браузера; можно создать собственные элементы управления с помощью JavaScript и API HTMLMediaElement. Подробнее см. в разделе Создание кроссбраузерного видеоплеера.
• Для точного управления видеоконтентом (и аудиоконтентом) элементы HTMLMediaElement генерируют множество различных событий. Помимо возможности управлять воспроизведением, эти события позволяют отслеживать ход загрузки и воспроизведения медиафайла, а также состояние и позицию воспроизведения.
• Свойство object-position позволяет настраивать положение видео в кадре элемента, а свойство object-fit — управлять тем, как размер видео подгоняется под кадр.
• Чтобы отображать субтитры или подписи вместе с видео, можно использовать JavaScript и элемент <track> с форматом WebVTT. Дополнительную информацию см. в разделе Добавление подписей и субтитров к видео HTML.
• Для воспроизведения аудиофайлов можно использовать элемент <video>. Это может быть полезно, например, если к аудио нужно добавить транскрипт WebVTT, поскольку элемент <audio> не позволяет добавлять подписи с помощью WebVTT.
• Чтобы проверить резервное содержимое в браузерах, поддерживающих этот элемент, можно заменить <video> несуществующим элементом, например <notavideo>.

Хороший общий источник информации об использовании HTML <video> — вводное руководство Видео и аудио в HTML.

Стилизация с помощью CSS

Элемент <video> — замещаемый элемент: по умолчанию значение его свойства display равно inline, однако ширина и высота элемента по умолчанию в области просмотра определяются встраиваемым видео.

Особых требований к стилизации <video> нет; обычно ему задают значение block для свойства display, чтобы упростить позиционирование, изменение размера и другие операции, а затем при необходимости задают стили и параметры макета. В разделе Основы стилизации видеоплеера приведены полезные приёмы стилизации.

Добавление субтитров и других текстовых дорожек с временной синхронизацией

Текстовые дорожки с временной синхронизацией для субтитров, скрытых подписей, заголовков глав и других целей можно добавить декларативно, вложив элемент <track>. Дорожки задаются в формате Web Video Text Tracks File Format (WebVTT) (файлы .vtt).

Например, приведённый ниже HTML-код включает файл «captions.vtt», который будет использоваться для наложения скрытых подписей на видео, если пользователь включит подписи.

<video controls src="video.webm">
  <track default kind="captions" src="captions.vtt" />
</video>

Текстовые дорожки с временной синхронизацией также можно добавлять программно с помощью API WebVTT.

Отслеживание добавления и удаления дорожек

Можно отслеживать добавление дорожек в элемент <video> и их удаление с помощью событий addtrack и removetrack. Однако эти события отправляются не непосредственно самому элементу <video>. Вместо этого они отправляются объекту списка дорожек внутри <video> элемента HTMLMediaElement, соответствующему типу добавленной дорожки:

HTMLMediaElement.audioTracks

AudioTrackList, содержащий все аудиодорожки медиаэлемента. Добавьте к этому объекту прослушиватель для addtrack, чтобы получать уведомления о добавлении в элемент новых аудиодорожек.

HTMLMediaElement.videoTracks

VideoTrackList, содержащий все видеодорожки медиаэлемента. Добавьте к этому объекту прослушиватель addtrack, чтобы получать уведомления о добавлении в элемент видеодорожек.

HTMLMediaElement.textTracks

TextTrackList, содержащий все текстовые дорожки медиаэлемента (используемые для субтитров, скрытых подписей и так далее). Добавьте к этому объекту прослушиватель addtrack, чтобы получать уведомления о добавлении в элемент текстовых дорожек.

Например, чтобы отслеживать добавление аудиодорожек в элемент <video> и их удаление, можно использовать следующий код:

const elem = document.querySelector("video");

elem.audioTracks.onaddtrack = (event) => {
  trackEditor.addTrack(event.track);
};

elem.audioTracks.onremovetrack = (event) => {
  trackEditor.removeTrack(event.track);
};

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

Для прослушивания событий addtrack и removetrack также можно использовать addEventListener().

Поддержка видео на сервере

Если на сервере неправильно задан тип MIME для видео, оно может не отображаться или отображаться в виде серого прямоугольника с крестиком (если JavaScript включён).

Если для размещения видео WebM используется Apache Web Server, эту проблему можно исправить, добавив расширения видеофайлов к типу MIME video/webm (самое распространённое расширение файлов WebM — .webm). Для этого отредактируйте файл mime.types в /etc/apache или используйте директиву конфигурации AddType в httpd.conf:

AddType video/webm .webm

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

Доступность

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

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

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

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

14
00:03:14 --> 00:03:18
[Dramatic rock music]

15
00:03:19 --> 00:03:21
[whispering] What's that off in the distance?

16
00:03:22 --> 00:03:24
It's… it's a…

16 00:03:25 --> 00:03:32
[Loud thumping]
[Dishes clattering]

Подписи не должны закрывать главный объект видео. Их положение можно настроить с помощью параметра субтитров VTT align.

• Формат Web Video Text Tracks (WebVTT)
• WebAIM: подписи, транскрипты и аудиоописания
• Понимание MDN WCAG: пояснения к руководству 1.2
• Понимание критерия успеха 1.2.1 | Понимание WCAG 2.0 от W3C
• Понимание критерия успеха 1.2.2 | Понимание WCAG 2.0 от W3C

Примеры

Один источник

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

HTML

<!-- Basic video example -->
<!-- 'Big Buck Bunny' licensed under CC 3.0 by the Blender foundation. Hosted by archive.org -->
<!-- Poster from peach.blender.org -->
<video
  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>

Результат

Пока видео не начнёт воспроизводиться, вместо него отображается изображение, указанное в атрибуте poster. Если браузер не поддерживает воспроизведение видео, отображается резервный текст.

Несколько источников

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

HTML

<!-- Using multiple sources as fallbacks for a video tag -->
<!-- 'Elephants Dream' by Orange Open Movie Project Studio, licensed under CC-3.0, hosted by archive.org -->
<!-- Poster hosted by Wikimedia -->
<video
  width="620"
  controls
  poster="https://upload.wikimedia.org/wikipedia/commons/e/e8/Elephants_Dream_s5_both.jpg">
  <source
    src="https://archive.org/download/ElephantsDream/ed_hd.avi"
    type="video/avi" />
  <source
    src="https://archive.org/download/ElephantsDream/ed_1024_512kb.mp4"
    type="video/mp4" />

  Sorry, your browser doesn't support embedded videos, but don't worry, you can
  <a
    href="https://archive.org/download/ElephantsDream/ed_1024_512kb.mp4"
    download="ed_1024_512kb.mp4">
    download the MP4
  </a>
  and watch it with your favorite video player!
</video>

Результат

Сначала проверяется AVI. Если его не удаётся воспроизвести, проверяется MP4. Если элемент video не поддерживается, отображается сообщение-запасной вариант, но не в случае, если не удаётся загрузить ни один из источников.

Некоторые типы медиафайлов позволяют указать более подробную информацию с помощью параметра codecs в строке типа файла. Например, video/webm; codecs="vp8, vorbis" сообщает, что файл представляет собой видео WebM, в котором для видео используется VP8, а для аудио — Vorbis.

Техническая сводка

Спецификации

Совместимость с браузерами

См. также

• Руководство по типам и форматам медиа в интернете

  • Форматы медиаконтейнеров (типы файлов)
  • Руководство по видеокодекам для веба
  • Руководство по аудиокодекам для веба

• Позиционирование и изменение размера изображения в его рамке: object-position и object-fit

• <audio>

• Видео и аудио в HTML

• Обработка видео с помощью canvas

• Настройка серверов для медиа в формате Ogg