Тег video (от английского video, «видео») показывает на странице видеоролик с готовым плеером. Он парный: открывающий и закрывающий теги обязательны, а то, что записано между ними, браузер не выводит. Файл указывают в атрибуте src или вложенными тегами source, а чтобы появились кнопки управления, нужен атрибут controls.
Дальше разобраны все атрибуты, форматы, автозапуск, загрузка, размеры, стили, работа из JavaScript и причины, по которым ролик не играет. Выбор файла из нескольких вариантов подробно описан на странице о теге source, а для звука без картинки есть похожий тег audio.
<video src="film.webm" controls width="640">
Ваш браузер не показывает видео.
</video>
В этой статье
- Тег video в HTML: что это и как его записывать
- Атрибуты тега video: таблица и связь со свойствами
- Атрибут controls у тега video и свой интерфейс на JavaScript
- Форматы видео для тега video: MP4, WebM и кодеки
- Атрибуты autoplay, muted и loop у тега video: когда видео запускается само
- Атрибут preload у тега video: none, metadata и auto
- Атрибуты poster, width и height у тега video: размер блока до загрузки
- Стили тега video в CSS: object-fit, aspect-ratio и зазор снизу
- Тег video в JavaScript: свойства и методы
- События тега video: порядок от loadstart до ended
- Почему тег video не воспроизводится: коды ошибок и причины
Тег video в HTML: что это и как его записывать
Сначала о том, как устроен тег и чем запись с одним файлом отличается от записи с несколькими.
По стандарту внутри video записывают либо ничего, если файл задан атрибутом src, либо один или несколько source. После них идут необязательные теги track для субтитров. Если у video есть свой src, вложенные source игнорируются. Текст между тегами (запасное содержимое) нужен только очень старым браузерам, которые не знают video: современный браузер его не показывает, в примере ниже строка «Текст внутри video на экране» это подтверждает. Субтитры и описания для людей с нарушениями слуха и зрения так не передают, для них служит track.
<video src="film.webm" controls></video>
<video controls>
<source src="film.avi" type="video/avi">
<source src="film.webm" type="video/webm">
</video>
Пример: video с одним src, с несколькими source и с текстом внутри
Три кнопки строят настоящий video в вашем браузере. Первый source во втором варианте с неподходящим type пропускается, а строка под плеером сообщает, открылся ли файл и виден ли текст внутри тега.
Пока файл не загружен, блок video занимает 300 на 150 пикселей, а потом подстраивается под размер ролика. Из-за этого страница может сдвинуться; как этого избежать, описано в разделе про размеры. По умолчанию video — строчный элемент, как img; подробнее об этом в разделе про CSS. Ответы на частые вопросы по тегу есть и в уроке курса.
Атрибуты тега video: таблица и связь со свойствами
У тега больше десяти собственных атрибутов, и большинство из них булевы: достаточно записать имя.
Булев атрибут включён, если он записан, и выключен, если его нет. Значение после знака равенства не нужно: controls и controls="" работают одинаково. Остальные атрибуты принимают значение: адрес файла, размер, слово из набора.
<video src="film.webm" controls loop muted
poster="cover.jpg" width="640" height="360"
preload="metadata" playsinline></video>
| Атрибут | Что делает | Пример записи |
|---|---|---|
src | Адрес файла. Если он есть, вложенные source игнорируются | src="film.webm" |
controls | Показывает встроенные кнопки: пуск, перемотку, звук, полный экран | controls |
autoplay | Запускает видео, как только оно готово, если браузер разрешает | autoplay muted |
loop | После конца начинает сначала | loop |
muted | Выключает звук при создании элемента | muted |
preload | Подсказывает, сколько загружать заранее: none, metadata, auto | preload="none" |
poster | Адрес картинки, которую видно, пока видео не запущено | poster="cover.jpg" |
width и height | Размер блока в пикселях | width="640" height="360" |
playsinline | Подсказка для iPhone: играть на странице, а не на весь экран | playsinline |
crossorigin | Включает проверку CORS для файла с другого сайта: anonymous или use-credentials | crossorigin="anonymous" |
disablepictureinpicture | Убирает кнопку картинка в картинке | controls disablepictureinpicture |
controlslist | Скрывает отдельные кнопки плеера: nodownload, nofullscreen, noremoteplayback (понимает Chrome) | controls controlslist="nodownload" |
disableremoteplayback | Запрещает передачу на другой экран | controls disableremoteplayback |
Атрибуты задают только начальное состояние. В JavaScript у объекта video есть одноимённые свойства, и они могут расходиться с атрибутами. Например, muted, добавленный после создания, звук не выключает, а autoplay, добавленный когда файл уже выбран, ничего не запускает. Устаревший атрибут из стандарта удалён, вместо него работает autobufferpreload. Свойство defaultMuted показывает атрибут, а muted — текущее состояние звука.
Пример: атрибуты video и свойства, которые от них зависят
Кнопки включают и выключают атрибуты у уже созданного видео. Строка со свойствами берётся прямо из объекта, а кнопка «Создать заново» строит ролик сразу с выбранными атрибутами.
Атрибут controls у тега video и свой интерфейс на JavaScript
Встроенный плеер включается одним атрибутом, а когда его не хватает, кнопки строят сами.
Без controls видео выглядит как картинка: кнопок нет, нажатием его не запустить. Такой режим нужен для фоновых роликов и для собственного интерфейса. Встроенный плеер уже умеет клавиатуру, полный экран и субтитры, поэтому свой нужен, когда важен фирменный вид. Кнопки в нём записывают тегом button, чтобы они работали с клавиатуры (между ними переходят клавишей Tab), а перемотку делают тегом input с типом range.
const video = document.querySelector("video");
playButton.addEventListener("click", () => {
if (video.paused) video.play();
else video.pause();
});
range.addEventListener("input", () => {
video.currentTime = range.value / 1000 * video.duration;
});
Пример: свой интерфейс для video без controls
Видео ниже записано без controls. Кнопки, перемотка и счётчик времени работают только за счёт свойств и методов объекта video.
Отдельные кнопки встроенного плеера можно убрать атрибутом controlslist. Это понимает Chrome, другие браузеры значение игнорируют, поэтому не опирайтесь на него как на защиту от скачивания: файл всё равно доступен по адресу.
Форматы видео для тега video: MP4, WebM и кодеки
Видео состоит из контейнера и кодека, и браузер воспроизводит файл только если понимает оба.
Контейнер (MP4, WebM, Ogg) упаковывает дорожки, кодек (H.264, VP9, AV1) сжимает изображение. Расширение файла о кодеке ничего не говорит: внутри MP4 может лежать и H.264, и AV1. Чаще всего для video готовят два файла: MP4 с H.264 как самый совместимый вариант и WebM с VP9 или AV1 как более лёгкий. Поддержка зависит от браузера, его версии и устройства, поэтому формат проверяют методом canPlayType.
| Контейнер | Кодеки | Пример записи |
|---|---|---|
| MP4 | H.264 (avc1), H.265 (hvc1), AV1 (av01) и звук AAC | type='video/mp4; codecs="avc1.42E01E, mp4a.40.2"' |
| WebM | VP8, VP9, AV1 и звук Vorbis или Opus | type='video/webm; codecs="vp9, opus"' |
| Ogg | Theora и звук Vorbis, формат устарел | type="video/ogg" |
<video controls width="640">
<source src="film.webm"
type='video/webm; codecs="vp9, opus"'>
<source src="film.mp4" type="video/mp4">
</video>
Пример: форматы и кодеки тега video в вашем браузере
Таблицу строит ваш браузер методом canPlayType, поэтому у разных читателей она получится разной.
Как браузер перебирает несколько source и когда пропускает неподходящий, подробно разобрано на странице о теге source. Файлы с сервера должны отдаваться с правильным типом MIME (video/mp4, video/webm): об этом напоминает справочник MDN. Сервер должен поддерживать частичную загрузку (заголовок Range), иначе не заработает перемотка.
Атрибуты autoplay, muted и loop у тега video: когда видео запускается само
Автозапуск удобен для фоновых роликов, но браузеры ограничивают его, чтобы страницы не включали звук без спроса.
Атрибут autoplay запускает видео, как только оно готово, а loop повторяет его после конца. Без loop по окончании свойство ended становится истинным, и видео остаётся на последнем кадре. Атрибут muted выключает звук, и именно с ним автозапуск разрешён почти везде. Автозапуск со звуком браузеры чаще всего блокируют, пока человек не нажмёт что-то на странице. Когда запуск блокируется, метод play() возвращает отклонённое обещание с ошибкой NotAllowedError. Поэтому фоновые ролики записывают как autoplay muted loop playsinline.
<video src="bg.webm" autoplay muted loop playsinline></video>
video.play().catch((error) => {
console.log(error.name); // NotAllowedError, если запуск запретили
});
Пример: autoplay и метод play() у тега video
Первый результат получен до нажатия на кнопки, это то, что браузер сделал сам. Любая кнопка даёт странице пользовательское действие, и после неё звук обычно разрешают.
| Ситуация | Что происходит | Пример записи |
|---|---|---|
autoplay без muted | Зависит от браузера: звук могут заблокировать | autoplay |
autoplay и muted | Запускается без нажатий | autoplay muted |
autoplay при preload="none" | Файл всё равно загружается: автозапуск сильнее preload | autoplay muted preload="none" |
autoplay добавлен скриптом после загрузки | Не запускает видео | video.setAttribute("autoplay", "") |
loop | Видео идёт по кругу, события ended нет | loop |
Атрибут preload у тега video: none, metadata и auto
Атрибут preload подсказывает браузеру, сколько загружать до нажатия на кнопку, и его решение обязательным не считается.
Значение none ничего не загружает, пока человек не запустил видео. Значение metadata загружает только служебные данные: длительность, размер и первый кадр. Значение auto разрешает браузеру загрузить файл целиком. Если атрибута нет, действует metadata (в Chrome так с 64-й версии). Это подсказка, а не команда: на мобильной сети или при включённой экономии трафика браузер может выбрать меньше. Автозапуск сильнее: файл с autoplay загружается и при preload="none".
| Пример записи | Что загружается | Длительность известна |
|---|---|---|
preload="none" | Ничего, пока нет play() | Нет, duration равна NaN |
preload="metadata" | Начало файла и служебные данные | Да |
| Атрибута нет | То же, что при metadata | Да |
preload="auto" | Почти весь файл | Да |
<video src="film.webm" controls preload="none"
poster="cover.jpg" width="640" height="360"></video>
Пример: атрибут preload у тега video до нажатия на play
Видео встроено в страницу, поэтому разница видна в свойствах: длительность, число загруженных секунд, readyState и networkState. Кнопка «Нажать play()» запускает ролик после preload none.
Для страницы с несколькими роликами выбирают none или metadata и дополняют poster: так браузер не упрётся в ограничение на число одновременных соединений с одним сайтом, о котором пишет web.dev.
Атрибуты poster, width и height у тега video: размер блока до загрузки
Пока файл не загружен, браузер не знает размер ролика, и блок video получается 300 на 150 пикселей.
Размер блока зависит от того, что известно до загрузки: есть ли картинка poster, заданы ли width и height, записан ли в CSS aspect-ratio. Если ничего этого нет, после загрузки блок меняет размер, и текст под ним сдвигается. Чтобы этого не было, заранее задайте пропорции. Когда задана только ширина, высоту браузер считает по пропорциям ролика: высота = ширина × 9 ÷ 16 для ролика 16 на 9, и для ширины 300 получается 168,75 пикселя.
| Пример записи | Размер до загрузки | Размер после загрузки (ролик 160 на 90) |
|---|---|---|
src="a.webm" | 300 на 150 | 160 на 90 |
poster="p.png" (200 на 100) | 200 на 100 | 200 на 100 до нажатия на play, потом 160 на 90 |
width="300" | 300 на 150 | 300 на 169 |
width="300" height="300" | 300 на 300 | 300 на 300, ролик вписан с полями |
style="width: 320px; aspect-ratio: 16/9" | 320 на 180 | 320 на 180 |
style="width: 100%" | 800 на 150 в окне 800 | 800 на 450 |
<video src="film.webm" controls
poster="cover.jpg" width="640" height="360"></video>
Пример: размер блока video до и после загрузки
Кнопки строят видео с разными атрибутами и измеряют блок. Пунктирная рамка показывает его границы. Последняя строка показывает размер самого видео, пока файл не загружен он равен нулю.
Картинка poster остаётся на месте, пока ролик не запущен, и блок держит её размер. Когда видео стартует, блок переходит к размеру ролика и обратно к постеру уже не возвращается, даже если вернуться на начало. Если адрес постера не открылся, блок остаётся 300 на 150. Поэтому делайте постер с теми же пропорциями, что и видео, и записывайте width и height.
Стили тега video в CSS: object-fit, aspect-ratio и зазор снизу
В CSS у video три частые задачи: вписать ролик в блок, сохранить пропорции и убрать зазор под ним.
Свойство object-fit задаёт, как ролик вписан в блок. По умолчанию у video значение contain: ролик целиком, с полями, если пропорции не совпадают. Значение cover заполняет блок и обрезает лишнее, fill растягивает, none показывает как есть, scale-down выбирает меньшее из none и contain.
.hero-video {
display: block;
width: 100%;
aspect-ratio: 16 / 9;
object-fit: cover;
}
Пример: object-fit и зазор под тегом video
Верхняя часть меняет значение object-fit у видео в квадратном блоке. Нижняя показывает высоту обёртки вокруг video в трёх режимах, в первом строчное положение добавляет несколько пикселей под роликом.
Как и у img, строчный video стоит на базовой линии строки, поэтому под ним остаётся место для нижних выносных элементов букв: обёртка вокруг ролика высотой 90 пикселей получается около 94. Убирают зазор значением display: block или vertical-align: top. Чтобы ролик не вылезал за колонку, пишут max-width: 100% и height: auto. Размер при этом задают так, как описано в предыдущем разделе, иначе страница будет сдвигаться при загрузке.
Тег video в JavaScript: свойства и методы
Объект video даёт полный доступ к воспроизведению: запуск, перемотку, звук, скорость и состояние файла.
Большинство свойств записывают и читают так же, как у обычных элементов. Значения вне допустимых пределов вызывают ошибку: громкость выше единицы приводит к исключению IndexSizeError. Длительность duration до загрузки служебных данных равна NaN, поэтому читать её нужно после события loadedmetadata.
| Свойство или метод | Что делает | Пример записи |
|---|---|---|
play() | Запускает видео, возвращает обещание | video.play() |
pause() | Ставит видео на паузу | video.pause() |
currentTime | Текущая позиция в секундах, можно записывать для перемотки | video.currentTime = 30 |
duration | Длительность в секундах, до загрузки служебных данных NaN | video.duration |
paused и ended | Стоит ли видео на паузе, дошло ли до конца | if (video.paused) {} |
volume | Громкость от 0 до 1 | video.volume = 0.5 |
muted | Выключен ли звук | video.muted = true |
playbackRate | Скорость: 1 обычная, 2 вдвое быстрее | video.playbackRate = 1.5 |
loop | Повтор после конца | video.loop = true |
readyState | Готовность данных от 0 до 4 | video.readyState |
videoWidth и videoHeight | Размер самого ролика, пока он не известен, равен 0 | video.videoWidth |
currentSrc | Адрес выбранного файла | video.currentSrc |
load() | Начинает выбор и загрузку заново | video.load() |
requestFullscreen() | Открывает видео на весь экран | video.requestFullscreen() |
const video = document.querySelector("video");
video.playbackRate = 2;
video.volume = 0.3;
video.play();
console.log(video.currentTime, video.duration);
Пример: свойства и методы video и что они возвращают
Каждая кнопка выполняет одно выражение над настоящим видео и записывает результат в журнал. Видео создано с preload none, поэтому duration сначала равна NaN, а после play() становится числом.
События тега video: порядок от loadstart до ended
Видео сообщает о каждом шаге событиями, и по ним удобно показывать индикатор загрузки, ошибки и конец ролика.
Подписываются на события обычным addEventListener. Типичный порядок при загрузке: loadstart, durationchange, loadedmetadata, loadeddata, canplay, canplaythrough. При preload="none" приходят только loadstart и suspend, остальные события ждут запуска. Точный порядок соседних событий может отличаться между браузерами, поэтому опираться на него не стоит.
| Событие | Когда приходит | Пример записи |
|---|---|---|
loadedmetadata | Стали известны длительность и размер ролика | video.addEventListener("loadedmetadata", fn) |
canplay | Данных достаточно, чтобы начать играть | video.addEventListener("canplay", fn) |
play и playing | Запуск запрошен и видео пошло | video.addEventListener("playing", fn) |
pause | Видео остановлено | video.addEventListener("pause", fn) |
seeking и seeked | Перемотка началась и закончилась | video.addEventListener("seeked", fn) |
timeupdate | Позиция изменилась, приходит несколько раз в секунду | video.addEventListener("timeupdate", fn) |
ended | Видео дошло до конца, при loop не приходит | video.addEventListener("ended", fn) |
error | Файл не удалось открыть | video.addEventListener("error", fn) |
video.addEventListener("ended", () => {
nextButton.hidden = false;
});
Пример: порядок событий video
Журнал показывает последние события в порядке прихода. Нажмите play на плеере, перемотайте и досмотрите до конца, и в списке появятся новые строки.
Почему тег video не воспроизводится: коды ошибок и причины
Когда видео не играет, причина почти всегда в файле, формате, сервере или запрете автозапуска.
Браузер сообщает об ошибке событием error и объектом video.error с кодом. Код 4 означает, что файл не нашли или его формат не поддерживается: и несуществующий адрес, и картинка вместо видео дают один и тот же код 4. Поэтому по коду причину не отличить, и смотрят вкладку «Сеть» в инструментах разработчика (они открываются клавишей F12).
| Причина | Что видно | Что проверить |
|---|---|---|
| Неверный адрес файла | Событие error, код 4 | Открыть адрес в отдельной вкладке |
| Браузер не знает формат или кодек | Код 4, у source событие error | Проверить файл через canPlayType, сделать запасной вариант |
| Сервер не поддерживает частичную загрузку | Видео играет, но перемотка не работает: currentTime остаётся равным нулю | Включить на сервере поддержку заголовка Range |
| Неверный тип в заголовке ответа | Chrome может сыграть файл и с типом text/plain, но MDN предупреждает, что видео может не показаться; отдавайте video/mp4 и video/webm | Проверить заголовок Content-Type |
| Автозапуск со звуком запрещён | play() отклонён с ошибкой NotAllowedError | Добавить muted или запускать после нажатия |
В src записана ссылка на YouTube | Код 4: это страница, а не видеофайл | Использовать тег iframe с кодом для размещения |
Пример: что сообщает video при ошибке файла
Три кнопки задают для video нормальный файл, файл, который не является видео, и адрес, которого нет. Под плеером видно, пришло ли событие error и какой код у ошибки.
Частые ошибки с тегом video
Основные ошибки связаны с размерами, звуком при автозапуске и ожиданием, что атрибуты работают после загрузки.
| Ошибка | Что происходит | Как исправить |
|---|---|---|
<video src="film.webm" /> | Слэш в конце игнорируется, тег остаётся открытым, и следующие за ним элементы оказываются внутри video и не показываются | Писать закрывающий тег </video> |
src="film.webm" | Нет controls и скрипта: запустить видео нечем | Добавить controls или свой интерфейс |
autoplay | Автозапуск со звуком браузер может заблокировать | Записать autoplay muted |
video.setAttribute("muted", "") | После создания звук не выключается | Записать video.muted = true |
video.setAttribute("autoplay", "") | После выбора файла ничего не запускает | Вызвать video.play() |
<video width="640"> | До загрузки высота 150, после загрузки сдвиг страницы | Записать и height либо aspect-ratio |
| Постер другой пропорции, чем ролик | Блок меняет размер при запуске | Сделать постер с пропорциями ролика |
<video src="a.webm"><source src="b.webm"></video> | Вложенные source игнорируются | Использовать либо src, либо source |
video.volume = 1.5 | Исключение IndexSizeError | Держать значение от 0 до 1 |
console.log(video.duration) | До loadedmetadata выводится NaN | Читать после события |
Много роликов с preload="auto" | Страница тянет все файлы сразу | Использовать none или metadata и poster |
video внутри блока без display: block | Под роликом появляется зазор | Записать display: block |