==Общее описание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 engine (default IP:port is 127. Порт по умолчанию0.0.1: 6878.)

==ОграниченияLimitations==You can't use HTTP API движка нельзя использовать с помощью with AJAX-запросов с HTTPS-страницqueries from secured (https) pages, because HTTP API is not secured, and such behaviour (http query from https page) will be blocked by browser.So you must have and serve a dedicated unsecured page on your secured site to work with engine HTTP API.

Технически невозможно отправить AJAX-запрос движку с HTTPS-страницы==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, так как общение с движком осуществляется по незащищенному протоколу HTTP. Все такие запросы блокируются всеми современные браузерамиthen it return version string in JSON format.

При необходимости работать с движком со своего https-сайта вебмастер должен создать для этих целей незащищенную http-страницу.Some examples: ==Проверка наличия движка==При необходимости проверить наличие движка у пользователя необходимо отправить JSONP запрос на адрес <nowiki>http://127.0.0.1:6878/webui/api/service?method=get_version&format=jsonp</nowiki>. Если движок запущен, то выдаст свою версию в ответ на запрос. Пример запросаQuery: <nowiki>Запрос:

ОтветResponse:

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

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

==Методы APImethods==В описаниях методов Terms: <tt>''<engine_address>''</tt> - это ip-адрес движкаapp engine IP address, <tt>''<engine_port>''</tt> - http-порт движкаapp engine HTTP port.Все методы принимают такие общие параметрыCommon params:*'''sid''' - [[#Идентификатор плеераplayer id|идентификатор плеераplayer id]] (необязательный параметрoptional)*'''id''' - идентификатор контента (content id) (условно обязательный параметрconditional param)*'''infohash''' - transport file infohash транспортного файла (.acelive либо or .torrent файлаfile) (условно обязательный параметрconditional param)*'''url''' - ссылка на транспортный файл link to transport file (условно обязательный параметрconditional param)*'''path''' - путь к транспортному файлу в локальной файловой системе local path to transport file (условно обязательный параметрconditional param)

В запросах на старт воспроизведения обязательно должен присутствовать один из параметров 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:

В ответ на данную команду движок выдаст 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)*'''transcode_ac3''' - транскодировать только transcode only AC3 track(параметр принимает значения s), (values: 0 либо or 1, по умолчанию default 0)*'''preferred_audio_language''' - предпочитаемый язык аудиоthree char code of preffered language, full list -дорожки (3-значный код, список [http://xml.coverpages.org/nisoLang3-1994.html здесь])

ПримерExample:

===Получение потока по How to get HTTPstream===Query:

В ответ на данную команду движок будет выдавать данные в виде 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:

Данная команда позволяет запустить через движок любую 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> движок принимает команды для управления сессией воспроизведения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.

На данный момент доступна одна команда: <tt>stop</tt> - остановить сессию воспроизведения. Рекомендуется всегда останавлить сессию воспроизведения с помощью этой команды, когда воспроизведение останавливается на уровне плеера. Пример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.

:движок остановил воспроизведение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.

Клиент API может взять на себя ответственность за уведомление пользователя. Для этого сессию воспроизведения нужно запускать с таким параметром: <nowiki>use_stop_notifications=1</nowiki> Теперь движок не будет уведомлять пользователяIf some permits is not granted, а при остановке воспроизведения по причине отсутствия платной опции клиент API получит соответствующее событие и должен будет самостоятельно уведомить пользователя. Остановка из-за отсутствуия опции возможна в двух случаях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

Если остановка произойдет через некоторое время после начала воспроизведения* 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:

Ждем событие по ссылке Wait for event via event_url:

При остановке получим такой ответ по event_urlAt playback stop response should look like:

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