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
- 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 addshttps://when it is missing. Users open/login?brand=<name>and never type the address. - It posts to
https://tv.example.com/api/public/getBrandConfig. The answer'splayerServeris your API host. - 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
- HTTPS only, on a public address. The player's server refuses private, loopback and cloud-metadata addresses, checks every redirect the same way (three at most, and the token is never sent to another host), and gives up after a few seconds or a few megabytes.
- Requests carry
Accept: application/jsonandX-Client-Type: web. After sign-in they also carryAuthorization: Bearer <token>and, once a profile is chosen,X-API-PROFILE: <number>. - Lists can be a bare array,
{ "data": [...] }or{ "data": { "items": [...] } }. Rows the player cannot read are skipped. - Answer
401when a token is no longer valid; the player then asks the user to sign in again. - Images may be absolute
https://URLs, or paths that resolve onhttps://storage.<API host>.
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