← Modes

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_video and vod_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 /main for about 30 minutes; /info and /watch are 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.