Difference between revisions of "Engine HTTP API"

From Ace Stream Wiki
Jump to: navigation, search
(→‎Методы API)
(→‎Получение статистики)
Line 115: Line 115:
 
</html></nowiki>
 
</html></nowiki>
  
−
==Получение статистики==
+
==Расширенные возможности==
−
Движок при необходимости может отдавать статистику по текущей сессии воспроизведения (скорость загрузки, кол-во подсоединенных узлов и т.д.)
+
Движок предоставляет некоторые дополнительные возможности по управлению сессией воспроизведения.
 +
Сюда входит возможность отправлять движку дополнительные команды, получать информацию про сессию воспроизведения, а также получать некоторые события.
 +
Для получения доступа к расширенным возможностям необходимо добавить такой параметр при старте сессии воспроизведения:
 +
<tt>format=json</tt>
 +
       
 +
При получении данного параметра движок выдаст в ответ не медиа-поток, а набор ссылок в формате JSON:
 +
<tt><nowiki>{
 +
    "playback_url": playback_url,
 +
    "stat_url: stat_url,
 +
    "command_url": command_url,
 +
    "event_url": event_url,
 +
}</nowiki></tt>
  
−
Для получения статистики необходимо запросить у движка URL статистики при старте воспроизведения. Для этого нужно добавить параметр format=json в запрос на воспроизведение. При наличии данного параметра движок вернет ответ в формате JSON с двумя ссылками:
+
;playback_url
−
*'''playback_url''' - ссылка для воспроизведения (по этой ссылке движок отдаст HLS-манифест либо HTTP-поток)
+
:ссылка для получения медиа-потока
−
*'''stat_url''' - ссылка для получения статистики
+
;stat_url
 +
:ссылка для получения информации про сессию
 +
;command_url
 +
:ссылка для отправки команд движку
 +
;event_url
 +
:ссылка для получения событий
  
−
Пример:
+
<tt>event_url</tt> в ответе выдается только в том случае, если страт выполнялся с параметром <tt>use_api_events</tt>.
−
<nowiki>Запрос:
+
 
−
http://127.0.0.1:6878/ace/manifest.m3u8?id=dd1e67078381739d14beca697356ab76d49d1a2d&format=json
+
По ссылке <tt>playback_url</tt> движок отдаст запрошенный медиа-поток. Эту ссылку необходимо передать плееру.
  
−
Ответ:
+
===Получение статистики===
−
{
 
−
  "stat_url": "http://127.0.0.1:6878/ace/stat/6d12f958332ef0bd258053ba1afd833ddf9b74f9/f528764d624db129b32c21fbca0cb8d6",
 
−
  "playback_url": "http://127.0.0.1:6878/ace/m/6d12f958332ef0bd258053ba1afd833ddf9b74f9/f528764d624db129b32c21fbca0cb8d6.m3u8"
 
−
}</nowiki>
 
  
 
По ссылке <tt>stat_url</tt> движок возвращает ответ в формате JSON с такими полями:
 
По ссылке <tt>stat_url</tt> движок возвращает ответ в формате JSON с такими полями:
Line 160: Line 172:
 
   "error": null
 
   "error": null
 
}</nowiki>
 
}</nowiki>
 +
       
 +
===Отправка команд движку===
 +
По ссылке <tt>command_url</tt> движок принимает команды для управления сессией воспроизведения.
 +
 +
Название команды передается в параметре <tt>method</tt>.
 +
 +
На данный момент доступна одна команда: <tt>stop</tt> - остановить сессию воспроизведения.
 +
 +
Рекомендуется всегда останавлить сессию воспроизведения с помощью этой команды, когда воспроизведение останавливается на уровне плеера.
 +
 +
Пример:
 +
<nowiki>Запрос:
 +
http://127.0.0.1:6878/ace/cmd/5410b27fc567c35c8547e3b69b141215ce3a1fd7/ef0609c43e560697329d93dae4571edb?method=stop
 +
 +
Ответ:
 +
{
 +
    "response": "ok",
 +
    "error": null
 +
}</nowiki>
 +
       
 +
===Получение событий от движка===
 +
Ссылка <tt>event_url</tt> используется для получения событий от движка методом long polling.
 +
 +
Данные по событию возвращаются в поле <tt>response</tt> в виде JSON-объекта с такими полями:
 +
;name
 +
:название события
 +
;params
 +
:объект с параметрами (значения зависят от события)
 +
 +
В версиях до 3003600 в поле <tt>response</tt> передается не сам JSON-объект, а его строковое представление.
 +
 +
Пример:
 +
<nowiki>Запрос:
 +
http://127.0.0.1:6878/ace/event/5410b27fc567c35c8547e3b69b141215ce3a1fd7/ef0609c43e560697329d93dae4571edb
 +
 +
Ответ (версия движка >= 3003600):
 +
{
 +
    "response": {
 +
        "name": "got_codec_info",
 +
        "params: {
 +
            "audio_codec_id": 86018,
 +
            "video_codec_id": 28
 +
        }
 +
    },
 +
    "error": null
 +
}
 +
 +
Ответ (версия движка < 3003600):
 +
{
 +
    "response": "{\"name\": \"got_codec_info\"}, \"params\": {\"audio_codec_id\": 86018, \"video_codec_id\": 28}",
 +
    "error": null
 +
}</nowiki>
 +
 +
 +
Когда текущая сессия воспроизведения будет остановлена, <tt>event_url</tt> вернет такой ответ:
 +
<nowiki>{
 +
    "response": null,
 +
    "error": "download stopped"
 +
}</nowiki>
 +
 +
После получения такого ответа необходимо прекратить отсылать запросы на <tt>event_url</tt>.
 +
 +
====Список событий====
 +
;missing_content
 +
:движок не может найти запрашиваемый сегмент при воспроизведении HLS (плеер должен перемотать на live)
 +
;got_codec_info
 +
:доступна информация по кодекам потока.
 +
:;параметры:
 +
::video_codec_id - идентификатор видеокодека
 +
::audio_codec_id - идентификатор аудиокодека
 +
:Идентификаторы кодеков взяты из библиотеки ffmpeg, их можно найти [https://ffmpeg.org/doxygen/trunk/avcodec_8h_source.html здесь]
 +
:Данное событие можно использовать для вывода сообщения в случае, если плеер не поддерживает данные кодеки.
 +
;segmenter_failed
 +
:встроенный в движок HLS-сегментатор не смог обработать поток (плеер должен остановить воспроизведение)
 +
 +
====Пример на javascript====
 +
Данный пример использует библиотеку [https://jquery.com jQuery].
 +
 +
<nowiki>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");</nowiki>
  
 
==Идентификатор плеера==
 
==Идентификатор плеера==

Revision as of 13:56, 3 December 2015

Общее описание

Начиная с версии 3.1 появилась возможность управлять движком по протоколу HTTP. Для передачи команды движку нужно отправить HTTP GET запрос на http-порт движка. Порт по умолчанию: 6878.

Проверка наличия движка

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

Пример запроса: 

Запрос:
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});

Ответ состоит и таких полей:

  • version - версия движка в виде строки (например, 3.0.12)
  • code - версия движка в виде целого числа (для удобства сравнения версий, например 30012)

Пример HTML-страницы с кнопкой для проверки движка (JSONP-запросы отправляются с помощью библиотеки 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>

Методы API

В описаниях методов <engine_address> - это ip-адрес движка, <engine_port> - http-порт движка. Все методы принимают такие общие параметры:

  • sid - идентификатор плеера (необязательный параметр)
  • id - идентификатор контента (content id) (условно обязательный параметр)
  • infohash - infohash транспортного файла (.acelive либо .torrent файла) (условно обязательный параметр)
  • url - ссылка на транспортный файл (условно обязательный параметр)
  • path - путь к транспортному файлу в локальной файловой системе (условно обязательный параметр)

В запросах на старт воспроизведения обязательно должен присутствовать один из параметров id, infohash, url, path.

Получение потока в формате HLS

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

В ответ на данную команду движок выдаст HLS плейлист для воспроизведения запрашиваемого контента. В случае ошибки будет возвращен HTTP код 4хх либо 5хх с кратким описанием ошибки.

Параметры:

  • transcode_audio - транскодировать аудио в AAC (параметр принимает значения 0 либо 1)
  • transcode_mp3 - не транскодировать MP3 (параметр принимает значения 0 либо 1)
  • preferred_audio_language - предпочитаемый язык аудио-дорожки (3-значный код, список здесь)

Пример: 

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

Получение потока по HTTP

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

В ответ на данную команду движок будет выдавать данные в виде http progressive download. В случае ошибки будет возвращен HTTP код 4хх либо 5хх с кратким описанием ошибки.

Пример: 

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

Запуск HLS-трансляции

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

Данная команда позволяет запустить через движок любую HLS-трансляцию. Для запуска достаточно передать движку ссылку на HLS-плейлист (параметр manifest_url).

Параметры:

  • manifest_url - URL трансляции (ссылка на плейлист HLS-трансляции)

Пример: 

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

Пример HTML-страницы для запуска HLS-трансляции через движок в плеере VideoJS: 

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

Расширенные возможности

Движок предоставляет некоторые дополнительные возможности по управлению сессией воспроизведения. Сюда входит возможность отправлять движку дополнительные команды, получать информацию про сессию воспроизведения, а также получать некоторые события. Для получения доступа к расширенным возможностям необходимо добавить такой параметр при старте сессии воспроизведения: 

format=json

При получении данного параметра движок выдаст в ответ не медиа-поток, а набор ссылок в формате JSON: 

{
    "playback_url": playback_url,
    "stat_url: stat_url,
    "command_url": command_url,
    "event_url": event_url,
}
playback_url
ссылка для получения медиа-потока
stat_url
ссылка для получения информации про сессию
command_url
ссылка для отправки команд движку
event_url
ссылка для получения событий

event_url в ответе выдается только в том случае, если страт выполнялся с параметром use_api_events.

По ссылке playback_url движок отдаст запрошенный медиа-поток. Эту ссылку необходимо передать плееру.

Получение статистики

По ссылке stat_url движок возвращает ответ в формате JSON с такими полями:

  • status - статус сессии воспроизведения:
    • prebuf - пребуферизация
    • dl - воспроизведение
  • peers - кол-во подсоединенных узлов
  • speed_down - скорость скачивания (Кбайт/с)
  • speed_up - скорость отдачи (Кбайт/с)
  • downloaded - объем скачанных данных (байт)
  • uploaded - объем отданных данных (байт)
  • total_progress - процент загруженных данных от суммарного объема (для VOD); для live всегда 0

Пример: 

Запрос:
http://127.0.0.1:6878/ace/stat/6d12f958332ef0bd258053ba1afd833ddf9b74f9/f528764d624db129b32c21fbca0cb8d6

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

Отправка команд движку

По ссылке command_url движок принимает команды для управления сессией воспроизведения.

Название команды передается в параметре method.

На данный момент доступна одна команда: stop - остановить сессию воспроизведения.

Рекомендуется всегда останавлить сессию воспроизведения с помощью этой команды, когда воспроизведение останавливается на уровне плеера.

Пример: 

Запрос:
http://127.0.0.1:6878/ace/cmd/5410b27fc567c35c8547e3b69b141215ce3a1fd7/ef0609c43e560697329d93dae4571edb?method=stop

Ответ:
{
    "response": "ok",
    "error": null
}

Получение событий от движка

Ссылка event_url используется для получения событий от движка методом long polling.

Данные по событию возвращаются в поле response в виде JSON-объекта с такими полями:

name
название события
params
объект с параметрами (значения зависят от события)

В версиях до 3003600 в поле response передается не сам JSON-объект, а его строковое представление.

Пример: 

Запрос:
http://127.0.0.1:6878/ace/event/5410b27fc567c35c8547e3b69b141215ce3a1fd7/ef0609c43e560697329d93dae4571edb

Ответ (версия движка >= 3003600):
{
    "response": {
        "name": "got_codec_info",
        "params: {
            "audio_codec_id": 86018,
            "video_codec_id": 28
        }
    },
    "error": null
}

Ответ (версия движка < 3003600):
{
    "response": "{\"name\": \"got_codec_info\"}, \"params\": {\"audio_codec_id\": 86018, \"video_codec_id\": 28}",
    "error": null
}


Когда текущая сессия воспроизведения будет остановлена, event_url вернет такой ответ: 

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

После получения такого ответа необходимо прекратить отсылать запросы на event_url.

Список событий

missing_content
движок не может найти запрашиваемый сегмент при воспроизведении HLS (плеер должен перемотать на live)
got_codec_info
доступна информация по кодекам потока.
параметры
video_codec_id - идентификатор видеокодека
audio_codec_id - идентификатор аудиокодека
Идентификаторы кодеков взяты из библиотеки ffmpeg, их можно найти здесь
Данное событие можно использовать для вывода сообщения в случае, если плеер не поддерживает данные кодеки.
segmenter_failed
встроенный в движок HLS-сегментатор не смог обработать поток (плеер должен остановить воспроизведение)

Пример на javascript

Данный пример использует библиотеку jQuery. 

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

Идентификатор плеера

Идентификатор плеера - произвольная строка, которая идентифицирует плеер при обращении к движку. В качестве идентификатора лучше всего использовать случайное число.

Предназначение идентификатора плеера - дать движку возможность отличать запросы одного плеера от другого. Это связано с таким ограничением - нельзя просматривать одну и ту же live-трансляцию через движок одновременно в двух плеерах. При возникновении такой ситуации результаты непредсказуемы (трансляция может начать идти с перебоями в обоих плеерах). В связи с этим движок перестает отдавать плееру данные по трансляции, если эту же трансляцию запустили в другом плеере, но делает это только в том случае, если может отличить один плеер от другого.

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