Docs

Bring your own backend

This is a standalone, independent web player. It provides no streams, channels or content. You connect it to your own backend, and the player shows what that backend returns. This page lists the basic calls the player makes, so you can build or adapt a backend for it.

How the address maps to calls

  1. The operator registers a brand on the registration page: a short name tied to the backend's service address, such as tv.example.com. The player keeps only the origin and adds https:// when it is missing. Users open /login?brand=<name> and never type the address.
  2. It posts to https://tv.example.com/api/public/getBrandConfig. The answer's playerServer is your API host.
  3. Sign-in and every later call go to <API host>/api/…. The session remembers the brand, so a signed-in user stays on the same backend until they sign out or the brand's paid period ends.

Registration checks that the service address answers getBrandConfig like this before it quotes the amount to pay.

Rules for every call

Calls

Service config

POST/api/public/getBrandConfigon the service address

The first call after the user enters a service address. It tells the player where your API lives. If the typed address does not answer with this, the player tries https://public.<host> once (a leading www. or webplayer. is dropped first).

Request body

{}

Example answer

{
  "success": true,
  "data": {
    "playerServer": "https://api.tv.example.com",
    "brandName": "Example TV",
    "portalLink": "https://account.tv.example.com"
  }
}

Sign in

POST/api/loginon the API host

Username and password in, a bearer token out. Answer 400, 401, 403 or 422 for wrong credentials, 402 for a lapsed subscription and 429 for too many attempts. expires_at is optional (ISO 8601 or Unix seconds).

Request body

{ "username": "[email protected]", "password": "••••••••" }

Example answer

{
  "data": {
    "token": "example-token-3f9a2c",
    "token_type": "Bearer",
    "expires_at": "2030-01-01T00:00:00Z",
    "service": { "name": "Example TV" }
  }
}

Profiles

GET/api/profileson the API host

Who is watching. Return exactly one profile and the player picks it for the user, so they never see a profile picker. The chosen number is sent back as X-API-PROFILE on later calls.

Example answer

{
  "data": [
    { "profile_number": 1, "name": "Alex", "avatar": "https://img.tv.example.com/avatars/1.png", "type": "regular" },
    { "profile_number": 2, "name": "Kids", "avatar": null, "type": "kids" }
  ]
}

Catalog categories

GET/api/info/movie/categorieson the API host

The rows of the movie catalog, in the order you want them shown.

Example answer

{ "data": [ { "id": "new", "name": "New releases" }, { "id": "docs", "name": "Documentaries" } ] }

Browse a category

GET/api/info/movie/items/{categoryId}/{offset}/{limit}on the API host

One page of a category. The player asks for 15 at a time and stops when a page comes back shorter than the limit. Only imdb_id is required; it is your item id and does not have to be a real IMDb id.

Example answer

{
  "data": [
    {
      "imdb_id": "m-1001",
      "title": "The Long Weekend",
      "meta": {
        "year": "2021",
        "runtime": "102",
        "poster": "https://img.tv.example.com/m-1001/poster.jpg",
        "fanart": "https://img.tv.example.com/m-1001/backdrop.jpg"
      }
    }
  ]
}

Item details

GET/api/info/movie/{id}on the API host

One item, in the same shape as a browse row. A one-row list is fine; the player picks the row whose imdb_id matches.

Example answer

{ "data": [ { "imdb_id": "m-1001", "title": "The Long Weekend", "meta": { "year": "2021", "runtime": "102" } } ] }

Channel groups

GET/api/info/livetv/categorieson the API host

Groups of live channels. The player adds ?with=sub_categories; sub_categories can be empty.

Example answer

{ "data": [ { "id": "news", "name": "News", "sub_categories": [] } ] }

Live channel list

GET/api/info/livetv/categories/{categoryId}/{offset}/{limit}/{sort}on the API host

One page of channels in a group (30 at a time, sort is asc or desc). now is optional: the programme on air, with start and stop as ISO 8601 or yyyyMMddHHmmss (UTC).

Example answer

{
  "data": [
    {
      "id": "101",
      "name": "Example News",
      "logo": "https://img.tv.example.com/channels/101.png",
      "now": { "title": "Morning Report", "start": "20300101080000", "stop": "20300101090000" }
    }
  ]
}

Stream source (on demand)

GET/api/play/movie/{id}on the API host

Where to play an item. secure_link wins over link; a relative link resolves on your API host. A link on another host (a CDN) is played by the browser directly, so that host must allow cross-origin requests from the player.

Example answer

{
  "link": "https://cdn.tv.example.com/vod/m-1001/master.m3u8",
  "secure_link": null,
  "info": { "format_name": "hls" }
}

Stream source (live)

GET/api/play/livetv.epg/{channelId}.m3u8on the API host

A live channel's HLS playlist itself, or the same JSON as above. The player's server fetches it with the user's token and passes it on, so playlists and segments on your API host need no cross-origin setup.

Example answer

#EXTM3U
#EXT-X-STREAM-INF:BANDWIDTH=3000000,RESOLUTION=1280x720
720p/index.m3u8

Optional files

Some players read a meta.json or a thumbnails.vtt (seek-bar previews) next to a stream. This version of the web player does not request them, so you can leave them out.

All names, hosts and values on this page are made-up examples.

Back to sign-in