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> 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: <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> Simple HTML code for playing HLS broadcast in VideoJS player: <nowiki><!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></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> As response app engine should return some links in JSON format: <tt><nowiki>{ "playback_url": playback_url, "stat_url: stat_url, "command_url": command_url, "event_url": event_url,}</nowiki></tt> ;playback_url:media stream link;stat_url:session statistics link;command_url:engine commands link;event_url:session events link <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. ===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: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}</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 listenerstartEventListener("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>
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.