117
edits
Changes
no edit summary
==About==
Since version 3.1 we implemented API to control app engine via HTTP. To do that, you should send appropriate HTTP GET query to engine (default IP:port is 127.0.0.1:6878)
==Limitations==
You can't use HTTP API with AJAX queries from secured (https) pages, because HTTP API is not secured, and such behaviour (http query from https page) will be blocked by browser.
So you must have and serve a dedicated unsecured page on your secured site to work with engine HTTP API.
==Checking local engine availability==
Send JSON query to <nowiki>http://127.0.0.1:6878/webui/api/service?method=get_version&format=jsonp</nowiki>. If app engine is running, then it return version string in JSON format.
Some examples:
1. Query:
<nowiki>
http://127.0.0.1:6878/webui/api/service?method=get_version&format=jsonp&callback=mycallback
Response:
mycallback({"result": {"code": 3002300, "version": "3.1.0-rc2"}, "error": null});</nowiki>
Fields description:
*'''version''' - версияengine движкаversion, в виде строкиstring (например, "3.0.12")
*'''code''' - engine version, integer (30012)
2. Simple page with check button (JSONP-queries served by jQuery):
<nowiki><!DOCTYPE html>
<html>
</html></nowiki>
==Методы API methods==
Common params:
*'''sid''' - [[#player id|player id]] (optional)
*'''id''' - идентификатор контента (content id) (условно обязательныйconditional параметрparam)
*'''infohash''' - infohashtransport транспортногоfile файлаinfohash (.acelive либоor .torrent файлаfile) (условно обязательныйconditional параметрparam)
*'''url''' - link to transport file (conditional param)
*'''path''' - local path to transport file (conditional param)
===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 (3-значный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 HTTP stream===
Query:
<tt><nowiki>http://<engine_address>:<engine_port>/ace/getstream</nowiki></tt>
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''' - URLHLS трансляции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>
</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,
;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": {
}</nowiki>
===Sending extra commands to the app engine===
Via <tt>command_url</tt> link you can control playback session.
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",
}</nowiki>
===Getting events from the app engine===
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:
Query:
http://127.0.0.1:6878/ace/event/5410b27fc567c35c8547e3b69b141215ce3a1fd7/ef0609c43e560697329d93dae4571edb
{
"response": {
}
{
"response": "{\"name\": \"got_codec_info\"}, \"params\": {\"audio_codec_id\": 86018, \"video_codec_id\": 28}",
When current playback session has stopped, <tt>event_url</tt> response looks like:
<nowiki>{
"response": null,
}</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 на javascriptexample====
<nowiki>function startEventListener() {
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": {
}</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
{
}
http://127.0.0.1:6878/ace/event/6d12f958332ef0bd258053ba1afd833ddf9b74f9/f528764d624db129b32c21fbca0cb8d6
At playback stop response should look like:
{
"response": {
}</nowiki>
==Player ID==
Player ID - random string, used for impersonate player during engine connect session.
Player ID purpose - app engine should distinguish one player from another, as in the current engine implementation user cannot play the same live-stream with two (or more) players from one engine, and engine will stop to serve requests from one player, when got a new request from another.
