api

Overview ¶

Package api implements the enginefs-compatible HTTP surface that stremio-web expects from a Stremio streaming server. It depends only on the interfaces in internal/types, so the engine/settings/media implementations are pluggable.

Niche routes fully wired: /list, /:ih/peers, /stream alias, /get-https (cert fetch from api.strem.io), /yt (yt-dlp shell-out), /casting (SSDP discovery), /local-addon (local-files Stremio addon), and HLS transcoding (/hlsv2 via the ffmpeg transcoder in internal/media). thumb.jpg is a cosmetic 404 stub.

Package api — archive streaming for zip / rar / 7zip / tar / tgz

Routes dispatched by handleArchive (seg[0] is the format extension):

GET|POST /{ext}/create             — create session, return {"key":…} or redirect
GET|POST /{ext}/create/{key}       — same, with caller-supplied key
GET      /{ext}/stream             — ?key=&file= redirect to full stream URL
GET      /{ext}/stream/{key}       — redirect to /{ext}/stream/{key}/{selectedFile}
GET      /{ext}/stream/{key}/{…}   — extract entry (once) and serve with Range support

Create payload (JSON; may be gzip+base62 encoded in ?lz= query param):

Object  {"url":"…","from":"…","fileIdx":0,"fileMustInclude":"…"}
Array   [{"url":"…",…}]   — first element is used

"url" and "from" are synonyms for the archive source. http/https sources are downloaded to a temp file; everything else is treated as a local path.

Package api — Bitmagnet Stremio add-on at /bitmagnet/*.

Routes:

GET /bitmagnet/manifest.json
     → Stremio addon manifest (id community.stremioservergo.bitmagnet, v0.1.0)
GET /bitmagnet/stream/<type>/<id>.json
     → {streams:[{infoHash,...}]} from self-hosted Bitmagnet DHT index

Bitmagnet is queried via its GraphQL API (POST to STREMIO_BITMAGNET_URL). Title and year are resolved via a Cinemeta-compatible metadata addon (STREMIO_METADATA_URL, default Cinemeta) and cached for 6 hours. If STREMIO_BITMAGNET_URL is unset the manifest still serves but all stream requests return an empty result set.

Package api — DLNA/UPnP casting device discovery and AVTransport control.

GET /casting → discover UPnP MediaRenderers, return

JSON array [{id, name, type, model, location}] (may be empty)

GET /casting/:id → single device by UDN/USN id (404 if unknown) GET|POST /casting/:id/player[/:cmd] → AVTransport:1 control

Discovery: Uses goupnp to search for urn:schemas-upnp-org:device:MediaRenderer:1 devices on the LAN. Only devices that expose an AVTransport:1 service are listed. Results are cached for 30 seconds; /casting triggers discovery only on a cache miss so cache hits never block.

Player control (UPnP AVTransport:1 via goupnp):

Command → AVTransport action
  load / setUrl → SetAVTransportURI(CurrentURI, DIDL-Lite meta) then Play
  play          → Play(Speed=1)
  pause         → Pause
  stop          → Stop
  seek          → Seek(Unit=REL_TIME, Target=HH:MM:SS from "time" param)
  status        → GetPositionInfo → {trackDuration, relTime, trackURI}

Command resolution: (1) path suffix /casting/:id/player/:cmd, (2) ?command=, (3) inferred from param presence (source→load, stop→stop, etc.).

Package api — shared TLS-certificate provisioning used by both the GET /get-https handler and the background auto-renewer (cmd/stremio-server).

ProvisionCert contacts https://api.strem.io/api/certificateGet, parses the issued Let's Encrypt wildcard cert (current nested schema or the legacy flat one), installs https-cert.pem / https-key.pem under appPath, and returns the issued domain plus expiry. The authKey can be cached so renewals need no further user interaction.

Package api — FTP/FTPS and HTTP(S) direct streaming via the /ftp route.

GET|HEAD /ftp/{filename}?lz=<encoded>

The lz parameter is an lz-string (compressToEncodedURIComponent) encoded JSON object {"ftpUrl":"<url>"} where url may be ftp://, ftps://, http://, or https://. The file is streamed to the client with Accept-Ranges / 206 partial content support when the total resource size is known.

Session routes respond 501 — the direct ?lz route is the supported path:

/ftp/create, /ftp/create/{key}
/ftp/stream, /ftp/stream/{key}/{file...}

Package api — GET /get-https?authKey=..&ipAddress=..

Provisions a TLS certificate from api.strem.io (see certprovision.go for the shared logic), installs https-cert.pem / https-key.pem under cfg.AppPath, and returns {ipAddress, domain, port}. The authKey is cached so the background renewer in cmd/stremio-server can refresh the cert without user interaction.

NOTE: This endpoint requires a valid Stremio authKey issued by api.strem.io after a real Stremio account login. Without it, the API returns no certificate and no files are written.

Package api — local-files Stremio addon at /local-addon/*.

Routes:

GET /local-addon/manifest.json
     → Stremio addon manifest (id org.stremio.local.go, v1.0.0)
GET /local-addon/catalog/:type/:id[.json]
     → {metas:[{id,type,name,poster?}]} — scans LOCAL_FILES_DIR for video files
GET /local-addon/meta/:type/:id[.json]
     → {meta:{id,type,name,poster?}} for a scanned file (local: or tt id)
GET /local-addon/stream/:type/:id[.json]
     → {streams:[{url:"file://..."}]} for a scanned file

IMDB resolution: filenames are parsed for title + year + season/episode via regexes mirroring the reference scanner.rs. The resolved title+year is queried against the public IMDB suggestion API:

https://v3.sg.media-imdb.com/suggestion/x/<urlencoded-title>.json
Response: {"d":[{"id":"tt…","l":"title","y":year,"qid":"movie|tvSeries","i":{"imageUrl":"…"}}]}

Match heuristic (highest score wins):

• Exact title match: +10; prefix match: +5
• Year match (exact): +8; within 1 year: +4
• qid matches content type (movie/tvSeries): +3

Resolution is lazy/background (goroutine per file, one attempt, 8 s timeout) so catalog requests are never blocked. Results are cached in-memory keyed by localID (SHA-256 of abs path). When an IMDB tt id is resolved it replaces the local: id in catalog/meta output so Stremio shows real IMDB metadata + poster. Falls back to local: id if resolution fails.

If LOCAL_FILES_DIR is unset or empty the manifest still serves and all catalogs/meta/stream return empty results.

Package api — NZB/Usenet streaming at /nzb/*.

Routes:

POST /nzb/create
POST /nzb/create/{key}   body: {"servers":[{host,port,user,pass,ssl,connections}], "nzbUrl":"..."}
                         or ?lz=<lz-string-encoded-json>
                         → {"key":"<session-key>"}
GET  /nzb/create?lz=...  → creates the session like POST, then 307-redirects
                         to /nzb/stream/{key} (stremio-core's Stream::convert()
                         emits this GET form for NZB streams)
GET  /nzb/create         → 501 (no ?lz= payload)

GET  /nzb/stream?key={key}
GET  /nzb/stream/{key}/{file...}
                         → assembled file served with Range/HEAD support

Sessions expire after 1 hour of inactivity; extracted temp files are removed by a background janitor started lazily on first create.

Package api — Torznab Stremio add-on at /torznab/*.

Routes:

GET /torznab/manifest.json
     → Stremio addon manifest (id community.stremioservergo.torznab, v0.1.0)
GET /torznab/stream/<type>/<id>.json
     → {streams:[{infoHash,...}]} from a Torznab indexer (Prowlarr/Jackett/NZBHydra/Bitmagnet)

The indexer is queried via its Torznab RSS/XML API (GET to STREMIO_TORZNAB_URL). Titles are resolved via Cinemeta (v3-cinemeta.strem.io) and cached for 6 hours. If STREMIO_TORZNAB_URL is unset the manifest still serves but all stream requests return an empty result set.

Package api — GET /yt/:id and GET /yt/:id.json

Shells out to the system yt-dlp binary to resolve YouTube video formats. /yt/:id.json → JSON {url, itag, quality, container, hasVideo, hasAudio,

isLive, isHLS, isDashMPD, approxDurationMs, mimeType}

/yt/:id → 307 redirect to the resolved format URL

The reference (server/src/routes/youtube.rs) uses the rusty_ytdl library; we shell out to yt-dlp instead because it is widely available and actively maintained. Behaviour is equivalent: pick a progressive (audio+video) mp4 format, fall back to any progressive format.