MelonPlayer. Описание API ядра.

Не используйте никакие методы и свойства, не описанные в данном документе. Лучше напишите разработчику, что надо расширить API.

Как подключить

Чтобы использовать плеер на своей странице, необходимо добавить 2 скрипта:

<script src="//connect.melonplayer.com/dist/clappr/clappr.min.js"></script>
<script src="//connect.melonplayer.com/dist/melon-player-core.js"></script>

API

В глобальное пространство имен добавляется 1 объект - MelonPlayer. Он имеет следующие свойства.

MelonPlayer.Core

Это конструктор для плеера без UI. При создании принимает объект конфигурации.

const player = new MelonPlayer.Core({
    // ссылка на вещание, обязательное поле
    source: "//hls-01-radio7.emgsound.ru/13/playlist.m3u8", 
    // HTMLElement для встраивания, обязательное поле.
    // можно передать document.createElement('div'), если не нужна поддержка IE11
    parent: document.querySelector("#hidden_element"), 
    // Настройки метаданных (необязательное поле).
    // Также любое из вложенных полей можно пропустить.
    metadata: { 
        // ссылка на JSON с метаданными
        jsonUrl: "https://metaradio7.hostingradio.ru/current.json",
        // ссылка на JSON для проверки обновления метаданных
        uniqueIdJsonUrl: "https://metaradio7.hostingradio.ru/id.json", 
        // Указание плееру читать метаданные из hls потока. 
        // Нужно только если такие метаданные там есть.
        isInAudioStream: true,
        // Указание плееру при запросе метаданных отсылать куки. 
        // Нужно если метаданные доступны только после авторизации пользователя.
        withCredentials: true, 
    },
    // Начальное состояние плеера (необязательное поле)
    // Любое из вложенных полей также можно пропустить.
    state: {
        volume: 50, // громкость
        isMuted: true, // отключение звука
        // Плеер начнет играть сразу после создания
        // Может работать не всегда, так многие браузеры запрещают autoplay 
        // до первого взаимодействия с интерфейсом
        isPlaying: true,      
    },   
});

Объект конфигурации должен содержать в себе следующие свойства:

source - url аудио-потока.
parent - html-элемент добавленный в DOM. Хотя ядро плеера не имеет никакого внешнего интерфейса, данный параметр необходим в связи с тем, что Flash не работает, если соответствующий элемент не будет добавлен в DOM. Flash используется в браузере IE11 на Windows 7. Сам элемент, добавленный внутрь parent, является, как правило, квадратиком размером 1 на 1 пиксел. Однако целесообразно скрыть и сам parent (но не через display: none!). Следующий стиль вполне справляется с задачей (сам элемент parent просто добавьте куда-нибудь в body).
```
.invisible {
    width: 0;
    height: 0;
    left: -999em;
    top: -999em;
    position: absolute;
    opacity: 0;
    overflow: hidden;
    z-index: -1000;
}
```
metadata - объект конфигурации метаданных (необязательное поле)
- jsonUrl - ссылка на json c метаданными. Даже если в hls-потоке есть метаданные, то при первом запуске метаданные все равно надо получать через http-запрос, чтобы не ждать, пока они появятся в потоке.
- uniqueIdJsonUrl - ссылка на json для проверки метаданных. Надо пропустить этот параметр, если metadata.isInAudioStream === true. Запрашивается каждые 5 секунд (если нельзя получить метаданные из hls-потока). Когда значение uniqueid в json поменялось, происходит запрос metadata.jsonUrl.
- isInAudioStream - указание плееру читать метаданные из аудио потока. Данный флаг нужен только в случае, если тип аудио потока - hls и такие метаданные в нем имеются, иначе установка этого флага приведет лишь к тому, что метаданные не будут обновляться совсем. Если метаданные в hls потоке отсутствуют, то этот флаг нужно просто опустить.
- withCredentials - указание плееру добавлять куки к запросам метаданных. Запросы метаданных - это кросс-доменные запросы, поэтому по умолчанию куки не отправляются. Данная опция нужна, если метаданные доступны только для авторизированных пользователей.
state - конфигурация начального состояния плеера. Можно пропустить. Опция удобна при переключении между станциями, когда плеер пересоздается.
- volume - уровень громкости. Число от 0 до 100.
- isMuted - отключить звук. То же, что вызвать player.mute().
- isPlaying - начать воспроизведение сразу после создания, то же что вызвать player.play().

Объект возвращаемый конструктором MelonPlayer.Core имеет следующие методы:

play() - запуск проигрывания. Именно когда начинается проигрывание обновляются метаданные и стартует анализ потока.
stop() - остановка проигрывания и анализа потока.
setVolume(value) - изменение громкости. value - число от 0 до 100.
getVolume() - получить уровень громкости, число от 0 до 100.
on(eventName, callback) - установить обработчик события.
off(eventName, callback) - снять обработчик события.
mute() - убирает звук.
unmute() - восстанавливает звук (то же значение громкости, что и до вызова mute()).
rewindToUnixTimestamp(timestamp) - перематывает эфир к заданному моменту времени. Принимает UNIX метку времени (UTC), то есть количество секунд (не миллисекунд!). Например, player.rewindToUnixTimestamp(Math.floor(Date.now() / 1000) - 60*60) отмотает эфир на 1 часа назад от текущего момента. Данный метод работает ли когда сервер сконфигурирован особым образом и хранит звук длительное время.
seek(timeInSeconds) - метод перемотки трека. Используется только при проигрывании файла. Принимает время в секундах.
getCurrentTime() - возвращает текущее время проигрывания в секундах.
getDuration() - возвращает общую длину трека в секундах.
isPlaying() - true/false. true если был вызван метод play() (даже если воспроизведение еще не началось в силу задержки, чтобы поймать момент начала звучания смотри событие PLAYING).
isMuted() - true/false. true если был вызван метод mute().
destroy() - уничтожение плеера. Вызывать когда экземпляр более не нужен. Приводит к остановке звука, и зачищению внутренних структур данных. Метод надо вызывать при пересоздании плеера для переключения между станциями.

MelonPlayer.Events

Плеер в процессе работы может возбуждать различные события, подписаться/отписаться на которые можно при помощи методов on()/off(). Например:

var player = new MelonPlayer.Core({ /* объект конфигурации */ });
player.on(MelonPlayer.Events.METADATA_UPDATED, ({metadata, delay}) => {
     // работа с метаданными   
});

MelonPlayer.Events.METADATA_UPDATED - событие возбуждается, когда были получены новые метаданные (через запрос к metadata.jsonUrl из конфигурации или в процессе анализа hls-потока). Обработчику события передается объект вида {metadata, [delay]}, где metadata - объект метаданных, полученный из JSON, а delay - это число в секундах, отражающее время, через которое аудио фрагмент, содержащий метаданные, начнет проигрываться. Данная задержка присутствует только когда метаданные были получены при анализе hls-потока (и есть буфер предварительной загрузки). В случае получения метаданных через http-запрос, поле задержки в объекте события может отсутствовать.
MelonPlayer.Events.WAITING - основано на стандартном событии waiting HTMLMediaElement'a. Возбуждается, когда проигрывание временно приостановлено (звук пропал) - при перемотке, при плохом соединении, а также и при старте проигрывания. Никаких данных обработчику не передается.

СОВЕТ: данное событие - это хороший момент для отображения индикатора загрузки (лучше с задержкой, например в 1 секунду, ибо после может очень быстро последовать событие PLAYING).
MelonPlayer.Events.PLAYING - основано на стандартном событии playing HTMLMediaElement'a. Возбуждается, когда началось проигрывание (звук пошел). Никаких данных обработчику не передается.

СОВЕТ: данное событие - это хороший момент для сокрытия индикатора загрузки.
MelonPlayer.Events.TIME_UPDATE - возбуждается, когда обновилось текущее время или общая длительность трека. Никаких данных обработчику не передается - для получения значений времени используйте методы плеера getDuration() и getCurrentTime().

СОВЕТ: данное событие возбуждается довольно часто - несколько раз в секунду, поэтому можно задать свой интервал (например в 1 секунду) и вызывать методы получения времени в соответствии с ним (или же игнорировать часть событий). Эта техника полезна, если обновления интерфейса дорогостоящи (например при использовании фреймворков, таких как React).
MelonPlayer.Events.ENDED - основано на стандартном событии ended HTMLMediaElement'a. Возбуждается, когда проигрывание трека закончилось. Никаких данных обработчику не передается.

Не используйте значения свойств объекта MelonPlayer.Events напрямую! Они могут поменяться в дальнейшем, то есть вместо player.on("METADATA_UPDATED", callback) следует писать player.on(MelonPlayer.Events.METADATA_UPDATED, callback).

Сводный пример

Типовая инициализация плеера.

HTML:

<!-- Следует добавить этот код куда-нибудь в body -->
<style>
    .invisible {
        width: 0;
        height: 0;
        left: -999em;
        top: -999em;
        position: absolute;
        opacity: 0;
        overflow: hidden;
        z-index: -1000;
    }
</style>
<div id="hidden_element" class="invisible"></div>

JavaScript:

// создаем плеер
var player = new MelonPlayer.Core({
    source: "//hls-01-radio7.emgsound.ru/13/playlist.m3u8",
    parent: document.querySelector("#hidden_element"),
    metadata: {
        jsonUrl: "https://metaradio7.hostingradio.ru/current.json",
        checkJsonUrl: "https://metaradio7.hostingradio.ru/id.json"
    }
});

// устанавливаем обработчики событий
player.on(MelonPlayer.Events.METADATA_UPDATED, ({metadata, delay}) => {
     // работа с метаданными   
});

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

Интерактивные примеры с кодом доступны по ссылкам: