==Общее описание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-адрес движкаt use HTTP API with AJAX queries from secured (https) pages, because HTTP API is not secured, <tt>''<engine_port>''</tt> - and such behaviour (http-порт движкаquery from https page) will be blocked by browser.Все методы принимают такие общие параметры:*'''sid''' - [[#Идентификатор сессии|идентификатор сессии]] (необязательный параметр)So you must have and serve a dedicated unsecured page on your secured site to work with engine HTTP API.
===Получение потока в формате HLS=Checking local engine availability==<tt>Send JSON query to <nowiki>http://<engine_address>127.0.0.1:<engine_port>6878/webui/aceapi/manifest.m3u8service?method=get_version&format=jsonp</nowiki></tt>. If app engine is running, then it return version string in JSON format.
В ответ на данную команду движок выдаст HLS плейлист для воспроизведения запрашиваемого контентаSome examples: <nowiki>Query:http://127. В случае ошибки будет возвращен HTTP код 4хх либо 5хх с кратким описанием ошибки0.0.1:6878/webui/api/service?method=get_version&format=jsonp&callback=mycallback
Воспроизведение в формате HLS доступно только для live-трансляцийResponse:mycallback({"result": {"code": 3002300, "version": "3. При попытке запустить VOD с помощью данной команды движок выдаст ошибку1.0-rc2"}, "error": null});</nowiki>
ПараметрыFields description:*'''idversion''' - идентификатор контента engine version, string (content id"3.0.12")*'''code''' - engine version, integer (30012)
ПримерSimple page with check button (JSONP-queries served by jQuery): <nowiki><!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></nowiki> ==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[[Using_Ace_Stream_as_service_on_Android|here]]. ==API methods==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''') In the query to the app engine at least one of params <tt>id</tt>, <tt>infohash</tt>, <tt>url</tt> must be present. ===How to get HLS stream===Query: <tt><nowiki>http://<engine_address>:<engine_port>/ace/manifest.m3u8</nowiki></tt> 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:
<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> 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> ===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 progressive download://127. В случае ошибки будет возвращен HTTP код 4хх либо 5хх с кратким описанием ошибки0.0.1:6878/ace/cmd/5410b27fc567c35c8547e3b69b141215ce3a1fd7/ef0609c43e560697329d93dae4571edb?method=stop
ПараметрыResponse:*'''id''' - идентификатор контента (content id){ "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> * 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/getstreammanifest.m3u8?id=dd1e67078381739d14beca697356ab76d49d1a2dc894b23a65d64a0dae2076d2a01ec6bface83b01&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.
Предназначение идентификатора плеера "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.
