Difference between revisions of "Engine HTTP API"

From Ace Stream Wiki
Jump to: navigation, search
(→‎Получение потока в формате HLS)
(→‎API methods)
 
(13 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
==Общее описание==
+
==About==
−
Начиная с версии 3.1 появилась возможность управлять движком по протоколу HTTP. Для передачи команды движку нужно отправить HTTP GET запрос на http-порт движка. Порт по умолчанию: 6878.
+
Since version 3.1 we implemented API to control app engine via HTTP. To do that, you should send appropriate HTTP GET query to the app engine (default IP:port is 127.0.0.1:6878)
  
−
==Ограничения==
+
==Limitations==
−
HTTP API движка нельзя использовать с помощью AJAX-запросов с HTTPS-страниц.
+
You can't use HTTP API with AJAX 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-страницы, так как общение с движком осуществляется по незащищенному протоколу HTTP. Все такие запросы блокируются всеми современные браузерами.
+
==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.
  
−
При необходимости работать с движком со своего https-сайта вебмастер должен создать для этих целей незащищенную http-страницу.
+
Some examples:
−
 
+
  <nowiki>
−
==Проверка наличия движка==
+
Query:
−
При необходимости проверить наличие движка у пользователя необходимо отправить JSONP запрос на адрес <nowiki>http://127.0.0.1:6878/webui/api/service?method=get_version&format=jsonp</nowiki>. Если движок запущен, то выдаст свою версию в ответ на запрос.
 
−
 
 
−
Пример запроса:
 
−
  <nowiki>Запрос:
 
 
http://127.0.0.1:6878/webui/api/service?method=get_version&format=jsonp&callback=mycallback
 
http://127.0.0.1:6878/webui/api/service?method=get_version&format=jsonp&callback=mycallback
  
−
Ответ:
+
Response:
 
mycallback({"result": {"code": 3002300, "version": "3.1.0-rc2"}, "error": null});</nowiki>
 
mycallback({"result": {"code": 3002300, "version": "3.1.0-rc2"}, "error": null});</nowiki>
  
−
Ответ состоит и таких полей:
+
Fields description:
−
*'''version''' - версия движка в виде строки (например, 3.0.12)
+
*'''version''' - engine version, string ("3.0.12")
−
*'''code''' - версия движка в виде целого числа (для удобства сравнения версий, например 30012)
+
*'''code''' - engine version, integer (30012)
  
−
Пример HTML-страницы с кнопкой для проверки движка (JSONP-запросы отправляются с помощью библиотеки jQuery):
+
Simple page with check button (JSONP-queries served by jQuery):
 
  <nowiki><!DOCTYPE html>
 
  <nowiki><!DOCTYPE html>
 
<html>
 
<html>
Line 60: Line 58:
 
</html></nowiki>
 
</html></nowiki>
  
−
==Методы API==
+
==Using HTTP API on Android==
−
В описаниях методов <tt>''<engine_address>''</tt> - это ip-адрес движка, <tt>''<engine_port>''</tt> - http-порт движка.
+
HTTP API is a preferred way to integrate engine with other applications on Android.
−
Все методы принимают такие общие параметры:
+
 
−
*'''sid''' - [[#Идентификатор плеера|идентификатор плеера]] (необязательный параметр)
+
Before sending any requests to engine you should ensure that it is running. This should be done by binding to engine service as described
−
*'''id''' - идентификатор контента (content id) (условно обязательный параметр)
+
[[Using_Ace_Stream_as_service_on_Android|here]].
−
*'''infohash''' - infohash транспортного файла (.acelive либо .torrent файла) (условно обязательный параметр)
+
 
−
*'''url''' - ссылка на транспортный файл (условно обязательный параметр)
+
==API methods==
−
*'''path''' - путь к транспортному файлу в локальной файловой системе (условно обязательный параметр)
+
Terms: <tt>''<engine_address>''</tt> - app engine IP address, <tt>''<engine_port>''</tt> - app engine HTTP port.
 +
Common params:
 +
*'''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.
 +
*'''pid''' - [[#Player ID|player id]] (optional, formerly known as '''sid''', since ver. 3.1.29 is obsolete and replaced by '''pid''')
  
−
В запросах на старт воспроизведения обязательно должен присутствовать один из параметров <tt>id</tt>, <tt>infohash</tt>, <tt>url</tt>, <tt>path</tt>.
+
In the query to the app engine at least one of params <tt>id</tt>, <tt>infohash</tt>, <tt>url</tt> must be present.
  
−
===Получение потока в формате HLS===
+
===How to get HLS stream===
−
<tt><nowiki>http://<engine_address>:<engine_port>/ace/manifest.m3u8</nowiki></tt>
+
Query: <tt><nowiki>http://<engine_address>:<engine_port>/ace/manifest.m3u8</nowiki></tt>
  
−
В ответ на данную команду движок выдаст HLS плейлист для воспроизведения запрашиваемого контента. В случае ошибки будет возвращен HTTP код 4хх либо 5хх с кратким описанием ошибки.
+
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''' - транскодировать все аудио в AAC (параметр принимает значения 0 либо 1, по умолчанию 0)
+
*'''transcode_audio''' - transcode all audio tracks to AAC, (values: 0 or 1, default 0)
−
*'''transcode_mp3''' - не транскодировать MP3 (параметр принимает значения 0 либо 1, по умолчанию 0)
+
*'''transcode_mp3''' - do not transcode MP3 track(s), (values: 0 or 1, default 0)
−
*'''transcode_ac3''' - транскодировать только AC3 (параметр принимает значения 0 либо 1, по умолчанию 0)
+
*'''transcode_ac3''' - transcode only AC3 track(s), (values: 0 or 1, default 0)
−
*'''preferred_audio_language''' - предпочитаемый язык аудио-дорожки (3-значный код, список [http://xml.coverpages.org/nisoLang3-1994.html здесь])
+
*'''preferred_audio_language''' - three char code of preffered language, full list - http://xml.coverpages.org/nisoLang3-1994.html
  
−
Пример:
+
Example:
 
  <nowiki>http://127.0.0.1:6878/ace/manifest.m3u8?id=dd1e67078381739d14beca697356ab76d49d1a2d</nowiki>
 
  <nowiki>http://127.0.0.1:6878/ace/manifest.m3u8?id=dd1e67078381739d14beca697356ab76d49d1a2d</nowiki>
  
−
===Получение потока по HTTP===
+
===How to get HTTP stream===
−
<tt><nowiki>http://<engine_address>:<engine_port>/ace/getstream</nowiki></tt>
+
Query: <tt><nowiki>http://<engine_address>:<engine_port>/ace/getstream</nowiki></tt>
  
−
В ответ на данную команду движок будет выдавать данные в виде http progressive download. В случае ошибки будет возвращен HTTP код 4хх либо 5хх с кратким описанием ошибки.
+
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:
 
  <nowiki>http://127.0.0.1:6878/ace/getstream?id=dd1e67078381739d14beca697356ab76d49d1a2d</nowiki>
 
  <nowiki>http://127.0.0.1:6878/ace/getstream?id=dd1e67078381739d14beca697356ab76d49d1a2d</nowiki>
  
−
===Запуск HLS-трансляции===
+
===How to play HLS broadcast===
−
<tt><nowiki>http://<engine_address>:<engine_port>/hls/manifest.m3u8</nowiki></tt>
+
Query: <tt><nowiki>http://<engine_address>:<engine_port>/hls/manifest.m3u8</nowiki></tt>
  
−
Данная команда позволяет запустить через движок любую HLS-трансляцию. Для запуска достаточно передать движку ссылку на HLS-плейлист (параметр <tt>manifest_url</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''' - URL трансляции (ссылка на плейлист HLS-трансляции)
+
*'''manifest_url''' - HLS manifest URL (link to the HLS playlist)
  
−
Пример:
+
Example:
 
  <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>http://127.0.0.1:6878/hls/manifest.m3u8?manifest_url=http%3A%2F%2Fwin.cdn.bonus-tv.ru%2FTVB7%2Fntv%2Fplaylist.m3u8</nowiki>
  
−
Пример HTML-страницы для запуска HLS-трансляции через движок в плеере VideoJS:
+
Simple HTML code for playing HLS broadcast in VideoJS player:
 
  <nowiki><!DOCTYPE html>
 
  <nowiki><!DOCTYPE html>
 
<html>
 
<html>
Line 123: Line 126:
 
</html></nowiki>
 
</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>format=json</tt>
−
       
+
 
−
При получении данного параметра движок выдаст в ответ не медиа-поток, а набор ссылок в формате JSON:
+
As response app engine should return some links in JSON format:  
 
  <tt><nowiki>{
 
  <tt><nowiki>{
 
     "playback_url": playback_url,
 
     "playback_url": playback_url,
Line 138: Line 140:
  
 
;playback_url
 
;playback_url
−
:ссылка для получения медиа-потока
+
:media stream link
 
;stat_url
 
;stat_url
−
:ссылка для получения информации про сессию
+
:session statistics link
 
;command_url
 
;command_url
−
:ссылка для отправки команд движку
+
:engine commands link
 
;event_url
 
;event_url
−
:ссылка для получения событий
+
:session events link
−
 
 
−
<tt>event_url</tt> в ответе выдается только в том случае, если страт выполнялся с параметром <tt>use_api_events</tt>.
 
  
−
По ссылке <tt>playback_url</tt> движок отдаст запрошенный медиа-поток. Эту ссылку необходимо передать плееру.
+
<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.
  
−
По ссылке <tt>stat_url</tt> движок возвращает ответ в формате JSON с такими полями:
+
===Getting some stats===
−
*'''status''' - статус сессии воспроизведения:
+
Via <tt>stat_url</tt> link app engine should return JSON-formatted structure:
−
**''prebuf'' - пребуферизация
+
*'''status''' - playback session status:
−
**''dl'' - воспроизведение
+
**''prebuf'' - prebuffering
−
*'''peers''' - кол-во подсоединенных узлов
+
**''dl'' - playback
−
*'''speed_down''' - скорость скачивания (Кбайт/с)
+
*'''peers''' - number of connected peers
−
*'''speed_up''' - скорость отдачи (Кбайт/с)
+
*'''speed_down''' - download speed (Kbytes per sec)
−
*'''downloaded''' - объем скачанных данных (байт)
+
*'''speed_up''' - upload (Kbytes per sec)
−
*'''uploaded''' - объем отданных данных (байт)
+
*'''downloaded''' - total downloaded (bytes)
−
*'''total_progress''' - процент загруженных данных от суммарного объема (для VOD); для live всегда 0
+
*'''uploaded''' - total uploaded (bytes)
 +
*'''total_progress''' - download ratio in percentage to media size, valid for VOD only, for live always 0
  
−
Пример:
+
Example:
−
  <nowiki>Запрос:
+
  <nowiki>
 +
Query:
 
http://127.0.0.1:6878/ace/stat/6d12f958332ef0bd258053ba1afd833ddf9b74f9/f528764d624db129b32c21fbca0cb8d6
 
http://127.0.0.1:6878/ace/stat/6d12f958332ef0bd258053ba1afd833ddf9b74f9/f528764d624db129b32c21fbca0cb8d6
  
−
Ответ:
+
Response:
 
{
 
{
 
   "response": {
 
   "response": {
Line 181: Line 183:
 
}</nowiki>
 
}</nowiki>
 
          
 
          
−
===Отправка команд движку===
+
===Sending extra commands to the app engine===
−
По ссылке <tt>command_url</tt> движок принимает команды для управления сессией воспроизведения.
+
Via <tt>command_url</tt> link you can control playback session.
−
 
 
−
Название команды передается в параметре <tt>method</tt>.
 
−
 
 
−
На данный момент доступна одна команда: <tt>stop</tt> - остановить сессию воспроизведения.
 
  
−
Рекомендуется всегда останавлить сессию воспроизведения с помощью этой команды, когда воспроизведение останавливается на уровне плеера.
+
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>Запрос:
+
  <nowiki>
 +
Query:
 
http://127.0.0.1:6878/ace/cmd/5410b27fc567c35c8547e3b69b141215ce3a1fd7/ef0609c43e560697329d93dae4571edb?method=stop
 
http://127.0.0.1:6878/ace/cmd/5410b27fc567c35c8547e3b69b141215ce3a1fd7/ef0609c43e560697329d93dae4571edb?method=stop
  
−
Ответ:
+
Response:
 
{
 
{
 
     "response": "ok",
 
     "response": "ok",
Line 200: Line 201:
 
}</nowiki>
 
}</nowiki>
 
          
 
          
−
===Получение событий от движка===
+
===Getting events from the app engine===
−
Ссылка <tt>event_url</tt> используется для получения событий от движка методом long polling.
+
Via <tt>event_url</tt> link you can get events from the app engine, using "long polling" method.
  
−
Данные по событию возвращаются в поле <tt>response</tt> в виде JSON-объекта с такими полями:
+
As response app engine should return data in the <tt>response</tt> field (JSON format):
−
;name
+
*'''name''' - event name
−
:название события
+
*'''params''' - object with actual param
−
;params
 
−
:объект с параметрами (значения зависят от события)
 
  
 +
In the versions prior to 3003600 <tt>response</tt> field contains "JSON as string" data.
 
В версиях до 3003600 в поле <tt>response</tt> передается не сам JSON-объект, а его строковое представление.
 
В версиях до 3003600 в поле <tt>response</tt> передается не сам JSON-объект, а его строковое представление.
  
−
Пример:
+
Example:
−
  <nowiki>Запрос:
+
  <nowiki>
 +
Query:
 
http://127.0.0.1:6878/ace/event/5410b27fc567c35c8547e3b69b141215ce3a1fd7/ef0609c43e560697329d93dae4571edb
 
http://127.0.0.1:6878/ace/event/5410b27fc567c35c8547e3b69b141215ce3a1fd7/ef0609c43e560697329d93dae4571edb
  
−
Ответ (версия движка >= 3003600):
+
Response (engine version >= 3003600):
 
{
 
{
 
     "response": {
 
     "response": {
Line 227: Line 228:
 
}
 
}
  
−
Ответ (версия движка < 3003600):
+
Response (engine version < 3003600):
 
{
 
{
 
     "response": "{\"name\": \"got_codec_info\"}, \"params\": {\"audio_codec_id\": 86018, \"video_codec_id\": 28}",
 
     "response": "{\"name\": \"got_codec_info\"}, \"params\": {\"audio_codec_id\": 86018, \"video_codec_id\": 28}",
Line 234: Line 235:
  
  
−
Когда текущая сессия воспроизведения будет остановлена, <tt>event_url</tt> вернет такой ответ:
+
When current playback session has stopped, <tt>event_url</tt> response looks like:
 
  <nowiki>{
 
  <nowiki>{
 
     "response": null,
 
     "response": null,
Line 240: Line 241:
 
}</nowiki>
 
}</nowiki>
  
−
После получения такого ответа необходимо прекратить отсылать запросы на <tt>event_url</tt>.
+
And player should stop sending queries to <tt>event_url</tt>.
  
−
====Список событий====
+
====Events list====
 
;missing_content
 
;missing_content
−
:движок не может найти запрашиваемый сегмент при воспроизведении HLS (плеер должен перемотать на live)
+
:quered fragment cannot be found (HLS playback). Player should fast-forward to keep up with "live" stream.
 
;got_codec_info
 
;got_codec_info
−
:доступна информация по кодекам потока.
+
:stream codec data is ready.
−
:;параметры:
+
:;params:
−
::video_codec_id - идентификатор видеокодека
+
::video_codec_id - video codec id
−
::audio_codec_id - идентификатор аудиокодека
+
::audio_codec_id - audio codec id
−
:Идентификаторы кодеков взяты из библиотеки ffmpeg, их можно найти [https://ffmpeg.org/doxygen/trunk/avcodec_8h_source.html здесь]
+
:audio/video IDs corresponded to ffmpeg libavcodec, [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
 
;segmenter_failed
−
:встроенный в движок HLS-сегментатор не смог обработать поток (плеер должен остановить воспроизведение)
+
:built-in HLS-segmenter failed to process stream. Player should stop the playback.
 
;download_stopped
 
;download_stopped
−
:движок остановил воспроизведение
+
:engine has stopped playback
−
:;параметры
+
:;params
−
::<tt>reason</tt> - причина остановки; возможные значения
+
::<tt>reason</tt> - stop reason, possible values:
−
:::<tt>missing_option</tt> - отсутствует платная опция, необходимая для воспроизведения данного контента
+
:::<tt>missing_option</tt> - content not free, "paid option" is missing.
−
::<tt>option</tt> - идентификатор отсутствующей опции (для <tt>reason=missing_option</tt>)
+
::<tt>option</tt> - missing option ID (for <tt>reason=missing_option</tt>)
  
−
====Пример на javascript====
+
====Javascript example====
−
Данный пример использует библиотеку [https://jquery.com jQuery].
+
Using [https://jquery.com jQuery] library.
  
 
  <nowiki>function startEventListener() {
 
  <nowiki>function startEventListener() {
Line 297: Line 298:
 
startEventListener("http://127.0.0.1:6878/ace/event/5410b27fc567c35c8547e3b69b141215ce3a1fd7/ef0609c43e560697329d93dae4571edb");</nowiki>
 
startEventListener("http://127.0.0.1:6878/ace/event/5410b27fc567c35c8547e3b69b141215ce3a1fd7/ef0609c43e560697329d93dae4571edb");</nowiki>
  
−
==<div id="stop-notifications"></div>Получение уведомлений об отсутствии платных опций==
+
==<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.
−
Клиент API может взять на себя ответственность за уведомление пользователя. Для этого сессию воспроизведения нужно запускать с таким параметром:
+
In this case at playback stop app engine will not send notification to user, but send a event to client.
−
<nowiki>use_stop_notifications=1</nowiki>
 
−
 
 
−
Теперь движок не будет уведомлять пользователя, а при остановке воспроизведения по причине отсутствия платной опции клиент API получит соответствующее событие и должен будет самостоятельно уведомить пользователя.
 
−
 
 
−
Остановка из-за отсутствуия опции возможна в двух случаях:
 
−
* при старте воспроизведения
 
−
* через некоторое время после начала воспроизведения
 
  
−
При старте это выглядит так:
+
If some permits is not granted, then engine playback can be stopped:
−
  <nowiki>http://127.0.0.1:6878/ace/manifest.m3u8?id=c894b23a65d64a0dae2076d2a01ec6bface83b01&format=json&use_stop_notifications=1
+
* 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": {  
 
     "extra_data": {  
Line 320: Line 316:
 
}</nowiki>
 
}</nowiki>
  
−
Если остановка произойдет через некоторое время после начала воспроизведения, то будет отослано событие <tt>download_stopped</tt>:
+
* sometime after playback was started:
−
  <nowiki>Старт воспроизведения:
+
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
 
http://127.0.0.1:6878/ace/manifest.m3u8?id=c894b23a65d64a0dae2076d2a01ec6bface83b01&format=json&use_api_events=1&use_stop_notifications=1
 
{
 
{
Line 333: Line 330:
 
}
 
}
  
−
Ждем событие по ссылке event_url:
+
Wait for event via event_url:
 
http://127.0.0.1:6878/ace/event/6d12f958332ef0bd258053ba1afd833ddf9b74f9/f528764d624db129b32c21fbca0cb8d6
 
http://127.0.0.1:6878/ace/event/6d12f958332ef0bd258053ba1afd833ddf9b74f9/f528764d624db129b32c21fbca0cb8d6
  
−
При остановке получим такой ответ по event_url:
+
At playback stop response should look like:
 
{
 
{
 
     "response": {
 
     "response": {
Line 348: Line 345:
 
}</nowiki>
 
}</nowiki>
  
−
==Идентификатор плеера==
+
==Player ID==
−
Идентификатор плеера - произвольная строка, которая идентифицирует плеер при обращении к движку. В качестве идентификатора лучше всего использовать случайное число.
+
Player ID ('''pid''') - random string, used for player identification during engine connect session.
  
−
Предназначение идентификатора плеера - дать движку возможность отличать запросы одного плеера от другого. Это связано с таким ограничением - нельзя просматривать одну и ту же live-трансляцию через движок одновременно в двух плеерах. При возникновении такой ситуации результаты непредсказуемы (трансляция может начать идти с перебоями в обоих плеерах). В связи с этим движок перестает отдавать плееру данные по трансляции, если эту же трансляцию запустили в другом плеере, но делает это только в том случае, если может отличить один плеер от другого.
+
"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.

Latest revision as of 21:55, 19 April 2018

About

Since version 3.1 we implemented API to control app engine via HTTP. To do that, you should send appropriate HTTP GET query to the app engine (default IP:port is 127.0.0.1:6878)

Limitations

You can't use HTTP API with AJAX 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.

Checking local engine availability

Send JSON query to http://127.0.0.1:6878/webui/api/service?method=get_version&format=jsonp. If app engine is running, then it return version string in JSON format.

Some examples: 

Query:
http://127.0.0.1:6878/webui/api/service?method=get_version&format=jsonp&callback=mycallback

Response:
mycallback({"result": {"code": 3002300, "version": "3.1.0-rc2"}, "error": null});

Fields description:

  • version - engine version, string ("3.0.12")
  • code - engine version, integer (30012)

Simple page with check button (JSONP-queries served by 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>

Using HTTP API on 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 here.

API methods

Terms: <engine_address> - app engine IP address, <engine_port> - app engine HTTP port. Common params:

  • 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.
  • pid - 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 id, infohash, url must be present.

How to get HLS stream

Query: http://<engine_address>:<engine_port>/ace/manifest.m3u8

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 - http://xml.coverpages.org/nisoLang3-1994.html

Example: 

http://127.0.0.1:6878/ace/manifest.m3u8?id=dd1e67078381739d14beca697356ab76d49d1a2d

How to get HTTP stream

Query: http://<engine_address>:<engine_port>/ace/getstream

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: 

http://127.0.0.1:6878/ace/getstream?id=dd1e67078381739d14beca697356ab76d49d1a2d

How to play HLS broadcast

Query: http://<engine_address>:<engine_port>/hls/manifest.m3u8

You can play via app engine any HLS broadcast, just pass link to the HLS playlist to the engine (manifest_url param).

Params:

  • manifest_url - HLS manifest URL (link to the HLS playlist)

Example: 

http://127.0.0.1:6878/hls/manifest.m3u8?manifest_url=http%3A%2F%2Fwin.cdn.bonus-tv.ru%2FTVB7%2Fntv%2Fplaylist.m3u8

Simple HTML code for playing HLS broadcast in VideoJS player: 

<!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>

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: 

format=json

As response app engine should return some links in JSON format: 

{
    "playback_url": playback_url,
    "stat_url: stat_url,
    "command_url": command_url,
    "event_url": event_url,
}
playback_url
media stream link
stat_url
session statistics link
command_url
engine commands link
event_url
session events link

event_url will be present in engine response only if query contains param use_api_events.

Via playback_url app engine will serve requested media stream. This link should be passed to media player.

Getting some stats

Via stat_url 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: 

Query:
http://127.0.0.1:6878/ace/stat/6d12f958332ef0bd258053ba1afd833ddf9b74f9/f528764d624db129b32c21fbca0cb8d6

Response:
{
  "response": {
    "status": "dl",
    "uploaded": 0,
    "speed_down": 516,
    "speed_up": 0,
    "downloaded": 14155776,
    "peers": 2,
    "total_progress": 0
  },
  "error": null
}

Sending extra commands to the app engine

Via command_url link you can control playback session.

Command name passed to app engine via method param. For the moment you can use only one command: stop - stop playback session. Its recommended to send "stop" command to the app engine when user stops playback in the media player UI/controls.

Example: 

Query:
http://127.0.0.1:6878/ace/cmd/5410b27fc567c35c8547e3b69b141215ce3a1fd7/ef0609c43e560697329d93dae4571edb?method=stop

Response:
{
    "response": "ok",
    "error": null
}

Getting events from the app engine

Via event_url link you can get events from the app engine, using "long polling" method.

As response app engine should return data in the response field (JSON format):

  • name - event name
  • params - object with actual param

In the versions prior to 3003600 response field contains "JSON as string" data. В версиях до 3003600 в поле response передается не сам JSON-объект, а его строковое представление.

Example: 

Query:
http://127.0.0.1:6878/ace/event/5410b27fc567c35c8547e3b69b141215ce3a1fd7/ef0609c43e560697329d93dae4571edb

Response (engine version >= 3003600):
{
    "response": {
        "name": "got_codec_info",
        "params: {
            "audio_codec_id": 86018,
            "video_codec_id": 28
        }
    },
    "error": null
}

Response (engine version < 3003600):
{
    "response": "{\"name\": \"got_codec_info\"}, \"params\": {\"audio_codec_id\": 86018, \"video_codec_id\": 28}",
    "error": null
}


When current playback session has stopped, event_url response looks like: 

{
    "response": null,
    "error": "download stopped"
}

And player should stop sending queries to event_url.

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 ffmpeg libavcodec, 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
reason - stop reason, possible values:
missing_option - content not free, "paid option" is missing.
option - missing option ID (for reason=missing_option)

Javascript example

Using jQuery library. 

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");

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 use_stop_notifications=1 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:
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"
}
  • sometime after playback was started:

If playback was stopped after some time, then engine will send a download_stopped event: 

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
}

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.

Retrieved from "https://wiki.acestream.media/index.php?title=Engine_HTTP_API&oldid=662"