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.)
==Методы APILimitations==В описаниях методов <tt>You can''<engine_address>''</tt> - это ip-адрес движка, <tt>''<engine_port>''</tt> - http-порт движка.Все методы принимают такие общие параметры:*'''sid''' - [[#Идентификатор плеера|идентификатор плеера]] t use HTTP API with AJAX queries from secured (необязательный параметрhttps)*'''id''' - идентификатор контента pages, because HTTP API is not secured, and such behaviour (content id) (условно обязательный параметрhttp query from https page)will be blocked by browser.*'''url''' - ссылка на транспортный файл (условно обязательный параметр)*'''path''' - путь к транспортному файлу в локальной файловой системе (условно обязательный параметр)So you must have and serve a dedicated unsecured page on your secured site to work with engine HTTP API.
<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.