117
edits
Changes
→API methods
==Общее описание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.
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});</nowiki>
<nowiki><!DOCTYPE html>
<html>
</html></nowiki>
==Методы Using HTTP APIon 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''' - [[#Идентификатор плеера|идентификатор плеера]] (необязательный параметр)*'''id''' - идентификатор контента (content id) (условно обязательный параметр)*'''infohash''' - infohash транспортного файла (.acelive либо .torrent файла)(условно обязательный параметр)*'''url''' - ссылка на транспортный файл (условно обязательный параметр)*'''path''' - путь к транспортному файлу в локальной файловой системе (условно обязательный параметр)
===Получение потока в формате HLS=API methods==Terms: <tt>''<nowikiengine_address>http:/''</tt> - app engine IP address, <engine_addresstt>:''<engine_port>''</acett> - 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:/manifest.m3u8</nowiki><path/tt>" 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''')
<nowiki>http://127.0.0.1:6878/ace/manifest.m3u8?id=dd1e67078381739d14beca697356ab76d49d1a2d</nowiki>
===Получение потока по How to get HTTPstream===Query: <tt><nowiki>http://<engine_address>:<engine_port>/ace/getstream</nowiki></tt>
<nowiki>http://127.0.0.1:6878/ace/getstream?id=dd1e67078381739d14beca697356ab76d49d1a2d</nowiki>
===Запуск How to play HLS-трансляцииbroadcast===Query: <tt><nowiki>http://<engine_address>:<engine_port>/hls/manifest.m3u8</nowiki></tt>
<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><!DOCTYPE html>
<html>
</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>
http://127.0.0.1:6878/ace/stat/6d12f958332ef0bd258053ba1afd833ddf9b74f9/f528764d624db129b32c21fbca0cb8d6
{
"response": {
},
"error": null
}</nowiki>
===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.
Example:
<nowiki>
Query:
http://127.0.0.1:6878/ace/cmd/5410b27fc567c35c8547e3b69b141215ce3a1fd7/ef0609c43e560697329d93dae4571edb?method=stop
Response:
{
"response": "ok",
"error": null
}</nowiki>
===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
In the versions prior to 3003600 <tt>response</tt> field contains "JSON as string" data.
В версиях до 3003600 в поле <tt>response</tt> передается не сам JSON-объект, а его строковое представление.
Example:
<nowiki>
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
}</nowiki>
When current playback session has stopped, <tt>event_url</tt> response looks like:
<nowiki>{
"response": null,
"error": "download stopped"
}</nowiki>
And player should stop sending queries to <tt>event_url</tt>.
====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, [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
: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>)
====Javascript example====
Using [https://jquery.com jQuery] library.
<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>
==<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.
