Changes

==Общее описание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.

Пример запроса==Checking local engine availability==Send JSON query to <nowiki>http://127.0.0.1:6878/webui/api/service?method=get_version&format=jsonp</nowiki>. If app engine is running, then it return version string in JSON format. Some examples: <nowiki>ЗапросQuery:

ОтветResponse:

Ответ состоит и таких полейFields description:*'''version''' - версия движка в виде строки engine version, string (например, "3.0.12")*'''code''' - версия движка в виде целого числа engine version, integer (для удобства сравнения версий, например 30012)

Пример HTML-страницы с кнопкой для проверки движка Simple page with check button (JSONP-запросы отправляются с помощью библиотеки queries served by jQuery):

==Методы 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''')

В запросах на старт воспроизведения обязательно должен присутствовать один из параметров In the query to the app engine at least one of params <tt>id</tt>, <tt>infohash</tt>, <tt>url</tt>, <tt>path</tt>must be present.

===Получение потока в формате How to get HLSstream===Query: <tt><nowiki>http://<engine_address>:<engine_port>/ace/manifest.m3u8</nowiki></tt>

В ответ на данную команду движок выдаст As response app engine should return HLS плейлист для воспроизведения запрашиваемого контентаplaylist. В случае ошибки будет возвращен If any error occured, then engine return HTTP код error code 4хх либо or 5хх с кратким описанием ошибкиwith brief error description.

ПараметрыParams:*'''transcode_audio''' - транскодировать аудио в transcode all audio tracks to AAC , (параметр принимает значения values: 0 либо or 1, default 0)*'''transcode_mp3''' - не транскодировать do not transcode MP3 track(s), (параметр принимает значения values: 0 либо or 1, default 0)*'''preferred_audio_languagetranscode_ac3''' - предпочитаемый язык аудио-дорожки transcode only AC3 track(s), (3values: 0 or 1, default 0)*'''preferred_audio_language''' -значный кодthree char code of preffered language, список [full list - http://xml.coverpages.org/nisoLang3-1994.html здесь])

ПримерExample:

===Получение потока по How to get HTTPstream===Query: <tt><nowiki>http://<engine_address>:<engine_port>/ace/getstream</nowiki></tt>

В ответ на данную команду движок будет выдавать данные в виде As response app engine should return stream data as http progressive download. В случае ошибки будет возвращен If any error occured, then engine return HTTP код error code 4хх либо or 5хх с кратким описанием ошибкиwith brief error description.

ПримерExample:

===Запуск How to play HLS-трансляцииbroadcast===Query: <tt><nowiki>http://<engine_address>:<engine_port>/hls/manifest.m3u8</nowiki></tt>

Данная команда позволяет запустить через движок любую You can play via app engine any HLS-трансляцию. Для запуска достаточно передать движку ссылку на broadcast, just pass link to the HLS-плейлист playlist to the engine (параметр <tt>manifest_url</tt>param).

ПараметрыParams:*'''manifest_url''' - HLS manifest URL трансляции (ссылка на плейлист link to the HLS-трансляцииplaylist)

ПримерExample:

Пример Simple HTML-страницы для запуска code for playing HLS-трансляции через движок в плеере broadcast in VideoJSplayer:

==Расширенные возможности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:

При получении данного параметра движок выдаст в ответ не медиа-поток, а набор ссылок в формате As response app engine should return some links in JSONformat:

:ссылка для получения медиа-потокаmedia stream link

:ссылка для получения информации про сессиюsession statistics link

:ссылка для отправки команд движкуengine commands link

:ссылка для получения событийsession events link

<tt>event_url</tt> в ответе выдается только в том случае, если страт выполнялся с параметром will be present in engine response only if query contains param <tt>use_api_events</tt>.

По ссылке Via <tt>playback_url</tt> движок отдаст запрошенный медиа-потокapp engine will serve requested media stream. Эту ссылку необходимо передать плееруThis link should be passed to media player.

===Получение статистики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

По ссылке <tt>stat_url</tt> движок возвращает ответ в формате JSON с такими полями:*'''status''' - статус сессии воспроизведения:**''prebuf'' - пребуферизация**''dl'' - воспроизведение*'''peers''' - кол-во подсоединенных узлов*'''speed_down''' - скорость скачивания (Кбайт/с)*'''speed_up''' - скорость отдачи (Кбайт/с)*'''downloaded''' - объем скачанных данных (байт)*'''uploaded''' - объем отданных данных (байт)*'''total_progress''' - процент загруженных данных от суммарного объема (для VOD); для live всегда 0 ПримерExample: <nowiki>ЗапросQuery:

ОтветResponse:

===Отправка команд движкуSending extra commands to the app engine===По ссылке Via <tt>command_url</tt> движок принимает команды для управления сессией воспроизведения. Название команды передается в параметре <tt>method</tt>. На данный момент доступна одна команда: <tt>stop</tt> - остановить сессию воспроизведенияlink you can control playback session.

Рекомендуется всегда останавлить сессию воспроизведения с помощью этой команды, когда воспроизведение останавливается на уровне плеераCommand name passed to app engine via <tt>method</tt> param.For the moment you can use only one command: <tt>stop</tt> - stop playback session.Its recommended to send "stop" command to the app engine when user stops playback in the media player UI/controls.

ПримерExample: <nowiki>ЗапросQuery:

ОтветResponse:

===Получение событий от движкаGetting events from the app engine===Ссылка Via <tt>event_url</tt> используется для получения событий от движка методом link you can get events from the app engine, using "long polling" method.

Данные по событию возвращаются в поле As response app engine should return data in the <tt>response</tt> в виде field (JSON-объекта с такими полямиformat):;*'''name''' - event name:название события;*'''params:объект с параметрами (значения зависят от события)''' - object with actual param

ПримерExample: <nowiki>ЗапросQuery:

Ответ Response (версия движка engine version >= 3003600):

Ответ Response (версия движка engine version < 3003600):

Когда текущая сессия воспроизведения будет остановленаWhen current playback session has stopped, <tt>event_url</tt> вернет такой ответresponse looks like:

После получения такого ответа необходимо прекратить отсылать запросы на And player should stop sending queries to <tt>event_url</tt>.

====Список событийEvents list====

:движок не может найти запрашиваемый сегмент при воспроизведении quered fragment cannot be found (HLS (плеер должен перемотать на playback). Player should fast-forward to keep up with "live)" stream.

:доступна информация по кодекам потока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).

:встроенный в движок 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.

==Идентификатор плеера<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.

Предназначение идентификатора плеера "Player ID" purpose - дать движку возможность отличать запросы одного плеера от другого. Это связано с таким ограничением - нельзя просматривать одну и ту же app engine must distinguish one player session from another, as in the current engine implementation user cannot play the same live-трансляцию через движок одновременно в двух плеерах. При возникновении такой ситуации результаты непредсказуемы stream with two (трансляция может начать идти с перебоями в обоих плеерахor more). В связи с этим движок перестает отдавать плееру данные по трансляции, если эту же трансляцию запустили в другом плеереplayers simultaneously from one engine, но делает это только в том случаеand engine will stop to serve requests from one player, если может отличить один плеер от другогоwhen got a new request from another.