117
edits
Changes
→API methods
==Общее описаниеAbout==Начиная с версии Since version 3.1 появилась возможность управлять движком по протоколу we implemented API to control app engine via HTTP. Для передачи команды движку нужно отправить To do that, you should send appropriate HTTP GET запрос на http-порт движкаquery to the app engine (default IP:port is 127. Порт по умолчанию0.0.1: 6878.)
==Проверка наличия движкаLimitations==При необходимости проверить наличие движка у пользователя необходимо отправить JSONP запрос на адрес <nowiki>You can't use HTTP API with AJAX queries from secured (https) pages, because HTTP API is not secured, and such behaviour (http://127query from https page) will be blocked by browser.0.0.1:6878/webui/api/service?method=get_version&format=jsonp</nowiki>. Если движок запущен, то выдаст свою версию в ответ на запросSo you must have and serve a dedicated unsecured page on your secured site to work with engine HTTP API.
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});</nowiki>
<nowiki><!DOCTYPE html>
<html>
</html></nowiki>
==Методы Using HTTP APIon Android==В описаниях методов HTTP API is a preferred way to integrate engine with other applications on Android. Before sending any requests to engine you should ensure that it is running. This should be done by binding to engine service as described[[Using_Ace_Stream_as_service_on_Android|here]]. ==API methods==Terms: <tt>''<engine_address>''</tt> - это ip-адрес движкаapp engine IP address, <tt>''<engine_port>''</tt> - http-порт движкаapp engine HTTP port.Все методы принимают такие общие параметрыCommon params:*'''sid''' - [[#Идентификатор плеера|идентификатор плеера]] (необязательный параметр)*'''id''' - идентификатор контента (content id) (условно обязательный параметрconditional param)*'''infohash''' - transport file infohash транспортного файла (.acelive либо or .torrent файлаfile) (условно обязательный параметрconditional param)*'''url''' - ссылка на транспортный файл link to transport file (условно обязательный параметрconditional param). Can be used with URL encoded "file://path/" to access local file.*'''pathpid''' - путь к транспортному файлу в локальной файловой системе [[#Player ID|player id]] (условно обязательный параметрoptional, formerly known as '''sid''', since ver. 3.1.29 is obsolete and replaced by '''pid''')
===Получение потока в формате How to get HLSstream===Query: <tt><nowiki>http://<engine_address>:<engine_port>/ace/manifest.m3u8</nowiki></tt>
<nowiki>http://127.0.0.1:6878/ace/manifest.m3u8?id=dd1e67078381739d14beca697356ab76d49d1a2d</nowiki>
===Получение потока по How to get HTTPstream===Query: <tt><nowiki>http://<engine_address>:<engine_port>/ace/getstream</nowiki></tt>
<nowiki>http://127.0.0.1:6878/ace/getstream?id=dd1e67078381739d14beca697356ab76d49d1a2d</nowiki>
===Запуск How to play HLS-трансляцииbroadcast===Query: <tt><nowiki>http://<engine_address>:<engine_port>/hls/manifest.m3u8</nowiki></tt>
<nowiki>http://127.0.0.1:6878/hls/manifest.m3u8?manifest_url=http%3A%2F%2Fwin.cdn.bonus-tv.ru%2FTVB7%2Fntv%2Fplaylist.m3u8</nowiki>
<nowiki><!DOCTYPE html>
<html>
</html></nowiki>
==Расширенные возможностиAdditional features==Движок предоставляет некоторые дополнительные возможности по управлению сессией воспроизведения.Сюда входит возможность отправлять движку дополнительные командыEngine can provide some additional features to control playback session, получать информацию про сессию воспроизведенияsuch as extra commands, а также получать некоторые событияsession statistics and events polling.Для получения доступа к расширенным возможностям необходимо добавить такой параметр при старте сессии воспроизведенияTo access such features, you must add this param to playback session options:
<tt>format=json</tt>
<tt><nowiki>{
"playback_url": playback_url,
;playback_url
:ссылка для получения медиа-потокаmedia stream link
;stat_url
:ссылка для получения информации про сессиюsession statistics link
;command_url
:ссылка для отправки команд движкуengine commands link
;event_url
:ссылка для получения событийsession events link
<tt>event_url</tt> в ответе выдается только в том случае, если страт выполнялся с параметром will be present in engine response only if query contains param <tt>use_api_events</tt>.
===Получение статистикиGetting some stats===Via <tt>stat_url</tt> link app engine should return JSON-formatted structure:*'''status''' - playback session status:**''prebuf'' - prebuffering**''dl'' - playback*'''peers''' - number of connected peers*'''speed_down''' - download speed (Kbytes per sec)*'''speed_up''' - upload (Kbytes per sec)*'''downloaded''' - total downloaded (bytes)*'''uploaded''' - total uploaded (bytes)*'''total_progress''' - download ratio in percentage to media size, valid for VOD only, for live always 0
http://127.0.0.1:6878/ace/stat/6d12f958332ef0bd258053ba1afd833ddf9b74f9/f528764d624db129b32c21fbca0cb8d6
{
"response": {
}</nowiki>
===Отправка команд движкуSending extra commands to the app engine===По ссылке Via <tt>command_url</tt> движок принимает команды для управления сессией воспроизведенияlink you can control playback session.
http://127.0.0.1:6878/ace/cmd/5410b27fc567c35c8547e3b69b141215ce3a1fd7/ef0609c43e560697329d93dae4571edb?method=stop
{
"response": "ok",
}</nowiki>
===Получение событий от движкаGetting events from the app engine===Ссылка Via <tt>event_url</tt> используется для получения событий от движка методом link you can get events from the app engine, using "long polling" method.
In the versions prior to 3003600 <tt>response</tt> field contains "JSON as string" data.
В версиях до 3003600 в поле <tt>response</tt> передается не сам JSON-объект, а его строковое представление.
http://127.0.0.1:6878/ace/event/5410b27fc567c35c8547e3b69b141215ce3a1fd7/ef0609c43e560697329d93dae4571edb
{
"response": {
}
{
"response": "{\"name\": \"got_codec_info\"}, \"params\": {\"audio_codec_id\": 86018, \"video_codec_id\": 28}",
<nowiki>{
"response": null,
}</nowiki>
====Список событийEvents list====
;missing_content
:движок не может найти запрашиваемый сегмент при воспроизведении quered fragment cannot be found (HLS (плеер должен перемотать на playback). Player should fast-forward to keep up with "live)" stream.
;got_codec_info
:доступна информация по кодекам потокаstream codec data is ready.:;параметрыparams:::video_codec_id - идентификатор видеокодекаvideo codec id::audio_codec_id - идентификатор аудиокодекаaudio codec id:Идентификаторы кодеков взяты из библиотеки audio/video IDs corresponded to ffmpeglibavcodec, их можно найти [https://ffmpeg.org/doxygen/trunk/avcodec_8h_source.html здесьfull list here]:Данное событие можно использовать для вывода сообщения в случаеthis event can be useful, если плеер не поддерживает данные кодекиwhen player do not support such codec(s).
;segmenter_failed
:встроенный в движок built-in HLS-сегментатор не смог обработать поток (плеер должен остановить воспроизведение)segmenter failed to process stream. Player should stop the playback.
;download_stopped
:движок остановил воспроизведениеengine has stopped playback:;параметрыparams::<tt>reason</tt> - причина остановки; возможные значенияstop reason, possible values::::<tt>missing_option</tt> - отсутствует платная опцияcontent not free, необходимая для воспроизведения данного контента"paid option" is missing.::<tt>option</tt> - идентификатор отсутствующей опции missing option ID (для for <tt>reason=missing_option</tt>)
====Пример на javascriptJavascript example====Данный пример использует библиотеку Using [https://jquery.com jQuery]library.
<nowiki>function startEventListener() {
startEventListener("http://127.0.0.1:6878/ace/event/5410b27fc567c35c8547e3b69b141215ce3a1fd7/ef0609c43e560697329d93dae4571edb");</nowiki>
==<div id=Получение уведомлений об отсутствии платных опций"stop-notifications"></div>Notifications about missing paid option==In some cases user must have a permit (the paid option) to playback some content. If such permit not granted, then app engine will stop the playback and send a notification to user (by showing some predefined text in the default browser).This behaviour can be overrided, and then client API will handle user notifications by itself. To do this, engine playback session should be started with <nowiki>use_stop_notifications=1</nowiki> param.In this case at playback stop app engine will not send notification to user, but send a event to client. If some permits is not granted, then engine playback can be stopped: * at the playback start: <nowiki>Start playback: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"}</nowiki> * sometime after playback was started:If playback was stopped after some time, then engine will send a <tt>download_stopped</tt> event: <nowiki>Start playback: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} Wait for event via event_url:http://127.0.0.1:6878/ace/event/6d12f958332ef0bd258053ba1afd833ddf9b74f9/f528764d624db129b32c21fbca0cb8d6 At playback stop response should look like:{ "response": { "name": "download_stopped", "params": { "reason": "missing_option", "option": "proxyServer" } }, "error": null}</nowiki>
==Идентификатор плеераPlayer ID==Идентификатор плеера Player ID ('''pid''') - произвольная строкаrandom string, которая идентифицирует плеер при обращении к движку. В качестве идентификатора лучше всего использовать случайное числоused for player identification during engine connect session.