Subtitles

Return subtitle tracks for a movie or episode, optionally matched by file hash.

A subtitle add-on serves subtitle files alongside playback. wako requests subtitles when the user opens the subtitle picker in the player, asks every installed subtitle add-on in parallel, and shows the merged list grouped by language.

Manifest declaration

JSON

{
  "id": "com.example.subs",
  "name": "Community Subs",
  "version": "1.0.0",
  "resources": ["subtitles"],
  "types": ["movie", "series"],
  "catalogs": [],
  "idPrefixes": ["tt"]
}

Endpoint

HTTP

GET /subtitles/{type}/{id}.json
GET /subtitles/{type}/{id}/{extra}.json

For series, {id} follows the same convention as streams ({imdb-id}:{season}:{episode}). The {extra} segment is a URL-style query string that lets wako pass file-specific data for accurate matching:

HTTP

GET /subtitles/movie/tt0083658/videoHash=8e245d9679d31e12&videoSize=2254857830.json
GET /subtitles/series/tt0903747:1:1/filename=breaking.bad.s01e01.mkv.json

Field	Type	Description
`videoHash`	`string`	OpenSubtitles-style hash of the local video file. When provided by the player, wako forwards it so subtitle add-ons can return frame-accurate matches.
`videoSize`	`number`	File size in bytes — used as a secondary match key alongside the hash.
`filename`	`string`	The original filename, when known. Helps add-ons that match by name.

The hash comes from the stream, not the user

wako derives videoHash, videoSize, and filename from the stream that is currently playing. Stream add-ons that include these in their behaviorHints let subtitle add-ons return more precise matches.

Response

JSON

{
  "subtitles": [
    {
      "id": "12345",
      "url": "https://example.com/subs/blade-runner.en.srt",
      "lang": "en"
    },
    {
      "id": "12346",
      "url": "https://example.com/subs/blade-runner.fr.srt",
      "lang": "fr"
    }
  ]
}

Subtitle fields

Field	Type	Description
`id` required	`string`	A stable identifier for the subtitle entry. wako does not interpret it but uses it to deduplicate and remember selections.
`url` required	`string (URL)`	Direct URL to the subtitle file. wako supports `.srt` and `.vtt` natively as JS-rendered overlays; `.ass` / `.ssa` render through the underlying native player.
`lang` required	`string`	ISO 639 language code (`en`, `fr`, `es`, `pt-BR`). wako groups subtitles by language in the picker and applies the user's preferred-language order.

Per-add-on timeout

Subtitle add-ons have a much shorter timeout than streams: wako gives each subtitle add-on 3.5 seconds. The subtitle list opens immediately when the user taps the button, so a slow add-on gets dropped silently rather than blocking the UI.

Hosting the subtitle files

The url you return must be fetchable by the end user's device. Subtitle files are small (a few hundred KB at most), so caching them on a CDN keeps things instant. If your service generates subtitles on demand, return a stable URL and cache the generated file behind it.

For very large catalogs of subtitles, prefer keeping the listing endpoint fast (under one second) and let the actual file URL be whatever long-running source you use — wako does not read the file until the user selects the entry.