Команды и запросы JS API

JavaScript API позволяет получать события плеера, запрашивать данные и управлять им снаружи.

Команды и запросы   Показать события

Для управления плеером и получением данных используется оператор api

var player = new Playerjs({...});
console.log(player.api("id"));
player.api("play");

Некоторые команды могут содержать параметр, например

player.api("play","ссылка на файл");

Команда	Параметр	Действие	Возвращает
play	-	запуск плеера*	-
play	ссылка на файл, плейлист или id:	запуск файла*	false или true для id:
pause	-	пауза	-
toggle	-	пуск / пауза	-
file	ссылка на файл, плейлист или id:	обновление файла без запуска и предзагрузки*	-
preload	ссылка на файл или плейлист	обновление файла без запуска с предзагрузкой*	-
stop	-	стоп	-
mute	-	выключение звука	-
unmute	-	включение звука**	-
seek	секунда	перемотка (после запуска)	-
fullscreen	-	полноэкранный режим**	-
exitfullscreen	-	выход из полноэкранного режима	-
isfullscreen	-	-	включен или выключен полноэкранный режим (false или true)
playing	-	-	включено или выключено воспроизведение (false или true)
started	-	-	был ли запущен плеер (false или true)
time	-	-	время воспроизведения в секундах (запрос time2 вернет время в формате чч:мм:cc)
duration	-	-	длительность в секундах
buffered	-	-	загруженный контент в секундах
muted	-	-	включен или выключен звук (false или true)
volume	ничего или уровень громкости (0.8)	возвращает уровень громкости, либо устанавливает значение (от 0 до 1). Для увеличения громкости своей кнопкой можно использовать команду volume,+0.1	уровень громкости (от 0 до 1) или ничего
quality	ничего или номер варианта качества (0,1,2...)	-	текущий вариант качества
qualities	-	-	доступные варианты качества
audiotrack	ничего или номер дорожки (0,1,2...)	запускает аудиодорожку по номеру с версии 9.7	название аудиодорожки, если не задан параметр или ее  номер, если указан параметр index
audiotracks	-	-	доступные аудиодорожки
speed	ничего или номер варианта скорости (0,1,2...)	-	текущая скорость
id	-	-	идентификатор плеера
log	-	-	лог плеера
screenshot	-	скриншот	false или base64
subtitles	-	-	доступные субтитры
subtitle	[Название]ссылка или номер субтитров (-1,0,1,2...)	запускает субтитры по ссылке или номеру (-1 выключает субтитры), для своей кнопки используйте subtitle,0/1	название текущего варианта субтитров или номер, если указать параметр index
+subtitle	[Название]ссылка	добавляет субтитры в конец списка	-
subtitle:size	размер субтитров (14 по-умолчанию)	форматирует субтитры (также можно использовать color, bg, bgcolor, shadow)	-
togglesubs	-	включает / выключает субтитры	-
poster	ссылка	выводит заставку, если плеер стоит на паузе	false или true
share	-	показывает экран с соц. сетями и кодом вставки плеера, если этот модуль включен в конструкторе	-
title	текст или ничего	выводит надпись player.api("title","text"), либо возвращает значение player.api("title")	значение title или true
playlist	объект [ ], ссылка или played	обновляет плейлист или возвращает прогресс	false или true или число
playlist_id	-	возвращает id файла из плейлиста	идентификатор
playlist_title	-	возвращает название активного файла из плейлиста	название
playlist_folders	-	возвращает массив данных о корневых папках плейлиста	массив
playlist_length	-	возвращает количество позиций в плейлисте	число
push	JSON	добавляет элементы в плейлист, например [{"file":"URL","title":"Название"}, {"file":"URL","title":"Название"}]	-
invert	-	разворачивает плейлист в обратном порядке	-
autonext	0, 1, либо ничего	запускать следующий файл в плейлисте (1), либо нет (0)	0 или 1, если не задан параметр
playlistloop	0, 1, либо ничего	зацикливать плейлист (1), либо нет (0)	0 или 1, если не задан параметр
next	-	запускает следующий файл в плейлисте	-
prev	-	запускает предыдущий файл в плейлисте	-
loop	0, 1, либо ничего	устанавливает автоповтор воспроизведения	0 или 1
find	id файла	открывает нужный файл из плейлиста и ждет запуска	false или true
cuid	значение cuid	обновляет параметр cuid для запоминания времени	-
showplaylist	1, либо ничего	показать или спрятать плейлист	-
moveplaylist	id	-	перемещает плейлист наружу
scale	шаг трансформации, либо формат, либо ничего	изменяет масштаб видео (число с плавающей точкой), либо соотношение сторон для неправильно закодированных видео (ширина:высота, например 4:3 или 16:9)	если параметр не задан, возвращает массив с масштабом по ширине и высоте, а также координаты, если видео сдвинуто
ratio	-	-	соотношение сторон видео
native	-	-	нативное управление (false или true)
points	объект меток	обновляет разметку содержания	-
thumbnails	ссылка на файл разметки миниатюр	обновляет миниатюры	-
vars	-	-	свои переменные
visibility	-	-	процент видимости плеера
hlserror dasherror	-	-	объект, содержащий информацию об ошибке HLS / DASH
hls dash	-	-	объект hls.js или dash.js (прямой доступ к модулю)
fix unfix	-	ручное переключение режима фиксации плеера	-
adblock	-	-	включен или выключен AdBlock (false или true)
startvast	id	запуск рекламы партнерской сети по id	-
live	-	-	прямой эфир или нет (true или false)
size	-	-	размеры плеера (ширина/высота)
stretch	0, 1, либо ничего	заполняет видео весь экран плеера	0 или 1
flip	-	переворачивает видео по горизонтали	-
geo	-	-	объект данных модуля геолокации
pip	-	меняет местами основной и дополнительный поток	-
cut	0, 1, интервал, либо ничего	управляет интерфейсом создания отрезка. Запрос cut? вернет актуальное значение.	-
toolbar	-	показывает панель управления, если она скрыта	-
destroy	-	подготавливает плеер к удалению перед очисткой контейнера	-
color1-3	цвет	задает значение цветовой переменной	-
menu	-	открывает / закрывает окно настроек	-
act	-	возвращает факт взаимодействия пользователя с плеером	true или false

* к команде play можно добавить опцию seek player.api("play","url[seek:10]"); для старта с нужной секунды, либо [seek:time] для старта с текущего времени. Старт через JS на мобильных платформах со звуком работает только вследствие действий пользователя (например, нажатие на экран телефона). Если вы хотите предотвратить показ рекламы после обновления ссылки на файл, необходимо добавить к ней [skipads] - player.api("play","url[skipads]");

** на всех платформах работает только вследствие действий пользователя.

API находится в постоянном процессе разработки, если чего-то не хватает - напишите нам через обратную связь.

Как узнать, что плеер готов работе

Можно отследить событие init, которое плеер присылает после инициализации. Также с версии 9.25 можно указать параметром ready название функции, которую плеер вызовет, когда будет готов.

var player = new Playerjs({id:"player", ready:"PlayerReady", file:"..."});
function PlayerReady(id){
   alert("ready");
}

Свои параметры

Вы можете передать плееру свои переменные объектом vars и забрать затем такой же командой.

var player = new Playerjs({id:"player", file:"video.mp4", vars:{my1:"a",my2:"b"}});

чvar vars = player.api("vars");
console.log(vars.my1); // a

Таким же образом свои переменные можно передавать в плейлистах.

Как отправлять команды плееру внутри iframe

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

<iframe id="player" src="https://site.com/video.html" type="text/html" width="640" height="360" frameborder="0" allowfullscreen=""></iframe>

Чтобы отправить ему команду нужно передать объект с командой api

document.getElementById("player").contentWindow.postMessage({"api":"play"}, "*");

Если нужно передать параметр, то в объект добавляется set

document.getElementById("player").contentWindow.postMessage({"api":"volume","set":0.5}, "*");

В ответ на запросы плеер отправляет событие message с объектом {event, answer} с 16 версии (в answer будет ответ).

document.getElementById("player").contentWindow.postMessage({"api":"time"}, "*");

window.addEventListener("message", function (event) {
   console.log(event.data.event, event.data.answer);
}

Символ * в конце означает, что вы доверяете этому iframe. Если нет, то вместо звездочки нужно передавать URI.

Плеер также поддерживает формат общения, который использует Яндекс в своем поиске по видео для управления плеерами.

---