Provider definition reference

A provider definition tells Burst how to search a site and how to read the results. This page describes every key Burst understands. To create and test a provider, see How to add a provider.

File format

Definitions are a JSON object. Each key is the provider ID, and its value is the provider definition:

{
    "my_tracker": {
        "name": "My Tracker",
        "base_url": "https://my-tracker.example/search?q=QUERYEXTRA",
        "...": "..."
    }
}

The provider ID is used in Kodi setting IDs (use_my_tracker, my_tracker_username, …) and in the icon file name (my_tracker.png). Use lowercase letters, digits, - and _.

Definitions are read from these places, in this order. Later files are merged into earlier ones key by key, so an override only needs the keys it changes:

How a search works

1. Elementum asks Burst for a movie, episode, season, anime episode, or a general (typed) search.
2. For each enabled provider, Burst takes base_url and appends the query part for that search type (for example movie_query).
3. It builds one or more queries from the keywords for that type (for example movie_keywords), filling in placeholders like {title} and {year}.
4. QUERY in the URL is replaced with the query, and EXTRA with the extra text for that type (for example movie_extra). Spaces become separator.
5. Burst logs in if needed, opens the URL and reads the results with the parser rules, or with api_format for JSON APIs.
6. Results go through Burst’s filters (resolution, size, release type) and are sent to Elementum.

General keys

Search URL

root_url is always set by Burst from base_url, so don’t set it yourself. You can use it in other values, for example in login_headers.

URL placeholders

Replaced in base_url, the *_query keys and post_data:

Search queries

Each search type has its own set of keys. Replace <type> with:

Identical queries are searched only once, and Burst stops starting new queries 3 seconds before the search timeout.

Example from 1337x: an episode is searched as s01e02, then, without results, as the whole season:

"tv_keywords": "{title:original:en} s{season:2}e{episode:2}",
"tv_keywords_fallback": "{title:original:en} s{season:2}"

Keyword placeholders

HTML parser

For sites returning HTML, parser describes where to find the results. Each value is a Python expression for the ehp HTML parser:

In all keys except row and key, item is the current row. re (Python regular expressions) is also available.

Parser functions

Parameters:

• tag: tag name, e.g. 'td', 'a'.
• order: which match to take, counting from 1. 0 is the last match, -1 the one before last.
• select: attribute filter as a tuple, e.g. ('class', 'seedmed'). The value matches one of the space-separated words of the attribute. A list matches any of its values: ('class', ['torrent', 'name']).
• attribute: 'text' (the default) for the text, or an attribute name like 'href' or 'title'.
• divider: (separator, index) splits the value and takes one part, e.g. ('&', 0) keeps everything before the first &.
• start: first match to return, e.g. start=2 skips a header row.
• every: return every Nth match.

Since values are Python, you can combine and transform them:

"torrent": "'https://www.1337x.to%s' % item(tag='a', attribute='href', order=2)",
"name": "item(tag='a', order=2) + ' [' + item(tag='img', attribute='title', order=1) + ']'",
"size": "re.search(r'Size: (.*?)\\n', item(tag='td', select=('class', 'descr'))).group(1)",
"infohash": "item(tag='a', attribute='href', order=3, divider=('&', 0)).replace('magnet:?xt=urn:btih:', '')"

Subpages

Some sites only list links to torrent pages, with the magnet or download link on the page itself.

Subpages are opened in parallel and cached during the search.

API providers

For sites with a JSON API, set is_api and describe the response with api_format instead of parser:

api_format keys:

Example, YTS:

"yts": {
    "name": "YTS",
    "enabled": true,
    "predefined": true,
    "private": false,
    "color": "FF6AC045",
    "language": "en",
    "languages": "en",
    "is_api": true,
    "base_url": "https://movies-api.accel.li/api/v2/list_movies.json?query_term=QUERY&sort_by=seeds&order_by=desc",
    "movie_keywords": "{title:en:original}",
    "general_keywords": "{title}",
    "api_format": {
        "results": "data.movies",
        "subresults": "torrents",
        "name": "title_long",
        "description": "type",
        "quality": "quality",
        "torrent": "url",
        "info_hash": "hash",
        "size": "size",
        "seeds": "seeds",
        "peers": "peers"
    }
}

Login (private trackers)

With "private": true, Burst shows username and password settings for the provider (for providers shipped with Burst), and logs in before searching:

If a passkey is set, Burst doesn’t log in: it puts the passkey into PASSKEY in the search URL and torrent links instead.

The session cookies are saved and sent with torrent downloads, so Elementum can download the torrent files.

Example, RuTracker (with cookie sync):

"private": true,
"login_path": "/forum/login.php",
"login_object": "{'login_username': USERNAME, 'login_password': PASSWORD, 'login': 'Login'}",
"login_failed": "Регистрация",
"login_cookie": "bb_session"

Network and encoding

Users can also set an alias (another domain) for each provider in Burst settings. Burst then replaces the domain in every value of the definition.

Complete example

A public HTML tracker, 1337x (some fallback queries left out):

{
    "1337x": {
        "name": "1337x",
        "enabled": true,
        "predefined": true,
        "private": false,
        "color": "FFF14E13",
        "language": null,
        "languages": "en",
        "base_url": "https://www.1337x.to/search/QUERYEXTRA/1/",
        "separator": "+",
        "general_query": "",
        "general_keywords": "{title}",
        "general_extra": "",
        "movie_query": "",
        "movie_keywords": "{title:original:en} {year}",
        "movie_extra": "",
        "show_query": "",
        "tv_keywords": "{title:original:en} s{season:2}e{episode:2}",
        "tv_keywords_fallback": "{title:original:en} s{season:2}",
        "tv_keywords_fallback2": "{title:original:en} season {season}",
        "tv_extra": "",
        "season_query": "",
        "season_keywords": "{title:original:en} s{season:2}",
        "season_keywords2": "{title:original:en} season {season}",
        "season_keywords_fallback": "{title:original:en} {season:2}x01",
        "season_extra": "",
        "anime_query": "",
        "anime_keywords": "{title:original:en} s{season:2}e{episode:2}",
        "anime_keywords_fallback": "{title:original:en} s{season:2}",
        "anime_extra": "",
        "subpage": true,
        "parser": {
            "row": "find_once(tag='tbody').find_all('tr')",
            "name": "item('a', order=2)",
            "torrent": "'https://www.1337x.to%s' % item(tag='a', attribute='href', order=2)",
            "size": "item(tag='td', order=5)",
            "seeds": "item(tag='td', order=2)",
            "peers": "item(tag='td', order=3)",
            "infohash": ""
        }
    }
}

A search for The Matrix (1999) opens https://www.1337x.to/search/The+Matrix+1999/1/. Then Burst reads the rows and opens each result page (subpage) to find the magnet link.

See providers.json for many more examples.