Wiki/Main Page

2020-06-11T19:37:39Z

Ffx: Changed redirect target from Https://wiki.acestream.org/Main Page to Main Page

#REDIRECT [[Main_Page]]

Wiki/Main Page

2020-06-09T16:56:23Z

Ffx:

MediaWiki:Sidebar

2020-06-09T16:54:05Z

Ffx:

Main Page

2020-06-08T19:54:31Z

Ffx: Created page with "'''Ace Stream''' is a media platform of a new generation with a decentralized system of delivering and storing multimedia data, which is designed to create Internet services w..."

2018-07-03T14:50:34Z

Ffx:

There are two configuration files:
* main (acestream.conf)
* user-defined (acestream_user.conf)

Engine reads configuration files on startup. First the main file is read, then engine reads user-defined file if it exists.
Options in user-defined file overwrite the same options in the main file.

The reason to have two configuration files is because the auto-update system on Windows prevents main file from being modified. You can change the main file but if will be restored to the original state during the next auto-update.

On Windows files are located here:
* main: %APPDATA%/ACEStream/engine/acestream.conf
* user-defined: %APPDATA%/ACEStream/engine/acestream_user.conf

Engine does not check configuration files at runtime, there are only read on startup. So of you want to update configuration please follow these steps:
* stop engine
* update user-defined configuration file (create it if it doesn't exist)
* start engine

Search API

2018-05-23T13:06:32Z

Ffx: /* search */

==Description==
Search API allows to search content in the Ace Stream P2P Network.

It can be accessed by two ways:
*using Ace Stream Engine endpoint
*using server-side endpoint

There are several differences between these two methods.

Engine search API:
*is free to use
*has a limit of total requests coming from certain engine instance per day
*has a limit on requests frequency
*is suitable for making search requests from installed applications

Server-side search API:
*is paid
Server-side search API provides 1000 search queries for free. If you need more, you may sign up for billing in the the admin-panel. Additional requests cost $1 per 10000 queries.
*has no limits
*allows to get search database snapshot
*is suitable for making server-to-server API calls

===<span style="color: #900;">Beta testing period</span>===
Server-side Search API is currently in beta testing and '''is free to use'''.

You can get personal API keys in the admin-panel at www.acestream.org after the end of the beta testing period of Ace Stream Search API.

==Engine Search API==
Endpoint:
<tt><nowiki>http://localhost:6878/server/api</nowiki></tt>

Ace Stream Engine must be running on the localhost.

Mandatory parameters:
*'''method''' - API method name
*'''token''' - Engine API access token (see below)

Each request must contain Engine API access token which must be retrieved by this request:
<tt><nowiki>http://localhost:6878/server/api?method=get_api_access_token</nowiki></tt>

Token is sent in the response:
<tt><nowiki>{
"result": {
"token": "9d324ef909c50629ca3d23faddaa7358236b0bbe62dfd049416dc4d570b60b57"
},
"error": null
}</nowiki></tt>

Method "get_api_access_token" does not allow cross-domain requests so it cannot be called from regular javascript on the web page.

==Server-side Search API==
Endpoint:
<tt><nowiki>https://search.acestream.net</nowiki></tt>

Mandatory parameters:
*'''method''' - API method name
*'''api_version''' - API version (currently it must be set to 1.0)
*'''api_key''' - API key (your personal key)

To obtain you personal API key you must register and request it.

Currently server-side API works in beta-testing mode and is available with API key "test_api_key".

==Response format==
All responses are in JSON format.

General response format is:
*success
<tt><nowiki>{
"result": <object>,
"error": null
}</nowiki></tt>
*error
<tt><nowiki>{
"result": null,
"error": "error description"
}</nowiki></tt>

==API methods==
===search===
Makes a search request

Parameters:
*'''query''' (string) - search query
*'''category''' (string) - filter by category (list of categories [[Channel Category|here]])
*'''page''' (integer) - page number (starting from 0, default is 0)
*'''page_size''' (integer) - page size (default is 10, maximum value is 200)
*'''group_by_channels''' (boolean, 0 or 1) - group output results by channel name (see examples)
*'''show_epg''' (boolean, 0 or 1) - include EPG in the response (this works only when group_by_channels=1)

Response fields:
*'''total''' (integer) - total number of found items
*'''results''' (array of objects) - array of results (each result is an object, see below)
*'''time''' (float) - query execution time

Single item fields:
*'''infohash''' (string) - channel infohash (unique identifier); it should be used to start channel playback
*'''name''' (string) - channel name
*'''bitrate''' (integer) - channel estimated bitrate (bytes per second)
*'''categories''' (array of strings) - channel categories
*'''availability_updated_at''' (integer) - unix timestamp when channel availability was last updated at
*'''availability''' (float) - channel availability (number between 0-1)
*'''status''' (integer) - channel status based on its availability; 2 means "green" status - channel is available; 1 means "yellow" status - there is no guaranty that channel is working. Can be used in query as additional filter.
*'''in_playlist''' (boolean) - true if the channel is included in user's playlist (available only on engine endpoint)

===all===
This method retrieves search database snapshot.

Data is returned "as-is": there is no filtering, sorting or pagination.

'''IMPORTANT''': this method is available on server-side endpoint only.

Example:
<tt><nowiki>https://search.acestream.net/all?api_version=1.0&api_key=test_api_key</nowiki></tt>

==Examples==

===Simple output===
*engine endpoint
<tt><nowiki>http://localhost:6878/server/api?method=search &crarr;
&token=9d324ef909c50629ca3d23faddaa7358236b0bbe62dfd049416dc4d570b60b57 &crarr;
&query=discovery</nowiki></tt>
*server-side endpoint
<tt><nowiki>https://search.acestream.net/?method=search &crarr;
&api_version=1.0 &crarr;
&api_key=test_api_key &crarr;
&query=discovery</nowiki></tt>

Response:
<tt><nowiki>{
"result": {
"total": 28,
"results": [
{
"name": "Discovery HD",
"bitrate": 506347,
"availability_updated_at": 1494970802,
"infohash": "09f1511aa2a596162bfb4f4d1146c2be545733f4",
"availability": 1,
"categories": [
"educational"
]
},
{
"name": "Discovery HD Showcase",
"bitrate": 504510,
"availability_updated_at": 1494970802,
"infohash": "948e1b51363cc07ec4ac20ef10dc099f8c7e20b8",
"availability": 1,
"categories": [
"educational"
]
},
... # some results are omitted
],
"time": "0.0237"
},
"error": null
}</nowiki></tt>

===Grouped by channel name results===
*engine endpoint:
<tt><nowiki>http://localhost:6878/server/api?method=search &crarr;
&token=9d324ef909c50629ca3d23faddaa7358236b0bbe62dfd049416dc4d570b60b57 &crarr;
&query=discovery &crarr;
&group_by_channels=1 &crarr;
&show_epg=1</nowiki></tt>
*server-side endpoint:
<tt><nowiki>https://search.acestream.net/?method=search &crarr;
&api_version=1.0 &crarr;
&api_key=test_api_key &crarr;
&query=discovery &crarr;
&group_by_channels=1 &crarr;
&show_epg=1</nowiki></tt>

Response:
<tt><nowiki>{
"result": {
"total": 11,
"results": [
{
"items": [
{
"status": 2,
"name": "Discovery HD",
"bitrate": 506347,
"channel_id": 845,
"availability_updated_at": 1494971282,
"infohash": "09f1511aa2a596162bfb4f4d1146c2be545733f4",
"availability": 1,
"categories": [
"educational"
]
}
],
"name": "Discovery HD"
},
{
"items": [
{
"status": 2,
"name": "Discovery Channel",
"bitrate": 215035,
"channel_id": 845,
"availability_updated_at": 1494971282,
"infohash": "6651feec9de120abf362c380841150cdc2742df2",
"availability": 0.99282296650718,
"categories": [
"educational"
]
},
{
"status": 1,
"name": "Discovery Channel",
"infohash": "e97bbddc4febc01f649c30013fd221e9adf43622",
"channel_id": 845,
"availability_updated_at": 1494964321,
"availability": 1,
"categories": [
"tv"
]
}
],
"name": "Discovery Channel"
},
{
"items": [
{
"status": 2,
"in_playlist": false,
"name": "Discovery Science",
"bitrate": 350000,
"channel_id": 851,
"availability_updated_at": 1494971282,
"infohash": "dacdcf48e9238d23d7bd687c8e00cac0d16dc177",
"availability": 1,
"categories": [
"educational"
]
},
{
"status": 2,
"name": "Discovery Science",
"bitrate": 215035,
"channel_id": 851,
"availability_updated_at": 1494971282,
"infohash": "c2c2c2bfda8440ae0781df0e06ccf13dda529737",
"availability": 0.98648648648649,
"categories": [
"educational"
]
}
],
"icon": "http://c1.torrentstream.info/epg/icons/3349.png",
"name": "Discovery Science",
"epg": {
"start": "1494970200",
"stop": "1494971700",
"name": "Как это сделано? (20-я серия) (12+)"
}
},
... # some results are omitted
],
"time": "0.0421"
},
"error": null
}</nowiki></tt>

Engine HTTP API

2018-04-19T19:55:00Z

Ffx: /* 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 query to the app 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:
<nowiki>
Query:
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)

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 HTTP stream===
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://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.

"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.

Engine HTTP API

2018-04-19T19:53:53Z

Ffx: /* 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 query to the app 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:
<nowiki>
Query:
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)

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''', beginning 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 HTTP stream===
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://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.

"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.

Заглавная страница/en

2018-04-19T11:57:07Z

Ffx:

Playlist API

2018-04-19T11:55:35Z

Ffx: /* Brief description */

''Added in version 3.1.28''

== Brief description ==
Playlist API allows to export playlist in different formats from Ace Stream Media Server.

API endpoint:
<tt>'''<nowiki>http://<engine_host>:6878/playlist/get</nowiki>'''</tt>

'''Parameters:'''

* ''format'' (list) - set output format;
* ''category'' (list) - filter by category (media type);
* ''subcategory'' (string) - filter by subcategory (tags);
* ''favorites'' (bool, default is 0) - filter favorites; favorites=0 means to output both favorite and non-favorite items;
* ''items'' (list of integers) - filter by playlist item ids;
* ''host'' (string) - configure playback URL: set "host" part of URL. Actually this is an IP address of Ace Stream Media Server. By default the host from endpoint URL is used;
* ''protocol'' (string, defaults to server settings) - configure playback URL: set output protocol (http or hls);
* ''transcode_audio'' (bool, defaults to server settings) - configure playback URL: enabled audio transcoding;
* ''transcode_mp3'' (bool, defaults to server settings) - configure playback URL: transcode MP3 to AAC (by default MP3 is not transcoded);
* ''transcode_ac3'' (bool, defaults to server settings) - configure playback URL: transcode only AC3 to AAC and don't transcode other codecs;
* ''preferred_audio_language'' (string, defaults to server settings) - configure playback ULR: set preferred audio language;
* ''download'' (bool, default is 0) - download playlist as file;
* ''skip_autosearch'' (bool, default is 0) - don't replace playlist data with autosearch results; this doesn't affect playlist items with disabled autosearch.
* ''generate_player_id'' (bool, default is 0) - with this option engine will output playlist with random '''pid''' ([[Engine_HTTP_API#Player ID]]) for each item.

Boolean values are passed as 0 or 1 (e.g. transcode_audio=1), list of integers is passed as string of values concatenated with comma (e.g. items=14,115,127).

Allowed values for list parameters:

* '''format''' - acestream, m3u, json;
* '''category''' - tv, movies, music_video, music, other;
* '''protocol''' - http, hls.

== Playlist output formats ==
"'''m3u'''" format is intented for different media players.

"'''acestream'''" format is used to export playlist in such way so it can be imported in the Ace Stream software running somewhere else.
At the moment we use M3U format with some additional fields, specific to Ace Stream.
Each playlist item is identified either by Content ID (start with acestream://) or infohash (starts with magnet:). Infohash is used when Content ID is not available for some playlist item.
Both types of identifiers are recognized by Ace Stream Media Server when playlist is imported.

"'''json'''" format is indented to be used for automation. Playlist is returned as list of items, each item is an object with such fields:
* ''id'' (integer) - playlist item id unique for this media server; this id can be passed in "items" parameter to filter specific playlist items;
* ''title'' (string) - title;
* ''playback_url'' (string) playback URL;
* ''content_id'' (string) - Content ID (may be null);
* ''infohash'' (string) - infohash (may be null);
* ''transport_file_url'' (string) - transport file URL (may be null);
* ''category'' (string) - media type (see list for "category" parameter);
* ''is_live'' (integer) - 1: live content, 0: VOD, -1: unknown;
* ''auto_search'' (bool) - whether autosearch is enabled for this playlist item;
* ''tags'' (list of strings) - list of tags.

== Examples ==
'''Get playlist in "m3u" format:'''

Request:
<nowiki>http://127.0.0.1:6878/playlist/get?format=m3u</nowiki>

Response:

#EXTM3U
#EXTINF:-1,Test Channel 1
<nowiki>http://127.0.0.1:6878/ace/getstream?id=acbfd1954084ffc68c65b0948485e5d0f82173e2&hlc=1&transcode_audio=0
&transcode_mp3=0&transcode_ac3=0&preferred_audio_language=eng</nowiki>
#EXTINF:-1 acestream-autosearch="1",Test Channel 2
<nowiki>http://127.0.0.1:6878/ace/getstream?infohash=7889e5f0cea9b72f5dcd7a9c67e665c7f4f5b3eb&hlc=1&transcode_audio=0
&transcode_mp3=0&transcode_ac3=0&preferred_audio_language=eng</nowiki>

'''Get playlist in "acestream" format:'''

Request:
<nowiki>http://127.0.0.1:6878/playlist/get?format=acestream</nowiki>

Response:
#EXTM3U
#EXTINF:-1,Test Channel 1
acestream://acbfd1954084ffc68c65b0948485e5d0f82173e2
#EXTINF:-1 acestream-autosearch="1",Test Channel 2
magnet:?xt=urn:btih:7889e5f0cea9b72f5dcd7a9c67e665c7f4f5b3eb

'''Get playlist in "json" format:'''

Request:
<nowiki>http://127.0.0.1:6878/playlist/get?format=json</nowiki>

Response:
[
{
"category": "tv",
"auto_search": false,
"title": "Test Channel 1",
"playback_url": "<nowiki>http://127.0.0.1:6878/ace/getstream?id=acbfd1954084ffc68c65b0948485e5d0f82173e2&hlc=1&transcode_audio=0
&transcode_mp3=0&transcode_ac3=0&preferred_audio_language=eng</nowiki>",
"is_live": 1,
"transport_file_url": null,
"content_id": "acbfd1954084ffc68c65b0948485e5d0f82173e2",
"infohash": "a1231ebb2a26263cb37b305fced076961990812e",
"id": 3
},
{
"category": "tv",
"auto_search": true,
"title": "Test Channel 2",
"playback_url": "<nowiki>http://127.0.0.1:6878/ace/getstream?infohash=7889e5f0cea9b72f5dcd7a9c67e665c7f4f5b3eb&hlc=1&transcode_audio=0
&transcode_mp3=0&transcode_ac3=0&preferred_audio_language=eng</nowiki>",
"is_live": 1,
"transport_file_url": null,
"content_id": null,
"infohash": "7889e5f0cea9b72f5dcd7a9c67e665c7f4f5b3eb",
"id": 4
}
]

Playlist API

2018-04-19T11:50:34Z

Ffx: /* Brief description */

''Added in version 3.1.28''

== Brief description ==
Playlist API allows to export playlist in different formats from Ace Stream Media Server.

API endpoint:
<tt>'''<nowiki>http://<engine_host>:6878/playlist/get</nowiki>'''</tt>

'''Parameters:'''

* ''format'' (list) - set output format;
* ''category'' (list) - filter by category (media type);
* ''subcategory'' (string) - filter by subcategory (tags);
* ''favorites'' (bool, default is 0) - filter favorites; favorites=0 means to output both favorite and non-favorite items;
* ''items'' (list of integers) - filter by playlist item ids;
* ''host'' (string) - configure playback URL: set "host" part of URL. Actually this is an IP address of Ace Stream Media Server. By default the host from endpoint URL is used;
* ''protocol'' (string, defaults to server settings) - configure playback URL: set output protocol (http or hls);
* ''transcode_audio'' (bool, defaults to server settings) - configure playback URL: enabled audio transcoding;
* ''transcode_mp3'' (bool, defaults to server settings) - configure playback URL: transcode MP3 to AAC (by default MP3 is not transcoded);
* ''transcode_ac3'' (bool, defaults to server settings) - configure playback URL: transcode only AC3 to AAC and don't transcode other codecs;
* ''preferred_audio_language'' (string, defaults to server settings) - configure playback ULR: set preferred audio language;
* ''download'' (bool, default is 0) - download playlist as file;
* ''skip_autosearch'' (bool, default is 0) - don't replace playlist data with autosearch results; this doesn't affect playlist items with disabled autosearch.
* ''generate_player_id'' (bool, default is 0) - with this option engine will output playlist with random '''pid''' ([[http://wiki.acestream.org/wiki/index.php/Engine_HTTP_API#Player ID|player id]], formerly known as '''sid''') for each item.

Boolean values are passed as 0 or 1 (e.g. transcode_audio=1), list of integers is passed as string of values concatenated with comma (e.g. items=14,115,127).

Allowed values for list parameters:

* '''format''' - acestream, m3u, json;
* '''category''' - tv, movies, music_video, music, other;
* '''protocol''' - http, hls.

== Playlist output formats ==
"'''m3u'''" format is intented for different media players.

"'''acestream'''" format is used to export playlist in such way so it can be imported in the Ace Stream software running somewhere else.
At the moment we use M3U format with some additional fields, specific to Ace Stream.
Each playlist item is identified either by Content ID (start with acestream://) or infohash (starts with magnet:). Infohash is used when Content ID is not available for some playlist item.
Both types of identifiers are recognized by Ace Stream Media Server when playlist is imported.

"'''json'''" format is indented to be used for automation. Playlist is returned as list of items, each item is an object with such fields:
* ''id'' (integer) - playlist item id unique for this media server; this id can be passed in "items" parameter to filter specific playlist items;
* ''title'' (string) - title;
* ''playback_url'' (string) playback URL;
* ''content_id'' (string) - Content ID (may be null);
* ''infohash'' (string) - infohash (may be null);
* ''transport_file_url'' (string) - transport file URL (may be null);
* ''category'' (string) - media type (see list for "category" parameter);
* ''is_live'' (integer) - 1: live content, 0: VOD, -1: unknown;
* ''auto_search'' (bool) - whether autosearch is enabled for this playlist item;
* ''tags'' (list of strings) - list of tags.

== Examples ==
'''Get playlist in "m3u" format:'''

Request:
<nowiki>http://127.0.0.1:6878/playlist/get?format=m3u</nowiki>

Response:

#EXTM3U
#EXTINF:-1,Test Channel 1
<nowiki>http://127.0.0.1:6878/ace/getstream?id=acbfd1954084ffc68c65b0948485e5d0f82173e2&hlc=1&transcode_audio=0
&transcode_mp3=0&transcode_ac3=0&preferred_audio_language=eng</nowiki>
#EXTINF:-1 acestream-autosearch="1",Test Channel 2
<nowiki>http://127.0.0.1:6878/ace/getstream?infohash=7889e5f0cea9b72f5dcd7a9c67e665c7f4f5b3eb&hlc=1&transcode_audio=0
&transcode_mp3=0&transcode_ac3=0&preferred_audio_language=eng</nowiki>

'''Get playlist in "acestream" format:'''

Request:
<nowiki>http://127.0.0.1:6878/playlist/get?format=acestream</nowiki>

Response:
#EXTM3U
#EXTINF:-1,Test Channel 1
acestream://acbfd1954084ffc68c65b0948485e5d0f82173e2
#EXTINF:-1 acestream-autosearch="1",Test Channel 2
magnet:?xt=urn:btih:7889e5f0cea9b72f5dcd7a9c67e665c7f4f5b3eb

'''Get playlist in "json" format:'''

Request:
<nowiki>http://127.0.0.1:6878/playlist/get?format=json</nowiki>

Response:
[
{
"category": "tv",
"auto_search": false,
"title": "Test Channel 1",
"playback_url": "<nowiki>http://127.0.0.1:6878/ace/getstream?id=acbfd1954084ffc68c65b0948485e5d0f82173e2&hlc=1&transcode_audio=0
&transcode_mp3=0&transcode_ac3=0&preferred_audio_language=eng</nowiki>",
"is_live": 1,
"transport_file_url": null,
"content_id": "acbfd1954084ffc68c65b0948485e5d0f82173e2",
"infohash": "a1231ebb2a26263cb37b305fced076961990812e",
"id": 3
},
{
"category": "tv",
"auto_search": true,
"title": "Test Channel 2",
"playback_url": "<nowiki>http://127.0.0.1:6878/ace/getstream?infohash=7889e5f0cea9b72f5dcd7a9c67e665c7f4f5b3eb&hlc=1&transcode_audio=0
&transcode_mp3=0&transcode_ac3=0&preferred_audio_language=eng</nowiki>",
"is_live": 1,
"transport_file_url": null,
"content_id": null,
"infohash": "7889e5f0cea9b72f5dcd7a9c67e665c7f4f5b3eb",
"id": 4
}
]