Difference between revisions of "Playlist API"

From Ace Stream Wiki
Jump to: navigation, search
 
(26 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
==Brief description==
 
==Brief description==
Playlist API allows to export playlist from Ace Stream Media Server in different formats.
+
Playlist API allows to export playlist in different formats from Ace Stream Media Server. API available since version 3.1.28.
  
API endpoint: '''<tt><nowiki>http://<engine_host>:6878/playlist/get</nowiki></tt>'''
+
API endpoint:
 +
<tt>'''<nowiki>http://<engine_host>:6878/playlist/get</nowiki>'''</tt>
  
 
'''Parameters:'''
 
'''Parameters:'''
  
- format (list) - set output format
+
* ''format'' (list) - set output format;
- category (list) - filter by category (media type)
+
* ''category'' (list) - filter by category (media type);
- subcategory (string) - filter by subcategory (tags)
+
* ''subcategory'' (string) - filter by subcategory (tags);
- favorites (bool, default is 0) - filter favorites; favorites=0 means to output both favorite and non-favorite items
+
* ''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
+
* ''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.
+
* ''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)
+
* ''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_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_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
+
* ''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
+
* ''preferred_audio_language'' (string, defaults to server settings) - configure playback ULR: set preferred audio language;
- download (bool, default is 0) - download playlist as file
+
* ''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
+
* ''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)
+
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).
List of integers is passed as string of values concatenated with comma (e.g. items=14,115,127)
 
  
 
Allowed values for list parameters:
 
Allowed values for list parameters:
<tt>'''format'''</tt>
 
* acestream
 
* m3u
 
* json
 
  
<tt>'''category'''</tt>
+
* '''format''' - acestream, m3u, json;
    - tv
+
* '''category''' - tv, movies, music_video, music, other;
    - movies
+
* '''protocol''' - http, hls.
    - music_video
 
    - music
 
    - other
 
<tt>'''protocol'''</tt>
 
    - http
 
    - hls
 
  
 +
==Playlist output formats==
 +
"'''m3u'''" format is intented for different media players.
  
==Playlist output formats==
+
"'''acestream'''" format is used to export playlist in such way so it can be imported in the Ace Stream software running somewhere else.
"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.
 
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.
 
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.
 
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:
+
"'''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
+
* ''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
+
* ''title'' (string) - title;
- playback_url (string) - playback URL
+
* ''playback_url'' (string) playback URL;
- content_id (string) - Content ID (may be null)
+
* ''content_id'' (string) - Content ID (may be null);
- infohash (string) - infohash (may be null)
+
* ''infohash'' (string) - infohash (may be null);
- transport_file_url (string) - transport file URL (may be null)
+
* ''transport_file_url'' (string) - transport file URL (may be null);
- category (string) - media type (see list for "category" parameter)
+
* ''category'' (string) - media type (see list for "category" parameter);
- is_live (integer) - 1: live content, 0: VOD, -1: unknown
+
* ''is_live'' (integer) - 1: live content, 0: VOD, -1: unknown;
- auto_search (bool) - whether autosearch is enabled for this playlist item
+
* ''auto_search'' (bool) - whether autosearch is enabled for this playlist item;
- tags (list of strings) - list of tags
+
* ''tags'' (list of strings) - list of tags.
  
"m3u" format is intented for different media players.
 
  
 +
==Examples==
 +
'''Get playlist in "m3u" format:'''
  
==Examples==
 
'''Get playlist in "acestream" format.'''
 
 
Request:
 
Request:
  http://127.0.0.1:6878/playlist/get?format=acestream
+
  <nowiki>http://127.0.0.1:6878/playlist/get?format=m3u</nowiki>
  
 
Response:
 
Response:
 +
 
  #EXTM3U
 
  #EXTM3U
 
  #EXTINF:-1,Test Channel 1
 
  #EXTINF:-1,Test Channel 1
  acestream://acbfd1954084ffc68c65b0948485e5d0f82173e2
+
  <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
 
  #EXTINF:-1 acestream-autosearch="1",Test Channel 2
  magnet:?xt=urn:btih:7889e5f0cea9b72f5dcd7a9c67e665c7f4f5b3eb
+
  <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:'''
  
'''Get playlist in "m3u" format.'''
 
 
Request:
 
Request:
  http://127.0.0.1:6878/playlist/get?format=m3u
+
  <nowiki>http://127.0.0.1:6878/playlist/get?format=acestream</nowiki>
  
 
Response:
 
Response:
 
  #EXTM3U
 
  #EXTM3U
 
  #EXTINF:-1,Test Channel 1
 
  #EXTINF:-1,Test Channel 1
  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
+
  acestream://acbfd1954084ffc68c65b0948485e5d0f82173e2
 
  #EXTINF:-1 acestream-autosearch="1",Test Channel 2
 
  #EXTINF:-1 acestream-autosearch="1",Test Channel 2
  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
+
  magnet:?xt=urn:btih:7889e5f0cea9b72f5dcd7a9c67e665c7f4f5b3eb
 +
 
 +
 
 +
'''Get playlist in "json" format:'''
  
'''Get playlist in "json" format.'''
 
 
Request:
 
Request:
  http://127.0.0.1:6878/playlist/get?format=json
+
  <nowiki>http://127.0.0.1:6878/playlist/get?format=json</nowiki>
  
 
Response:
 
Response:
Line 95: Line 92:
 
  "auto_search": false,
 
  "auto_search": false,
 
  "title": "Test Channel 1",
 
  "title": "Test Channel 1",
  "playback_url": "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",
+
  "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,
 
  "is_live": 1,
 
  "transport_file_url": null,
 
  "transport_file_url": null,
Line 106: Line 104:
 
  "auto_search": true,
 
  "auto_search": true,
 
  "title": "Test Channel 2",
 
  "title": "Test Channel 2",
  "playback_url": "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",
+
  "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,
 
  "is_live": 1,
 
  "transport_file_url": null,
 
  "transport_file_url": null,

Latest revision as of 19:06, 9 June 2020

Brief description

Playlist API allows to export playlist in different formats from Ace Stream Media Server. API available since version 3.1.28.

API endpoint:

http://<engine_host>:6878/playlist/get

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:

http://127.0.0.1:6878/playlist/get?format=m3u

Response:

#EXTM3U
#EXTINF:-1,Test Channel 1
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
#EXTINF:-1 acestream-autosearch="1",Test Channel 2
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


Get playlist in "acestream" format:

Request:

http://127.0.0.1:6878/playlist/get?format=acestream

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:

http://127.0.0.1:6878/playlist/get?format=json

Response:

[
{
"category": "tv",
"auto_search": false,
"title": "Test Channel 1",
"playback_url": "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",
"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": "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",
"is_live": 1,
"transport_file_url": null,
"content_id": null,
"infohash": "7889e5f0cea9b72f5dcd7a9c67e665c7f4f5b3eb",
"id": 4
}
]