venom-player v0.2.88

Venom player

Бесплатный DASH HLS HTML5 видео плеер для сайта

Пример:

<script src="https://cdn.jsdelivr.net/npm/venom-player@latest"></script>
<script>
    VenomPlayer.make({
        publicPath: 'https://cdn.jsdelivr.net/npm/venom-player@' + VenomPlayer.version + '/dist/',
        source: {
            file: {
                360: 'https://raw.githubusercontent.com/mnaseersj/BigBuckBunny/master/BigBuckBunny_640x360.mp4'
            }
        }
    })
</script>

Краткое содержание

• Параметры
• События
• Методы и свойства
• Список воспроизведения
• Модуль рекламы
• Надписи и текст сообщений по умолчанию

Параметры

publicPath (String) задаёт базовый путь, откуда будут подгружаться по мере необходимости динамические модули. Например, если плеер подключен из https://cdn.jsdelivr.net/npm/venom-player@latest, то нужно указать "https://cdn.jsdelivr.net/npm/venom-player@latest/dist/"

source (Object) комплексный параметр, в основном для указания пути к источнику видео. Должна содержать хотя бы одну из секций:

• dash (String) путь к dash манифесту
• hls (String) путь к hls манифесту
• file (Object<Number,String>) объект, в котором ключом выступает качество видео, а значением - путь к медиа файлу ( mp4, webm и т.д.)

Эти опции должны представлять альтернативные варианты одного и того же видео. Если указан dash, но он не поддерживается браузером пользователя, то будет использован hls; если же нет поддержки hls (библиотеки hls.js или же нативной), воспроизводиться будет file

Пример:

opts = {
 // ...
 source: {
  dash: 'https://video.example/id/master.mpd',
  hls: 'https://video.example/id/master.m3u8'
 }
}

• source.audio позволяет переименовывать звуковые дорожки и изменять их порядок в меню (количество должно совпадать с манифестом, иначе параметр будет проигнорирован)
• source.cc субтитры

opts = {
  // ...
  source: {
    // ...
    audio:  {
      names: ["Оригинал", "Дубляж"],
      order: [1, 0] // в меню будет "Дубляж", а затем "Оригинал" 
    },
    cc: {
      { name: "rus", url: "https://example.cc/rus.vtt" },
      { name: "eng", url: "https://example.cc/eng.vtt" }
    }
  }
}

container (Element) - ссылка на DOM элемент, в который следует встроить плеер. Если не указан, будет использовано document.body. Перед встраиванием весь контент контейнера будет очищен.

container: document.getElementById('player-container')

title (String) - название видео. Не отображается в теме "classic"

title: 'Game of Thrones'

ui.titleOnlyOnFullscreen (Boolean) если включена, то название видео будет отображаться только в полноэкранном режиме

ui: {
    titleOnlyOnFullscreen: true
}

poster (String) путь к постеру. Подробнее про poster тут

defaultPoster (String) заглушка, которая будет использована как постер, если изображение из параметра poster по каким-либо причинам будет недоступно.

autoLandscape (Boolean) если установить true, то на мобильных при входе в полноэкранный режим также будет использована альбомная ориентация экрана

pip (Boolean | Number) true - добавить кнопку "picture in picture", по умолчанию false. При значении 0.5 переход в этот режим будет происходить автоматически, когда видимость плеера станет ниже 50%

live (Boolean) для трансляций следует указать live: true

liveBuffer соответствует настройке hls.js maxBufferLength

theme (String) тема, в данный момент доступны "modern", "classic", "metro". По умолчанию "venom"

cssVars (Object) позволяет более тонко настроить вид плеера. Значения можно обновить после инициализации с помощью сеттера TODO list

aspectRatio (String) соотношение сторон, по умолчанию "16:9". Значение "fill" (заполнить всё доступное пространство) или "ширина:высота" (4:3, 10:9, 1:1...)

blocked (Boolean) если установлено в true, вместо плеера будет выведено окно-заглушка с сообщением, что видео заблокировано. Текст сообщения можно изменить с помощью text.blocked

quality (Number) качество по умолчанию

quality: 720

restrictQuality (Function) позволяет ограничить качество. Вместо смены будет выведено сообщение, что вернула функция. Если результат в логическом контексте ложен - ограничений нет.

restrictQuality: function(quality) {
  if (quality > 9000) {
    return "Your video card are not prepared!"
  }
}

speed (Number[]) список значений, из которых пользователь сможет выбрать скорость воспроизведения

speed: [1, 1.1, 1.25, 1.5]

restrictSpeed (Function) позволяет ограничить изменение скорости воспроизведения, в зависимости от качества

restrictSpeed: function(rate, quality) {
  if (rate > 1 && quality > 480) {
    return 'Ускорение доступно только для низкого качества видео'
  }
}

volume (Number) звук в пределах от 0 до 1. По умолчанию 1

time (Number) начать воспроизведения с указанного времени в секундах

timeSearchParamName (String) название get параметра, с которого будет взято значение time, по умолчанию "t"

trackProgress (Number) интервал в секундах, по которому будет срабатывать событие viewProgress, по умолчанию 60

doNotSaveProgress (Boolean) if true then don't save progress to localStorage, по умолчанию false

rewind (Number[]) время перемотки в секундах, по умолчанию [5, 20]. Первое значение используется при перемотке стрелками клавиатуры и тапом на мобильном (можно несколько раз подряд), второе - с зажатой кнопкой shift и на телевизоре

replay повторять воспроизведение

download (String) позволяет добавить ссылку на скачивание

reportUrl (String) url, на который будет отправляться форма обратной связи методом POST. Содержит поля: email, message и data

dash (Object) настройки dashjs, подробнее

ui: {
    // share: false, // спрятать кнопку поделиться, по умолчанию true
    // share: ['facebook', 'vkontakte', 'odnoklassniki', 'copy'], // белый список
    // timeline: false, // по умолчанию true
    // prevNext: false, // по умолчанию true: спрятать кнопки "следующая"/"предыдущая"
    // fullscreen: 'external'|false, по умолчанию true
}

text, translations изменить надписи

text: {
    settings: 'Настройки'
},
translations: { // позволяет изменить или дополнить переводы
    en: {
        settings: '[ Settings ]'
    }
}

format (Object) форматирование опций меню

format: {
    speed: function (rate) {
        return 'x' + rate;
    },
    quality: function (q) {
        if (q > 2000) return q+'K';
        if (q > 1079) return 'fHD '+q;
        if (q > 719) return 'HD '+q;
        return q;
    }
}

preview TODO

oneSound (String) позволяет спрятать все звуковые дорожки, кроме указанной

oneSound: 'original' // регистронезависимо; можно указать лишь часть названия

soundBlock (String) спрятать перечисленные звуковые дорожки

soundBlock: 'spanish,одноголосый' // можно указать лишь часть названия

События

Поддерживаются стандартные медиа события и события VPAID, а также:

• ready информирует о завершении инициализации
• endedSoon воспроизведение скоро закончится. Срабатывает за 20 сек до конца видео, но это время можно изменить с помощью одноименного параметра endedSoon. На это событие показывается подсказка о переключении на следующую серию; его же следует использовать, чтобы показать рекомендации или отправлять событие окончания просмотра в статистику (следующее видео из списка воспроизведения может быть переключено до события "ended", во время титров)
• playlistItem срабатывает перед переключением видео в списке воспроизведения. В зависимости от типа списка может содержать id, season, episode
• selectRecommendation id выбранной рекомендации (см. метод showRecommendations)
• TODO

Методы и свойства

• on(), once(), off() аналогичны EventEmitter node.js
• showRecommendations() показать рекомендации; id выбранной можно получить с помощью события selectRecommendation

player.once('endedSoon', () => player.showRecommendations([
    { id: 1, name: 'title1', poster: '<url1>' },
    { id: 2, name: 'title2', poster: '<url2>' },
    { id: 3, name: 'title3', poster: '<url3>' }
]));
player.on('selectRecommendation', id => alert(`go to video with id ${id}`));

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

var player = VenomPlayer.make({ /*...*/ });
player.onRenew = listen;
listen(player);

function listen(player) {
	player.once('ready', () => console.log('player ready'));
}

• cssVars сеттер для обновления cssVars

player.cssVars = {
	'color-primary': '#12aa6a',
	'background-color-primary': 'rgba(27, 39, 52, .9)'
};

Статические

• version (String) текущая версия плеера
• isMobile (Boolean)
• VenomPlayer.cssVars() реэкспорт пакета css-vars-ponyfill

Список воспроизведения

• playlist (Object | String) объект или url списка воспроизведения; в случае использования url формат должен быть json

Списков есть 2 вида: обычный "плоский" (одно уровневый)

playlist: {
    open: false,
    autoNext: true,
    ignoreLast: false,
    id: 'playlist id',
    flat: [
        { id: 'video1', title: 'title 1', source: { /*...*/ }, blocked: false },
        { id: 'video2', title: 'title 2', source: { /*...*/ } }
    ],
    current: { id: 'video1' }
}

и вложенный (для сериалов)

playlist: {
    id: 'game-of-thrones',
    seasons: [{
        season: 1, blocked: false, episodes: [
            { episode: '1', id: 'got1e1', title: 's1e1', source: { /*...*/ }, poster: '' },
            { episode: '2', id: 'got1e2', title: 's1e2', source: { /*...*/ }, mini: '' },
            { episode: '3', id: 'got1e3', title: 's1e3', source: { /*...*/ }, blocked: false }
        ]
    }, {
        season: 2, episodes: [/*...*/]
    }],
    current: { season: 2, episode: '13' }
}

параметры списка воспроизведения

id уникальный идентификатор списка, по нему будет сохраняться позиция просмотра

flat массив эпизодов ИЛИ seasons массив сезонов

current позиция списка, с которой следует начать проигрывание, для flat следует указать идентификатор видео { id: 'video id' }, для seasons - сезон и серию { season: 2, episode: '13' }

open если установить в true - меню списка будет изначально открыто (работает только в теме "modern")

autoNext: false - отключить автоматическое переключение на следующий эпизод

ignoreLast: true - игнорировать сохраненную позицию, на которой остановился пользователь. Вместо этого будет показан эпизод, установленный параметром current

параметры сезона

season номер сезона

blocked если значение true - все эпизоды этого сезона также будут недоступны для просмотра

episodes список эпизодов

параметры эпизода

id уникальный идентификатор видео

episode номер эпизода (серии)

source, title, blocked и poster аналогичны параметрам плеера

mini миниатюра постера, отображаемая при наведении на копки "Следующая"/"Предыдущая"

Модуль рекламы

Настраивается с помощью параметра ads. Поведение по умолчанию:

start => pre roll ( => 10m => non linear => 5m => middle )*

*поведение, заключенное в скобки, повторяется

ads: {
    volume: 0.3, // 30% громкости, чтобы сгладить контраст с контентом
    midThenNonLinear: false, // true - показать первым middle roll, затем оверлэй
    nonLinear: { // overlay
        url: 'https://...',
        offset: 10 * 60, // через 10 мин после старта и middle
        total: 2 // общее количество не больше 2 (по умолчанию не ограничено)
    },
    pre: {
        urls: ['https://...'], //ссылка на vast
        maxImpressions: 2 // не больше 2 подряд
    },
    middle: {
        urls: ['https://...'],
        maxImpressions: 1, // не больше 1 подряд
        offset: 5 * 60, // через 5 мин после non-linear (overlay)
        total: 0 // общее количество не ограничено
    }
}

text