Creating a Custom Mode
A Custom Mode lets you plug your own content library into Combust Media. You run a small server that returns JSON, generate an encrypted mode code from this site, and share that code with users — they paste it into the app to unlock your content.
Combust Media never proxies your content: the app talks directly to your server using the URLs in your descriptor. You stay in full control of what you serve and to whom.
Overview
1. Build a server that answers the mode contract (JSON routes)
2. Write a mode descriptor (title, URLs, bearer token, …)
3. Generate an encrypted code here → Create a mode
4. Share the code — users add it in the app to unlock your mode
There are four media_type values:
media_type |
Player | Flow | Use for |
|---|---|---|---|
vod_video |
Video | Main → Info → Watch | Movies, series |
vod_audio |
Audio | Main → Info → Watch | Audiobooks, podcasts |
live_tv |
Video | Main → Watch | Live TV channels |
live_radio |
Audio | Main → Watch | Live radio stations |
The app plays
vod_videoandvod_audio. The live types are part of the contract but not yet playable — for live channels and stations, the app's own TV and Radio modes are the place.
Step 1 — Build your server
Your server exposes a few JSON endpoints. Every route must require your bearer token (sent as
Authorization: Bearer <token> on each request).
Routes for vod_video
| Route | Required | Returns |
|---|---|---|
GET /main |
Yes | Home-screen sections + items |
GET /info |
Yes | Detail for one item |
GET /watch |
Yes | Playback URL + subtitles |
GET /search/[query] |
No | Paginated search results |
GET /main
{
"sections": [
{
"title": "Trending Movies",
"media_items": [
{
"id": "movie1",
"title": "John Wick: Chapter 4",
"image": "https://img.example.com/3.jpg",
"type": "movie",
"release_date": "2023",
"duration": "120m",
"info_url": "https://yourserver.com/info?id=movie1"
}
]
}
]
}
Each item's type is movie or series. info_url is called next.
Important: every URL you embed (info_url, watch_url) must be reachable from the user's
device — use your public host, not localhost.
GET /info
The app calls the item's info_url. episodes is always an array — a single entry for a
movie, one per episode for a series.
{
"id": "tv1",
"title": "Platonic",
"cover": "https://img.example.com/cover_1.jpg",
"image": "https://img.example.com/1.jpg",
"description": "A long description…",
"type": "series",
"release_date": "2023-05-23",
"duration": "45 min",
"rating": "9.0",
"episodes": [
{ "title": "Eps 1: Pilot", "episode": "1", "season": "1", "watch_url": "https://yourserver.com/watch?id=tv1_1" }
]
}
For a movie, episodes is [{ "watch_url": "https://yourserver.com/watch?id=movie1" }].
GET /watch
The app calls the watch_url. Return the direct media URL (e.g. an HLS .m3u8) and any subtitles
(empty array if none).
{
"url": "https://yourserver.com/media/file.m3u8",
"subtitles": [
{ "url": "https://yourserver.com/subs/eng.srt", "lang": "English" },
{ "url": "https://yourserver.com/subs/eng-sdh.vtt", "lang": "English (SDH)" }
],
"headers": { "Referer": "https://yourserver.com/" }
}
Subtitles are sidecar files in SubRip (.srt) or WebVTT (.vtt); the app fetches and renders
them itself, stripping any HTML or SSA styling. They start off — the viewer picks one from the
player's subtitle menu, in the order you return them. lang is the label shown in that menu, exactly
as written, so make it tell entries apart: "English" and "English (SDH)", not "en" twice.
headers is optional. Some stream hosts only serve media to requests carrying a particular
Referer or User-Agent; whatever you put here is sent with the media URL and its HLS segments.
It is not sent when fetching subtitles — those URLs must be reachable with a plain request.
GET /search/[query]
Only if you set a search URL. The app appends the URL-encoded query and an optional ?page.
{
"next_page_url": "https://yourserver.com/search/rick?page=2",
"prev_page_url": null,
"media_items": [ /* same shape as /main items */ ]
}
Audio modes (vod_audio)
Audio modes use the same routes — /main, /info and /watch, with the same bearer token — but
an audio title has no picture to fill the screen, so the app presents it one of two ways. You pick
which with Audio layout in the mode builder (audio_layout in the
descriptor):
library(the default) — albums, audiobooks and shows. A detail page with a track list, a seek bar, resume, and a compact now-playing screen.scene— an immersive backdrop (a looping video or a slideshow) with a rail of stations. Made for continuous audio: ambient sound, lo-fi, live stations.
Search isn't offered for audio modes yet; a search URL on a vod_audio mode is ignored.
GET /main
Same shape as for video. Each item's type is optional and only affects how it's shown:
album, audiobook, show, single or scene.
{
"sections": [
{
"title": "New audiobooks",
"media_items": [
{
"id": "book1",
"title": "The Long Way Home",
"image": "https://img.example.com/book1.jpg",
"type": "audiobook",
"release_date": "2024",
"info_url": "https://yourserver.com/info?id=book1"
}
]
}
]
}
GET /info — library layout
Return tracks in play order. A track with duration_seconds gets a seek bar and resumes where
the listener left off; without it, the track is treated as a continuous stream.
{
"id": "book1",
"title": "The Long Way Home",
"cover": "https://img.example.com/book1-wide.jpg",
"image": "https://img.example.com/book1.jpg",
"description": "A long description…",
"release_date": "2024",
"tracks": [
{
"title": "Chapter 1",
"subtitle": "Read by Jane Doe",
"track_number": 1,
"duration_seconds": 1834,
"watch_url": "https://yourserver.com/watch?id=book1_1"
}
]
}
A server ported from vod_video that still sends episodes instead of tracks works too — the
episodes are shown as a plain track list.
GET /info — scene layout
stations fill the rail; backdrop is drawn behind them. A video (mp4 or HLS) loops muted
behind the audio; images cross-fade as a slideshow when there's no video or the listener has
turned motion off. Stations are treated as continuous unless you set "continuous": false.
{
"id": "rain",
"title": "Rainy café",
"image": "https://img.example.com/rain.jpg",
"description": "Rain on the window, quiet chatter, slow jazz.",
"backdrop": {
"video": "https://yourserver.com/backdrops/rain.mp4",
"images": ["https://img.example.com/rain-1.jpg", "https://img.example.com/rain-2.jpg"]
},
"stations": [
{
"id": "jazz",
"label": "Slow jazz",
"image": "https://img.example.com/jazz.jpg",
"watch_url": "https://yourserver.com/watch?station=jazz"
}
]
}
GET /watch
Return the audio URL, plus optional headers (as for video). now_playing is an optional line
shown under the title and on the lock screen — useful for a station's current track. Subtitles are
ignored for audio.
{
"url": "https://yourserver.com/audio/jazz.m3u8",
"now_playing": "Bill Evans — Peace Piece",
"headers": { "Referer": "https://yourserver.com/" }
}
Live routes (live_tv / live_radio)
Live content skips the info step — tapping a channel goes straight to playback. /main returns
channels (with logo, watch_url, optional info_url for EPG) instead of media_items, and
/watch returns just url.
Step 2 — Write your descriptor
Your descriptor is the set of fields below. You don't write JSON by hand — the mode builder form collects them.
| Field | Required | Notes |
|---|---|---|
title |
Yes | Display name |
description |
Yes | What the mode provides |
media_type |
Yes | One of the four types |
logo_url |
Yes | Square image, ≥200×200 |
bearer_token |
Yes | Token your server checks on every request |
main_screen_url |
Yes | Your /main URL |
search_screen_url |
No | Your /search URL |
audio_layout |
No | vod_audio only: library (default) or scene |
Modes have no developer-settable expiry. Every mode ships locked — access is granted per person with a renewal code (see below).
Step 3 — Generate your code
Open the mode builder, fill in the fields, and click Generate code. You'll get
a string that starts with v1:. The descriptor is encrypted server-side with a key that never
leaves Combust Media — the raw fields (including your bearer token) are never exposed in the code.
Step 4 — Share it
Give the v1:… code to your users however you like (email, a web page, a private group). In the
app they open Custom → Add, paste the code, and your mode appears — but it stays locked
until they redeem a renewal code, so pair it with one per user (see below). You can also add codes
yourself on the Custom modes page.
Access & renewal codes
A mode code grants no access on its own — every mode expires the moment it's created, so it lands in a user's app locked. Access is granted per person with a renewal code:
- You mint renewal codes on the renewal codes page. Each carries a grants access until date and is single-use (self-expires if unredeemed).
- The user redeems a code (
XXXX-XXXX) in the app, which sets their expiry to that date. - Redeeming again with a later date extends them; mint one code per person.
So distribute the v1:… mode code together with a renewal code for each user. This runs
subscription-style, per-person access — different people, different expiry dates, one mode — with
no payments handled inside the app.
Good to know
- Caching: the app caches
/mainfor about 30 minutes;/infoand/watchare always fetched fresh, so playback URLs can be short-lived or signed. - Security: your bearer token authorizes every request — rotate it (with a new code) if it leaks. The encrypted code is safe to distribute; the underlying token is not embedded in plaintext.
- Reachability: test that every URL your server returns loads from a phone on mobile data, not just your local network.