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==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-страницу. ==Проверка наличия движка==При необходимости проверить наличие движка у пользователя необходимо отправить JSONP запрос на адрес <nowiki>http://127.0.0.1:6878/webui/api/service?method=get_version&format=jsonp</nowiki>. Если движок запущен, то выдаст свою версию в ответ на запрос. Пример запроса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

:ссылка для получения событий <tt>event_url</tt> в ответе выдается только в том случае, если страт выполнялся с параметром <tt>use_api_events</tt>.session events link

По ссылке <tt>playback_urlevent_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

Пример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.

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

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