[Feature Request] Pass stream URL or custom hashes to subtitle addons

[piotrek1488]

Feature Request: Pass stream URL or custom hashes to subtitle addons

Problem

Subtitle addons currently receive limited information about the video being played. The extra parameters include videoHash (OpenSubtitles format), videoSize, and filename (recently added in 71b8012). However, only the OpenSubtitles hash format (CRC64-based, first and last 64KB) is supported.

Many subtitle databases worldwide use entirely different hashing algorithms that cannot be derived from the OpenSubtitles hash. For example, NapiProjekt — the largest Polish subtitle database with 20+ years of community-contributed content — uses MD5 of the first 10MB of the video file. There is no way for a subtitle addon to receive or compute this hash through the current Stremio protocol.

This means that addon developers who want to integrate non-OpenSubtitles services must resort to workarounds like:

• Building and maintaining offline hash databases by scraping subtitle service websites (fragile, incomplete, blocked by Cloudflare)
• Requiring users to provide Real-Debrid API keys so the addon can download 10MB of the file server-side to compute the hash (adds seconds of latency, only works for debrid users)

Both approaches are fragile and limited compared to simply having access to the stream URL.

Impact

This limitation affects subtitle coverage for users who rely on regional/national subtitle databases with non-OpenSubtitles hash formats:

• Polish users — NapiProjekt (napiprojekt.pl) is the primary subtitle source for Polish content. Its entire API exclusively accepts MD5 hashes of video files — there is no title-based search endpoint. This is confirmed by every open-source client: qnapi, napi.py, bashnapi, napi-js, NapiTux, and others.

• Any future subtitle service that uses a different hashing scheme.

Proposed Solution

Option A: Pass stream URL to subtitle addons (preferred)

Add the stream URL (or a streaming server proxy URL) as an extra parameter in subtitle requests:

/subtitles/movie/tt10366206/videoHash=...&videoSize=...&filename=...&streamUrl=https%3A%2F%2F....json

This would allow subtitle addons to:

• Download only the bytes they need via HTTP Range requests (e.g., first 10MB for NapiProjekt) to compute their own hashes
• Work with any hashing algorithm without further changes to Stremio core
• Maintain full backward compatibility — addons that don't need the URL simply ignore it

The implementation path is straightforward: VideoParams in player.rs already holds hash, size, and filename. Adding a stream_url field and populating it from the selected stream's URL (or the streaming server's proxy URL) would make it available to subtitle addons via the existing extra parameter mechanism.

Security consideration: The URL could be the local streaming server's proxy URL (e.g., http://127.0.0.1:11470/...) rather than the raw source URL, limiting exposure. Subtitle addons would only use it for targeted byte-range downloads, not full streaming.

Option B: Support custom hashes via behaviorHints

Extend behaviorHints in stream responses to support arbitrary hash types:

{
  "behaviorHints": {
    "videoHash": "8e245d9679d31e12",
    "videoSize": 1632335363,
    "filename": "Movie.2024.1080p.mkv",
    "hashes": {
      "opensubtitles": "8e245d9679d31e12",
      "md5_10mb": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
    }
  }
}

These would be forwarded to subtitle addons in extra parameters. Stream addons (like Torrentio) that already have access to the file could pre-compute additional hashes.

This is less flexible than Option A (requires stream addon cooperation) but simpler to implement.

Technical Context

Why this can't be solved addon-side

NapiProjekt requires MD5 of the first 10,485,760 bytes (10MB) of the actual video file. This hash is fundamentally different from the OpenSubtitles hash (which uses the first and last 64KB with CRC64). One cannot be derived from the other.

Current workarounds:

1. Offline hash database — Scrape NapiProjekt's website to map IMDB IDs to their internal hashes. This requires bypassing Cloudflare protection (curl_cffi with browser cookies), is inherently incomplete, and creates unnecessary load on NapiProjekt's servers.
2. Real-Debrid integration — Download 10MB from debrid services server-side to compute the hash. Only works for debrid users, adds 2-5 seconds latency on first request.

Both are workarounds for information that Stremio already has available internally (the stream URL or file reference).

Related work

• Commit 71b8012 — Added filename to VideoParams and subtitle extras (thank you! This helps with subtitle matching)
• stremio-bugs#1502 — behaviorHints.videoHash handling on older clients; expected to be resolved with Stremio 5 rollout and new apps using stremio-core/stremio-video
• stremio-addon-sdk#221 — Extra parameters omission in subtitle requests; partially addressed by the filename commit above

Who would benefit

This feature would immediately enable a NapiProjekt Stremio addon serving the Polish-speaking community. Poland has ~38 million native speakers, and NapiProjekt is by far the most popular subtitle source for Polish content — but it's currently impossible to properly integrate with Stremio due to the hash format limitation. The same infrastructure would benefit any future subtitle service using non-OpenSubtitles hashing.