Start Playback¶

How It Works¶

In the terms of video stream playback the engine acts as a gateway between P2P network and video player:

the player "tells" the engine which stream should be played and which output format should be used
the engine connects to the P2P network, downloads the stream data from other peers and reassembles it to the specified output format (e.g. MPEG TS)
the player receives the stream from the engine over HTTP

Input Parameters¶

Input parameters are divided in two groups:

what should be played (required)
extended configuration options (optional)

In this section we'll describe only the first group. You can read about all available options in the API Reference.

To start playback the engine needs to know which broadcast to connect to. The broadcast is uniquely identified by the transport file, but in practice you can start playback without explicitly passing the transport file to the engine. There are four possible options and you must specify one of them:

Parameter	Description
content_id	Content ID of the stream
infohash	Infohash of the stream
url	URL of the transport file
magnet	Magnet link

These parameters are mutually exclusive and are parsed in the same order as in the table above. This means that if you specify both content_id and infohash parameters only content_id will be used.

Output Format¶

The engine supports two output formats:

MPEG TS
HLS

The format is selected by using the corresponding endpoint.

To receive the stream in MPEG TS:

# Endpoint
GET /ace/getstream

# Example
http://127.0.0.1:6878/ace/getstream?infohash=0a4848271c91ce2d8965ce416267c25047dc8141

To receive the stream in HLS:

# Endpoint
GET /ace/manifest.m3u8

# Example
http://127.0.0.1:6878/ace/manifest.m3u8?infohash=0a4848271c91ce2d8965ce416267c25047dc8141

Using Middleware¶

We advise using middleware to start playback.

Middleware is a software that acts as a bridge between video player and the engine. If you're a player developer then the middleware most likely will be embedded in the player itself.

In the examples above the engine will output the video stream directly in the response. For example:

$ curl -L "http://127.0.0.1:6878/ace/manifest.m3u8?infohash=0a4848271c91ce2d8965ce416267c25047dc8141"
#EXTM3U
#EXT-X-VERSION:3
#EXT-X-TARGETDURATION:7
#EXT-X-MEDIA-SEQUENCE:0
#EXTINF:5.720000,
http://127.0.0.1:6878/ace/c/0a4848271c91ce2d8965ce416267c25047dc8141/0.ts
#EXTINF:5.360000,
http://127.0.0.1:6878/ace/c/0a4848271c91ce2d8965ce416267c25047dc8141/1.ts
#EXTINF:5.600000,
http://127.0.0.1:6878/ace/c/0a4848271c91ce2d8965ce416267c25047dc8141/2.ts
#EXTINF:6.280000,
http://127.0.0.1:6878/ace/c/0a4848271c91ce2d8965ce416267c25047dc8141/3.ts
#EXTINF:4.160000,
http://127.0.0.1:6878/ace/c/0a4848271c91ce2d8965ce416267c25047dc8141/4.ts
#EXTINF:3.720000,
http://127.0.0.1:6878/ace/c/0a4848271c91ce2d8965ce416267c25047dc8141/5.ts
#EXTINF:5.800000,
http://127.0.0.1:6878/ace/c/0a4848271c91ce2d8965ce416267c25047dc8141/6.ts
#EXTINF:3.920000,
http://127.0.0.1:6878/ace/c/0a4848271c91ce2d8965ce416267c25047dc8141/7.ts
#EXTINF:4.600000,
http://127.0.0.1:6878/ace/c/0a4848271c91ce2d8965ce416267c25047dc8141/8.ts
#EXTINF:5.600000,
http://127.0.0.1:6878/ace/c/0a4848271c91ce2d8965ce416267c25047dc8141/9.ts
#EXTINF:4.600000,
http://127.0.0.1:6878/ace/c/0a4848271c91ce2d8965ce416267c25047dc8141/10.ts
#EXTINF:5.640000,
http://127.0.0.1:6878/ace/c/0a4848271c91ce2d8965ce416267c25047dc8141/11.ts
#EXTINF:4.800000,
http://127.0.0.1:6878/ace/c/0a4848271c91ce2d8965ce416267c25047dc8141/12.ts

It means that the URL that is used to start playback can be passed directly to the player.

The downside of this approach is that you don't have control over the playback session. Using the middleware gives you such control and you can:

explicitly stop the playback session
get the info about playback session (number of connected peers, download and upload speed etc)

In the middleware you should add format=json parameter. The engine will start the playback session and give you links to control the session:

$ curl "http://127.0.0.1:6878/ace/manifest.m3u8?format=json&infohash=0a4848271c91ce2d8965ce416267c25047dc8141"
{
  "response": {
    "playback_url": "http://127.0.0.1:6878/ace/m/0a4848271c91ce2d8965ce416267c25047dc8141/f528764d624db129b32c21fbca0cb8d6.m3u8",
    "stat_url": "http://127.0.0.1:6878/ace/stat/0a4848271c91ce2d8965ce416267c25047dc8141/f528764d624db129b32c21fbca0cb8d6",
    "command_url": "http://127.0.0.1:6878/ace/cmd/0a4848271c91ce2d8965ce416267c25047dc8141/f528764d624db129b32c21fbca0cb8d6",
    "infohash": "0a4848271c91ce2d8965ce416267c25047dc8141",
    "playback_session_id": "e0d10c40465de696c0222ffa815edace0635b86a",
    "is_live": 1,
    "is_encrypted": 0,
    "client_session_id": -1
  },
  "error": null
}

The most important fields in the response:

playback_url - the URL of video stream. It should be passed to the player.
stat_url - this URL returns the information about the playback session
command_url - this URL is used to stop the playback session. To do this you should add method=stop parameter to this URL. NOTE: you're not required to stop the session. The engine will stop it automatically if the player stops reading the stream. But the good practice is to stop the session explicitly.

Other fields are described in the API Reference.

Examples:

# stop playback session
$ curl "http://127.0.0.1:6878/ace/cmd/0a4848271c91ce2d8965ce416267c25047dc8141/f528764d624db129b32c21fbca0cb8d6?method=stop"
{
  "response": "ok",
  "error": null
}

# get session info
$ curl "http://127.0.0.1:6878/ace/stat/0a4848271c91ce2d8965ce416267c25047dc8141/f528764d624db129b32c21fbca0cb8d6"
{
  "response": {
    "uploaded": 491520,
    "network_monitor_status": 0,
    "debug_level": 0,
    "disk_cache_stats": {
      "avail": 3199156224,
      "disk_cache_limit": 2266017044,
      "inactive_inuse": 0,
      "active_inuse": 38010982
    },
    "speed_down": 257,
    "speed_up": 29,
    "network_monitor_started": false,
    "selected_stream_index": 0,
    "total_progress": 0,
    "stream_status": -1,
    "client_session_id": -1,
    "status": "dl",
    "downloaded": 3276800,
    "manifest_access_mode": -1,
    "peers": 4,
    "playback_session_id": "15ad634c7ed4deb28045e641c825adcebe5b5f27",
    "is_encrypted": 0,
    "is_live": 1,
    "infohash": "0a4848271c91ce2d8965ce416267c25047dc8141",
    "selected_file_index": -1,
    "livepos": {
      "last": "1639986704",
      "live_first": "1639984904",
      "pos": "1639986704",
      "first_ts": "1639984904",
      "last_ts": "1639986704",
      "is_live": "1",
      "live_last": "1639986704",
      "buffer_pieces": "30"
    }
  },
  "error": null
}

Playback session info fields

Name	Type	Description
status	enum	Playback session status. Values: prefuf, dl.
peers	int	Number of connected peers
speed_down	int	Download speed (Kbytes/s)
speed_up	int	Upload speed (Kbytes/s)
downloaded	int	Total downloaded (bytes)
uploaded	int	Total uploaded (bytes)