Engine HTTP API
Contents
Общее описание
Начиная с версии 3.1 появилась возможность управлять движком по протоколу HTTP. Для передачи команды движку нужно отправить HTTP GET запрос на http-порт движка. Порт по умолчанию: 6878.
Проверка наличия движка
При необходимости проверить наличие движка у пользователя необходимо отправить JSONP запрос на адрес http://127.0.0.1:6878/webui/api/service?method=get_version&format=jsonp. Если движок запущен, то выдаст свою версию в ответ на запрос.
Пример запроса:
Запрос: http://127.0.0.1:6878/webui/api/service?method=get_version&format=jsonp&callback=mycallback Ответ: mycallback({"result": {"code": 3002300, "version": "3.1.0-rc2"}, "error": null});
Ответ состоит и таких полей:
- version - версия движка в виде строки (например, 3.0.12)
- code - версия движка в виде целого числа (для удобства сравнения версий, например 30012)
Пример HTML-страницы с кнопкой для проверки движка (JSONP-запросы отправляются с помощью библиотеки jQuery):
<!DOCTYPE html> <html> <head> <title>Ace Stream - check engine version</title> <script src="https://code.jquery.com/jquery-1.11.3.min.js"></script> <script> function checkEngineVersion() { $.ajax({ method: "GET", url: "http://127.0.0.1:6878/webui/api/service", dataType: "jsonp", data: { method: "get_version", format: "jsonp" }, success: function(response) { if(response.error) { console.log("request failed: " + response.error); } else { console.log("version: " + response.result.version); console.log("version_code: " + response.result.code); } }, error: function(request, error_string, exception) { console.log("request failed: " + error_string); } }); } </script> </head> <body> <button onclick="checkEngineVersion();">Check engine version</button> </body> </html>
Методы API
В описаниях методов <engine_address> - это ip-адрес движка, <engine_port> - http-порт движка. Все методы принимают такие общие параметры:
- sid - идентификатор плеера (необязательный параметр)
- id - идентификатор контента (content id) (условно обязательный параметр)
- infohash - infohash транспортного файла (.acelive либо .torrent файла) (условно обязательный параметр)
- url - ссылка на транспортный файл (условно обязательный параметр)
- path - путь к транспортному файлу в локальной файловой системе (условно обязательный параметр)
В запросах на старт воспроизведения обязательно должен присутствовать один из параметров id, infohash, url, path.
Получение потока в формате HLS
http://<engine_address>:<engine_port>/ace/manifest.m3u8
В ответ на данную команду движок выдаст HLS плейлист для воспроизведения запрашиваемого контента. В случае ошибки будет возвращен HTTP код 4хх либо 5хх с кратким описанием ошибки.
Параметры:
- transcode_audio - транскодировать аудио в AAC (параметр принимает значения 0 либо 1)
- transcode_mp3 - не транскодировать MP3 (параметр принимает значения 0 либо 1)
- preferred_audio_language - предпочитаемый язык аудио-дорожки (3-значный код, список здесь)
Пример:
http://127.0.0.1:6878/ace/manifest.m3u8?id=dd1e67078381739d14beca697356ab76d49d1a2d
Получение потока по HTTP
http://<engine_address>:<engine_port>/ace/getstream
В ответ на данную команду движок будет выдавать данные в виде http progressive download. В случае ошибки будет возвращен HTTP код 4хх либо 5хх с кратким описанием ошибки.
Пример:
http://127.0.0.1:6878/ace/getstream?id=dd1e67078381739d14beca697356ab76d49d1a2d
Запуск HLS-трансляции
http://<engine_address>:<engine_port>/hls/manifest.m3u8
Данная команда позволяет запустить через движок любую HLS-трансляцию. Для запуска достаточно передать движку ссылку на HLS-плейлист (параметр manifest_url).
Параметры:
- manifest_url - URL трансляции (ссылка на плейлист HLS-трансляции)
Пример:
http://127.0.0.1:6878/hls/manifest.m3u8?manifest_url=http%3A%2F%2Fwin.cdn.bonus-tv.ru%2FTVB7%2Fntv%2Fplaylist.m3u8
Пример HTML-страницы для запуска HLS-трансляции через движок в плеере VideoJS:
<!DOCTYPE html> <html> <head> <title>HLS example</title> <link href="http://vjs.zencdn.net/4.12/video-js.css" rel="stylesheet"> <script src="http://vjs.zencdn.net/4.12/video.js"></script> <script src="https://github.com/videojs/videojs-contrib-media-sources/releases/download/v0.1.0/videojs-media-sources.js"></script> <script src="https://github.com/videojs/videojs-contrib-hls/releases/download/v0.11.2/videojs.hls.min.js"></script> </head> <body> <video id="myvideo" class="video-js vjs-default-skin" controls preload="auto" width="640" height="390" data-setup='{}'> <source src="http://127.0.0.1:6878/hls/manifest.m3u8?manifest_url=http%3A%2F%2Fwin.cdn.bonus-tv.ru%2FTVB7%2Fntv%2Fplaylist.m3u8" type="application/x-mpegurl"> </video> </body> </html>
Расширенные возможности
Движок предоставляет некоторые дополнительные возможности по управлению сессией воспроизведения. Сюда входит возможность отправлять движку дополнительные команды, получать информацию про сессию воспроизведения, а также получать некоторые события. Для получения доступа к расширенным возможностям необходимо добавить такой параметр при старте сессии воспроизведения:
format=json
При получении данного параметра движок выдаст в ответ не медиа-поток, а набор ссылок в формате JSON:
{ "playback_url": playback_url, "stat_url: stat_url, "command_url": command_url, "event_url": event_url, }
- playback_url
- ссылка для получения медиа-потока
- stat_url
- ссылка для получения информации про сессию
- command_url
- ссылка для отправки команд движку
- event_url
- ссылка для получения событий
event_url в ответе выдается только в том случае, если страт выполнялся с параметром use_api_events.
По ссылке playback_url движок отдаст запрошенный медиа-поток. Эту ссылку необходимо передать плееру.
Получение статистики
По ссылке stat_url движок возвращает ответ в формате JSON с такими полями:
- status - статус сессии воспроизведения:
- prebuf - пребуферизация
- dl - воспроизведение
- peers - кол-во подсоединенных узлов
- speed_down - скорость скачивания (Кбайт/с)
- speed_up - скорость отдачи (Кбайт/с)
- downloaded - объем скачанных данных (байт)
- uploaded - объем отданных данных (байт)
- total_progress - процент загруженных данных от суммарного объема (для VOD); для live всегда 0
Пример:
Запрос: http://127.0.0.1:6878/ace/stat/6d12f958332ef0bd258053ba1afd833ddf9b74f9/f528764d624db129b32c21fbca0cb8d6 Ответ: { "response": { "status": "dl", "uploaded": 0, "speed_down": 516, "speed_up": 0, "downloaded": 14155776, "peers": 2, "total_progress": 0 }, "error": null }
Отправка команд движку
По ссылке command_url движок принимает команды для управления сессией воспроизведения.
Название команды передается в параметре method.
На данный момент доступна одна команда: stop - остановить сессию воспроизведения.
Рекомендуется всегда останавлить сессию воспроизведения с помощью этой команды, когда воспроизведение останавливается на уровне плеера.
Пример:
Запрос: http://127.0.0.1:6878/ace/cmd/5410b27fc567c35c8547e3b69b141215ce3a1fd7/ef0609c43e560697329d93dae4571edb?method=stop Ответ: { "response": "ok", "error": null }
Получение событий от движка
Ссылка event_url используется для получения событий от движка методом long polling.
Данные по событию возвращаются в поле response в виде JSON-объекта с такими полями:
- name
- название события
- params
- объект с параметрами (значения зависят от события)
В версиях до 3003600 в поле response передается не сам JSON-объект, а его строковое представление.
Пример:
Запрос: http://127.0.0.1:6878/ace/event/5410b27fc567c35c8547e3b69b141215ce3a1fd7/ef0609c43e560697329d93dae4571edb Ответ (версия движка >= 3003600): { "response": { "name": "got_codec_info", "params: { "audio_codec_id": 86018, "video_codec_id": 28 } }, "error": null } Ответ (версия движка < 3003600): { "response": "{\"name\": \"got_codec_info\"}, \"params\": {\"audio_codec_id\": 86018, \"video_codec_id\": 28}", "error": null }
Когда текущая сессия воспроизведения будет остановлена, event_url вернет такой ответ:
{ "response": null, "error": "download stopped" }
После получения такого ответа необходимо прекратить отсылать запросы на event_url.
Список событий
- missing_content
- движок не может найти запрашиваемый сегмент при воспроизведении HLS (плеер должен перемотать на live)
- got_codec_info
- доступна информация по кодекам потока.
- параметры
- video_codec_id - идентификатор видеокодека
- audio_codec_id - идентификатор аудиокодека
- Идентификаторы кодеков взяты из библиотеки ffmpeg, их можно найти здесь
- Данное событие можно использовать для вывода сообщения в случае, если плеер не поддерживает данные кодеки.
- segmenter_failed
- встроенный в движок HLS-сегментатор не смог обработать поток (плеер должен остановить воспроизведение)
- download_stopped
- движок остановил воспроизведение
- параметры
- reason - причина остановки; возможные значения
- missing_option - отсутствует платная опция, необходимая для воспроизведения данного контента
- option - идентификатор отсутствующей опции (для reason=missing_option)
Пример на javascript
Данный пример использует библиотеку jQuery.
function startEventListener() { $.ajax({ url: url, method: "GET", dataType: "json", cache: false, success: function(response) { if(response.error) { console.log("event listener: got error: " + response.error); } else { var event = response.response; if(typeof event !== "object") { event = JSON.parse(event); } console.log("event listener: got event: name=" + event.name + " params=" + JSON.stringify(params)); // handle event here // ... // listen to the next event (long polling) startEventListener(url); } }, error: function(xhr, status, error) { console.log("event listener error: status=" + status + " error=" + error); } }); } // init event listener startEventListener("http://127.0.0.1:6878/ace/event/5410b27fc567c35c8547e3b69b141215ce3a1fd7/ef0609c43e560697329d93dae4571edb");
Получение уведомлений об отсутствии платных опций
В определенных ситуациях для воспроизведения контента может понадобится наличие у пользователя той или иной платной опции. При отсутствии опции движок остановит воспроизведение и уведомит пользователя о необходимости приобрести опцию (для этого будет открыта страница в браузере по умолчанию).
Клиент API может взять на себя ответственность за уведомление пользователя. Для этого сессию воспроизведения нужно запускать с таким параметром:
use_stop_notifications=1
Теперь движок не будет уведомлять пользователя, а при остановке воспроизведения по причине отсутствия платной опции клиент API получит соответствующее событие и должен будет самостоятельно уведомить пользователя.
Остановка из-за отсутствуия опции возможна в двух случаях:
- при старте воспроизведения
- через некоторое время после начала воспроизведения
При старте это выглядит так:
http://127.0.0.1:6878/ace/manifest.m3u8?id=c894b23a65d64a0dae2076d2a01ec6bface83b01&format=json&use_stop_notifications=1 { "extra_data": { "reason": "missing_option", "option": "proxyServer" }, "response": null, "error": "You need to buy Proxy Server option to continue" }
Если остановка произойдет через некоторое время после начала воспроизведения, то будет отослано событие download_stopped:
Старт воспроизведения: http://127.0.0.1:6878/ace/manifest.m3u8?id=c894b23a65d64a0dae2076d2a01ec6bface83b01&format=json&use_api_events=1&use_stop_notifications=1 { "response": { "stat_url": "http://127.0.0.1:6878/ace/stat/6d12f958332ef0bd258053ba1afd833ddf9b74f9/f528764d624db129b32c21fbca0cb8d6", "command_url": "http://127.0.0.1:6878/ace/cmd/6d12f958332ef0bd258053ba1afd833ddf9b74f9/f528764d624db129b32c21fbca0cb8d6", "event_url": "http://127.0.0.1:6878/ace/event/6d12f958332ef0bd258053ba1afd833ddf9b74f9/f528764d624db129b32c21fbca0cb8d6", "playback_url": "http://127.0.0.1:6878/ace/m/6d12f958332ef0bd258053ba1afd833ddf9b74f9/f528764d624db129b32c21fbca0cb8d6.m3u8" }, "error": null } Ждем событие по ссылке event_url: http://127.0.0.1:6878/ace/event/6d12f958332ef0bd258053ba1afd833ddf9b74f9/f528764d624db129b32c21fbca0cb8d6 При остановке получим такой ответ по event_url: { "response": { "name": "download_stopped", "params": { "reason": "missing_option", "option": "proxyServer" } }, "error": null }
Идентификатор плеера
Идентификатор плеера - произвольная строка, которая идентифицирует плеер при обращении к движку. В качестве идентификатора лучше всего использовать случайное число.
Предназначение идентификатора плеера - дать движку возможность отличать запросы одного плеера от другого. Это связано с таким ограничением - нельзя просматривать одну и ту же live-трансляцию через движок одновременно в двух плеерах. При возникновении такой ситуации результаты непредсказуемы (трансляция может начать идти с перебоями в обоих плеерах). В связи с этим движок перестает отдавать плееру данные по трансляции, если эту же трансляцию запустили в другом плеере, но делает это только в том случае, если может отличить один плеер от другого.