Video.js: HTML5 видеоплеер — примеры и настройка

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

Ниже — бесплатная интерактивная мастерская без регистрации. Попробуйте готовые сценарии, измените внешний вид, скорость и повтор, сравните MP4 с HLS и откройте собственный видеофайл. Затем скопируйте пример или скачайте исходники, чтобы перенести настройку в свой проект.

Предпросмотр использует настоящий Video.js 10. Панель настроек и учебный ролик созданы для этой страницы. Выбранный файл открывается локально в браузере: мастерская не загружает его на сервер. Для демонстрационного ролика подготовлены русские и английские субтитры; они не добавляются к вашему файлу автоматически.

Что дает Video.js и когда он нужен

В актуальной версии библиотека разделяет состояние плеера, отображение элементов управления и работу с источником видео. Для обычного HTML-проекта доступны пользовательские элементы, для React — отдельный пакет. Можно начать с готовой оболочки и подключать нужные возможности по мере развития страницы. Архитектура описана в официальной документации.

Например, в инструкции полезны субтитры, перемотка и изменение скорости, в демонстрации продукта — аккуратная заставка и подходящее оформление. Если достаточно стандартных браузерных кнопок, обычный <video controls> тоже решает задачу. Video.js становится полезен, когда требуется управляемый интерфейс, единый вид и дальнейшее расширение.

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

Версия имеет значение. Примеры ниже рассчитаны на @videojs/html@10.0.1. Старые инструкции с вызовом videojs(...), классом video-js и пакетом video.js относятся к предыдущему API. При обновлении существующего сайта используйте руководство миграции с Video.js 8, а не смешивайте оба подхода в одном примере.

Пример 1. Подключение в HTML-проекте

Для этих примеров нужен проект со сборкой JavaScript, например Vite. В его папке установите зафиксированную версию:

npm install --save-exact @videojs/html@10.0.1

Создайте src/player.js. Первые два импорта регистрируют плеер и готовую оболочку; остальные подключают русский язык интерфейса:

import '@videojs/html/video/player';
import '@videojs/html/video/skin';
import '@videojs/html/i18n';
import '@videojs/html/i18n/locales/ru/register';
import './player.css';

Добавьте в HTML подключение <script type="module" src="/src/player.js"></script>. В разработке файл обрабатывает сборщик; на сайт нужно перенести итоговые файлы сборки и их адреса. Обычный браузер не разрешит пакетные импорты из node_modules без сборки или карты импортов. Пошаговая подготовка проекта и отдельный вариант через CDN приведены в HTML-инструкции Video.js. В архиве нашей мастерской есть готовый проект с командой запуска.

Пример 2. Заставка, размеры и загрузка

Поместите видео, заставку и файл субтитров в доступную для сервера папку media. Например, в Vite это public/media. В разметке адреса ниже начинаются от корня сайта; замените их на свои:

<media-i18n lang="ru">
  <video-player class="lesson-player" poster="/media/lesson-poster.webp">
    <video-skin>
      <video id="lesson-video" src="/media/lesson.mp4"
             preload="metadata" playsinline>
        <track kind="subtitles" src="/media/lesson-ru.vtt"
               srclang="ru" label="Русский" default>
      </video>
    </video-skin>
  </video-player>
</media-i18n>

poster находится на video-player: готовая оболочка берет заставку оттуда. Указание только на нативном video задает браузерную заставку, но не изображение оболочки Video.js. Это различие разобрано в инструкции по poster.

playsinline позволяет воспроизводить ролик внутри страницы там, где платформа это поддерживает. preload="metadata" — подсказка браузеру загрузить сведения о видео; это не обещание конкретного объема трафика. Запуск оставлен за посетителем. Автовоспроизведение зависит от правил браузера и может быть заблокировано даже без звука, поэтому кнопку запуска нужно сохранять. Подробности — в документации autoplay.

Пример 3. Оформление без изменения ролика

Запишите в src/player.css размеры оболочки и цвет главного действия. Для учебного видео сохраняем весь кадр: режим contain не обрезает подписи по краям.

.lesson-player {
  display: block;
  width: 100%;
  --media-accent-color: #155e63;
  --media-accent-text-color: #ffffff;
  --media-border-radius: 16px;
  --media-object-fit: contain;
}

.lesson-player video-skin {
  display: block;
  width: 100%;
  aspect-ratio: 16 / 9;
}

Пару «акцент — текст на акценте» задаем вместе: так оформление не зависит от того, умеет ли браузер автоматически подобрать контрастный цвет. Для другой пропорции ролика измените aspect-ratio. Параметры готовых оболочек описаны в руководстве по настройке skins. Если будете добавлять собственные кнопки, сохраните видимый фокус и понятные подписи.

Пример 4. Субтитры WebVTT

Файл lesson-ru.vtt, подключенный в предыдущем примере, содержит время появления и текст. Сохраните его в UTF-8; первая строка должна быть WEBVTT, а между фрагментами — пустая строка:

WEBVTT

00:00.000 --> 00:03.000
Откройте настройки плеера.

00:03.000 --> 00:06.000
Выберите скорость, удобную для просмотра.

00:06.000 --> 00:09.000
Повторите нужный фрагмент инструкции.

Для английского перевода добавьте второй track с srclang="en", отдельным src и понятным label. Готовая оболочка уже содержит управление субтитрами. Если VTT хранится на другом домене, нужны разрешающие CORS-заголовки и crossorigin на медиакомпоненте. Браузерные предпочтения могут изменить выбор дорожки с атрибутом default. См. подключение captions и subtitles.

Пример 5. Своя скорость и повтор для MP4

При работе с обычным MP4 медиакомпонентом остается нативный video. Дополнительные настройки можно вынести под плеер. Добавьте после него следующую разметку:

<label for="lesson-rate">Скорость просмотра</label>
<select id="lesson-rate">
  <option value="0.75">0,75×</option>
  <option value="1" selected>1×</option>
  <option value="1.5">1,5×</option>
  <option value="2">2×</option>
</select>
<label><input id="lesson-loop" type="checkbox"> Повторять ролик</label>

В конце src/player.js, после импортов, подключите обработчики:

const video = document.querySelector('#lesson-video');
const rate = document.querySelector('#lesson-rate');
const loop = document.querySelector('#lesson-loop');

rate.addEventListener('change', () => {
  video.playbackRate = Number(rate.value);
});
loop.addEventListener('change', () => {
  video.loop = loop.checked;
});
video.addEventListener('ratechange', () => {
  const supported = [...rate.options]
    .some(option => Number(option.value) === video.playbackRate);
  if (supported) rate.value = String(video.playbackRate);
});

Обработчик ratechange обновляет поле, если скорость изменена через меню плеера. Этот пример рассчитан на нативный MP4-элемент из примера 2. Свойства playbackRate и loop описаны в справочнике HTMLMediaElement; для другого адаптера сверяйтесь с его API.

Пример 6. HLS с отдельным адаптером

HLS — поток с плейлистами и сегментами, а не просто MP4 с другим расширением. Для него установите npm install --save-exact @videojs/hlsjs-video@10.0.1 и добавьте в src/player.js импорт import '@videojs/html/media/hlsjs-video';. Внутри той же оболочки замените нативный video следующим элементом:

<video-player class="lesson-player" poster="/media/lesson-poster.webp">
  <video-skin>
    <hlsjs-video src="/media/lesson-hls/index.m3u8"
                 preload="metadata" playsinline>
    </hlsjs-video>
  </video-skin>
</video-player>

Адаптер использует hls.js и предоставляет медиавозможности оболочке. Подключение и ограничения смотрите в справочнике hlsjs-video. На сервере должны быть доступны главный плейлист, вложенные плейлисты и все сегменты с корректными адресами. Для нашего короткого HLS-примера подготовлены варианты 360p и 540p; это запись, а не прямая трансляция.

Несколько качеств нужно подготовить заранее: плеер не создаст их из одного MP4. Аналогично, DASH подключается своим адаптером; dash-video в текущей документации v10 помечен Unstable. Поэтому его стоит рассматривать отдельно от проверенного сценария MP4/HLS. Выбор источников описан в руководстве Media sources.

Если видео не запускается

Проверку удобно вести от файла к интерфейсу:

1. Адрес и доставка. Откройте запрос видео в панели Network. Исключите 404, авторизацию, смешанный HTTP/HTTPS-контент и ошибки CORS. Для потока проверьте также сегменты.
2. Кодеки. MP4 — контейнер. Способность открыть файл зависит и от видео- и аудиокодеков, устройства и браузера. Плеер не перекодирует неподдерживаемый файл. См. руководство по видеокодекам.
3. Запуск пользователем. Сначала проверьте обычную кнопку Play. Отказ автозапуска не означает, что ролик поврежден.
4. Сборка и версия. Проверьте загрузку модуля, выбранный адаптер и отсутствие кода от предыдущего API. Полезен разбор ошибок воспроизведения.

У v10 есть опубликованные минимальные версии браузеров: Chrome/Edge 111, Firefox 121, Safari и iOS Safari 16.4. Поддержку Smart TV и встроенных WebView проверяют на конкретной платформе; обещать работу на любом устройстве нельзя. Актуальная таблица и особенности оболочек — в Browser support. На своем сайте дополнительно проверьте управление клавиатурой, субтитры и удобство телефона.

Перенесите пример в свою страницу

Начните с MP4, заставки и явного запуска. Подберите оформление в мастерской, затем замените демонстрационные адреса на собственные и проверьте готовую сборку на вашем сервере. Для длинных роликов подготовьте HLS с несколькими вариантами качества; для инструкций добавьте собственные субтитры.

Страницу вокруг плеера можно собрать в конструкторе Bootstrap 5. Цвета интерфейса поможет выбрать мастерская тем shadcn Studio, а примеры анимации для соседних блоков — материал о React Bits. Исходный проект и развитие библиотеки доступны в официальном GitHub Video.js.