The Omnio add-on format

Omnio TV ships with no video sources of its own. When you press Play, it asks the add-ons you have added where a video can be found, then plays what they point to, usually through your own debrid service. This page explains the two kinds of add-on Omnio understands, so that anyone can build one:

1. an add-on file: a small JSON file that tells Omnio which address to ask and how to read the answer;
2. a Stremio add-on link: Omnio also opens the manifest.json links of Stremio add-ons that find streams. Stremio is a separate app made by others; Omnio is not connected with it, and nothing here is endorsed by it.

Omnio does not host, check, rank or recommend any add-on. Add-ons are made and run by other people, and whoever adds one is responsible for using it, and what it finds, only where they have the right to.

1. Adding an add-on

Add-ons are added by link, on the Add-ons page of the app (TV or phone):

• The link must start with https:// and name a host. Plain-http links are refused.
• A link whose path ends in /manifest.json is read as a Stremio add-on (section 8). A stremio:// link (what an "Install" button often gives) is read as the same address on https://.
• Any other link whose path ends in .json is read as an add-on file. Its path may not contain ; or %, or a manifest.json piece before the end. A query string (?…) is allowed.
• Anything else is refused.

Before the first add on a device, the person accepts a short notice that add-ons are run by others. They must be signed in to an Omnio account, and can have up to 5 add-ons: from Omnio TV 0.1.50, add-on files and Stremio links together on the account; before that, the account's add-on files plus that device's Stremio links. Omnio fetches the link once (no retry), checks it, and only then saves it:

• an add-on file's address is saved to the account, so it follows the person to their other devices;
• a Stremio link is kept encrypted, because Stremio links often contain the person's own settings or keys: from Omnio TV 0.1.50 on the account, so it follows the person to their other devices (and can be added on the account page too, which shows only its name and website, never the link); before 0.1.50 on that device only, sealed with the device's key.

Omnio fetches each switched-on add-on again whenever the account signs in or the person taps "Try again". There is no separate install step on your side.

Each add-on has an on/off switch on the Add-ons page, and it works per device. From Omnio TV 0.1.50 the account page can also switch one off for all devices or for one device. An add-on that is switched off stays in the list, but Omnio doesn't ask it for videos or contact it at all until it is switched on again. Every added add-on counts toward the 5, on or off.

2. The add-on file

An add-on file is UTF-8 JSON. After trimming white space it must start with [ or {. Three shapes are read:

• an array of entries: [ {…}, {…} ];
• an object with a data key holding an array or a single entry: { "data": [ {…} ] };
• any other object, read as a single entry.

A file needs at least one entry. Each entry is one add-on Omnio will ask (the app calls these "video sources"). Omnio checks every entry, in order, and the first entry that breaks a rule rejects the whole file: nothing from it is saved. Unknown keys are ignored.

An entry whose type is reg_hash is a registration entry (section 7). Every other entry is a normal entry, described below.

3. Fields

All values are JSON strings unless the table says otherwise. Omnio trims each value; a value that is blank after trimming counts as missing.

A dotted path such as meta.bytes walks through nested objects: {"meta": {"bytes": 1000}}.

The value that counts is the one Omnio reads: registeredDebridProvider if present, else debridProvider. Accepted values: realdebrid (or rd, real-debrid), alldebrid (or ad, all-debrid), premiumize (or pm), offcloud (or oc), torbox (or tb), debrider. Letter case does not matter.

• One other value is reserved for Omnio's own use: a file that uses it is refused as a whole, with a message saying so.
• Any other value (a misspelling such as torbx, say) is accepted, but no service ever matches it, so that entry is never asked.

4. The request Omnio sends

%searchPattern is the only placeholder. Omnio replaces every %searchPattern in url with:

• Titles are always looked up by their IMDb id (tt followed by digits). A season or episode Omnio does not know counts as 1.
• Nothing is URL-encoded and nothing else is filled in: {imdb}, %imdb% or similar text in your url is sent as it is.
• An id that is not a plain id (letters, digits, _ or -, at most 64 characters) is never sent.

The request:

• GET to the filled-in address, with the header User-Agent: OmnioTV/<app version>. No key, account id or other data of the person is added to it. Whatever your url itself contains (for example a settings token you gave the person) is sent as written.
• Before searching, Omnio may send a HEAD request to your host's root (for example https://finder.example.org/) to open the connection early. The answer is ignored.
• Redirects are followed only to another https:// address (on your host or another one). A redirect to plain http is not followed: it counts as a failed answer.
• Omnio asks all add-ons at once. Each one has 15 seconds in total for its answer. A failed request (an error status or no answer) is tried once more, after 400 ms. A whole search ends after 30 seconds.
• A successful answer is reused for the same address for 10 minutes.
• Omnio asks add-ons only while at least one debrid service is set up and switched on in the app.

5. The answer Omnio reads

Answer with status 2xx and a JSON object (an array or any other JSON at the top level counts as a failed answer). Answers larger than 16 MiB are refused.

Omnio takes the array at jsonResultsKey. If the key is missing or is not an array, the add-on simply found nothing. Items that are not objects are skipped. Each item may have:

Direct links must be https://. An item whose direct link starts with anything else (plain http included) is skipped without a message, on every Android version. If the link redirects when it is played, every address it redirects to must be https:// too; a redirect to plain http fails to play.

6. How results are named, sized, graded and sorted

Name. The first of these that is present and not blank: the field at torrentNameTargetKey, behaviorHints.filename, behaviorHints.fileName, name, title.

Size. Omnio reads the size from, in order:

1. the field at sizeAttr, when set;
2. otherwise your sizePattern, run over title and description joined by a space. With two capture groups, group 1 is the number and group 2 the unit; with one group, it is a number of bytes; with none, Omnio looks for a number and a unit inside the matched text;
3. otherwise the marker 💾 followed by a size, for example 💾 1.4 GB.

A 📦 marker (📦 24 GB) gives the size of the whole season pack the file sits in. If the size from steps 1 or 2, a 📦 size and a fileIdx are all present, there is no 💾 marker, and the two sizes are within 12 % of each other, Omnio treats that size as the pack size. Without a file size, Omnio uses the pack size for a film and estimates one episode's size from it for a series.

Units: KB, MB, GB, TB (powers of 1000) and KiB, MiB, GiB, TiB (powers of 1024). A comma in the number is read as a decimal point (1,5 GB is 1.5 GB).

Quality words. Omnio grades each result from the debrid service's file name once it is known, else the item's title, else its name. It matches whole words, ignoring letter case. The main ones:

People can hide results by grade in the app's settings (for example 4K, HDR, cinema recordings or samples; 3D releases are hidden unless they turn them on), and an optional setting hides results whose name does not match the title being looked up (for grown-up profiles it works only when the app language is English; in Kids profiles it is always on). Omnio also drops, on its own, names with adult words the title itself does not contain, .mp4 files over 20 GiB, and names on filter lists Omnio can update. Name your results clearly.

Sorting. There is no sorting field. Omnio sorts every result with its own rules: resolution first (4K, 1440p, 1080p, 720p, then the rest), torrents played through a debrid service before direct links, then larger files first. A link that two add-ons both return is shown once. Torrent results are first checked with the person's debrid services where a service supports such a check, and only the ones it can play are shown.

What is shown. Each result is shown with its name or title, then a line like 1080p · 2.1 GB · Sample Finder: grade, size (in GB with one decimal) and your entry's name.

7. Registration entries

An entry with "type": "reg_hash" is not asked directly. Instead, for each debrid service the person has switched on, Omnio sends that service's key to your host, and your host answers with a token that Omnio puts in the address it asks from then on.

Registration, per service, in the order Real-Debrid, Premiumize, Offcloud, AllDebrid, TorBox:

1. POST {url}/{mode} with Content-Type: application/json. The body is a JSON object whose streaming_provider holds service (the service id, for example torbox) and token (the person's key), together with a fixed set of stream preferences.
2. Answer {"status": "success", "encrypted_str": "<token>"}. The token must be one path piece: not empty, no /, ?, #, \, spaces or control characters, and not . or ...
3. Omnio then asks {url}/{token}/stream/%searchPattern.json, tied to that service, and reads the answer as for a normal entry.

A status 429, or an answer containing "too many request", is shown as "busy". If any registration fails, the add-on is not added. Each registration may take at most 30 seconds. Registrations are repeated each time the add-on is loaded and whenever the person's debrid keys change. Registration entries are ignored in a file that is reached through a manifest.json link.

8. Stremio add-on links

Omnio also opens Stremio add-on links: it can use an existing Stremio add-on that finds streams. Stremio is a separate app made by others; Omnio is not connected with it, and nothing here is endorsed by it. Paste the add-on's manifest link:

• a link of the form https://addon.example.org/{optional path}/manifest.json, or the same with stremio:// instead of https://.
• The path before /manifest.json is kept exactly as written (add-ons often store settings in it). A query string or # part is not used for the requests that follow.

The manifest. Omnio fetches it once, with a 20-second limit and no redirect from https to plain http. It must be JSON, at most 512 KiB, and is accepted when:

• resources lists stream, either as the text "stream" or as an object {"name": "stream", …};
• that resource covers movie and/or series (its own types, else the manifest's types);
• it takes IMDb ids: there is no idPrefixes list (its own, else the manifest's), or one of the prefixes is tt or a start of it;
• behaviorHints.configurationRequired is not true.

Only the first 100 entries of each list are looked at. Omnio uses only the stream resource: catalogs, meta and subtitles are not used. The add-on is named after the manifest's name (control and invisible characters removed, cut to 40 characters), or after its host when there is none.

If the link answers with something that is not a manifest but is a valid add-on file, Omnio reads it as an add-on file, without its registration entries.

Stream requests. For a base address {base} (the link without /manifest.json):

• a film: GET {base}/stream/movie/{imdb id}.json;
• an episode: GET {base}/stream/series/{imdb id}:{season}:{episode}.json, only if the manifest lists series (films only if it lists movie).

The same timing rules as add-on files apply (section 4), with no redirect from https to plain http. The answer may be at most 4 MiB. Omnio reads the first 500 items of streams:

Items with only ytId, externalUrl or another kind of link are skipped.

9. Messages people can see

When an add-on cannot be added, the person sees one of these (wording may change slightly):

A file that breaks a rule gives "This isn't a valid add-on file." followed by one of these (entries are numbered from 1):

For a Stremio link:

When an add-on fails during a search (an error, a timeout, an answer that is not a JSON object), it simply adds no results; the other add-ons are not affected.

10. Worked examples

All hosts, names and hashes below are made up. The app's tests read these exact files and check every result described here.

Example 1: the smallest file

Hosted at, say, https://finder.example.org/omnio.json:

{
  "name": "Sample Finder",
  "type": "json_imdb",
  "itemType": "info_hash",
  "url": "https://finder.example.org/stream/%searchPattern.json",
  "searchPattern": { "movie": "movie", "tv": "series" }
}

Omnio asks:

• for the film tt0000101: https://finder.example.org/stream/movie/tt0000101.json
• for season 2, episode 5 of tt0000202: https://finder.example.org/stream/series/tt0000202:2:5.json

A sample answer for the film:

{
  "streams": [
    {
      "name": "Sample Finder\n1080p",
      "title": "Open.Film.2024.1080p.WEB.x265\n💾 2.1 GB",
      "infoHash": "0123456789abcdef0123456789abcdef01234567",
      "fileIdx": 0,
      "behaviorHints": { "filename": "Open.Film.2024.1080p.WEB.x265.mkv" }
    },
    {
      "title": "Open.Film.2024.2160p.HDR\n💾 9.8 GB",
      "infoHash": "89abcdef0123456789abcdef0123456789abcdef"
    }
  ]
}

What Omnio makes of it:

Once the person's debrid service says it can play them, the list shows the 4K result first:

Open.Film.2024.2160p.HDR …     4K · 9.8 GB · Sample Finder
Open.Film.2024.1080p.WEB.x265 …  1080p · 2.1 GB · Sample Finder

Example 2: a file with every optional field

Two entries: torrents that are only asked while TorBox is switched on, and direct links.

[
  {
    "name": "Sample Torrents",
    "type": "json_imdb",
    "itemType": "info_hash",
    "url": "https://torrents.example.org/u/demo/stream/%searchPattern.json",
    "searchPattern": { "movie": "movie", "tv": "series" },
    "jsonResultsKey": "streams",
    "sizeAttr": "meta.bytes",
    "torrentNameTargetKey": "meta.release",
    "debridProvider": "tb"
  },
  {
    "name": "Sample Direct",
    "type": "json_imdb",
    "itemType": "http_url",
    "url": "https://videos.example.com/api/%searchPattern",
    "searchPattern": { "movie": "movie", "tv": "series" },
    "jsonResultsKey": "data.items",
    "httpUrlTargetKey": "links.play",
    "sizePattern": "Size: ([\\d.,]+) ?(GB|MB)"
  }
]

With TorBox switched on, both are asked. With only Real-Debrid switched on, only "Sample Direct" is asked.

"Sample Torrents", for the film tt0000101, asks https://torrents.example.org/u/demo/stream/movie/tt0000101.json and gets:

{
  "streams": [
    {
      "title": "Open Film 2024 2160p DV",
      "infoHash": "fedcba9876543210fedcba9876543210fedcba98",
      "fileIdx": 2,
      "meta": { "bytes": 12500000000, "release": "Open.Film.2024.2160p.WEB.DV.mkv" }
    }
  ]
}

This gives a TorBox torrent, file 2, named Open.Film.2024.2160p.WEB.DV.mkv (from meta.release), 12.5 GB (from meta.bytes), graded 4K and Dolby Vision. It is shown as Open Film 2024 2160p DV with 4K · 12.5 GB · Sample Torrents.

"Sample Direct", for season 2, episode 5 of tt0000202, asks https://videos.example.com/api/series/tt0000202:2:5 and gets:

{
  "data": {
    "items": [
      {
        "title": "Sample Show S02E05 720p",
        "description": "Size: 0,6 GB",
        "links": { "play": "https://media.example.com/v/s02e05-720.mp4" }
      },
      {
        "title": "Sample Show S02E05 1080p",
        "description": "Size: 1.2 GB",
        "links": {}
      }
    ]
  }
}

The first item becomes a direct link to https://media.example.com/v/s02e05-720.mp4, 0.6 GB (from sizePattern; the comma is a decimal point), shown as Sample Show S02E05 720p with 720p · 0.6 GB · Sample Direct. The second item has no links.play, so it is skipped.

Example 3: a Stremio add-on link

The person pastes https://streams.example.org/c/eyJkZW1vIjp0cnVlfQ/manifest.json, which answers:

{
  "id": "org.example.sample-streams",
  "version": "1.0.0",
  "name": "Sample Streams",
  "description": "A made-up add-on used in the Omnio add-on format examples.",
  "resources": ["stream"],
  "types": ["movie", "series"],
  "idPrefixes": ["tt"],
  "catalogs": []
}

Omnio accepts it as "Sample Streams", for films and series, keeps the link on this device, and from then on asks https://streams.example.org/c/eyJkZW1vIjp0cnVlfQ/stream/movie/tt0000101.json for a film and https://streams.example.org/c/eyJkZW1vIjp0cnVlfQ/stream/series/tt0000202:2:5.json for an episode. A sample answer for the episode:

{
  "streams": [
    {
      "name": "Sample\n1080p",
      "title": "Sample.Show.S02E05.1080p.WEB\n💾 1.5 GB",
      "infoHash": "0123456789ABCDEF0123456789ABCDEF01234567",
      "fileIdx": 4,
      "behaviorHints": { "filename": "Sample.Show.S02E05.1080p.WEB.mkv", "videoSize": 1500000000 }
    },
    {
      "name": "Sample\n4k",
      "description": "Sample Show S02E05\nready link",
      "url": "https://cdn.example.org/play/abc.mkv"
    },
    {
      "name": "Sample",
      "title": "A trailer",
      "ytId": "abcdefghijk"
    }
  ]
}

The list shows the 4K direct link first (4K · Sample Streams), then the torrent (1080p · 1.5 GB · Sample Streams) once the person's debrid service says it can play it.

11. Safety

• Your debrid key. Omnio never adds a person's debrid key, account or any other personal data to a request it sends to an add-on. The one exception is a registration entry (section 7), which exists to send the key to the host the file names: only add a file with registration entries if you trust whoever runs that host with your debrid key. If your add-on needs a key, make it a Stremio add-on and let people put the key in its link (as many Stremio add-ons do): Omnio keeps a Stremio link encrypted (on the account from 0.1.50, on the device before) and never shows the full address. Never ask for a key in an add-on file's address: that address is saved to the account.
• https only. The link people add, every url in an add-on file, every registration address and every direct link (from an add-on file or a Stremio add-on) must be https://. No request Omnio makes to an add-on or a direct link follows a redirect from https to plain http, and Omnio refuses plain http to add-ons and direct links on every Android version it runs on, not only on Android 9 and later.
• Limits. Manifests up to 512 KiB, Stremio answers up to 4 MiB and 500 items, other answers up to 16 MiB, 15 seconds per add-on per search. Names from a manifest are cleaned before they are shown.
• No code runs. An add-on is read as data. Nothing in it is run on the device, apart from sizePattern, which is used only as a regular expression for finding sizes.

12. Changes

If the format changes in a way that affects existing add-ons, the version goes up and the change is listed here.