SubAlchemy 🧙‍♂️

Universal SRT subtitle converter & aggregator for Stremio — built specifically for Samsung TVs running Tizen 9.

➡️ Install: open the addon in Stremio and click Install. The "Configure" button lets you add optional API keys and pick up to 3 preferred languages.

📺 Why SubAlchemy?

Samsung Tizen 9 (and several other smart TV platforms) does not support WebVTT (.vtt) or Advanced SubStation Alpha (.ass/.ssa) subtitles inside Stremio. Since 90% of community subtitle uploads — especially for anime — are in one of those formats, the TV ends up showing nothing when the user opens the subtitles panel.

SubAlchemy fixes this transparently: it intercepts every /subtitles request, fetches from multiple sources in parallel, converts every format to plain SRT on the fly, and serves the result back to Stremio from its own HTTPS endpoint with the headers Tizen 9 needs (Content-Type: application/x-subrip, Content-Disposition: attachment; filename="...", full CORS, immutable cache).

🌐 5 Subtitle Sources (parallel aggregation)

SubAlchemy queries all 5 providers simultaneously with a per-provider 10s deadline race. Any provider that fails or times out is logged and skipped — the batch never aborts.

Get free API keys (all optional — the addon works out-of-the-box without any):

• SubDL → https://subdl.com/panel/api
• SubSource → https://subsource.net/ (My Profile)
• Wyzie → https://store.wyzie.io/redeem

🔄 Universal Format Conversion

Every non-SRT subtitle is converted in-memory to clean SRT before being served to Stremio:

Smart encoding detection: chardet + BOM sniffing + iconv-lite automatically normalize Shift-JIS, Big5, GBK, EUC-KR, KOI8-R, Windows-1250/1252 → UTF-8. Accents in PT-BR/ES/FR always render correctly.

Magic-byte format detection: since AnimeTosho URLs end in a numeric file ID (no extension), the converter inspects the first 4 bytes of every download to identify the actual format.

Ad removal: promotional lines and leftover ASS style tags are stripped automatically.

🌍 Language Priority Fallback

Pick up to 3 preferred languages in priority order on the configure page. The addon supports 12 languages out of the box:

🇧🇷 Portuguese (Brazil) · 🇬🇧 English · 🇪🇸 Spanish · 🇫🇷 French · 🇩🇪 German · 🇮🇹 Italian · 🇯🇵 Japanese · 🇨🇳 Chinese (Simplified + Traditional) · 🇷🇺 Russian · 🇸🇦 Arabic · 🇮🇳 Hindi · 🇰🇷 Korean

Fan-sub variants like Brazilian_CR (Erai-raws) and POR-BR (Ironclad) are auto-recognized.

Flow:

1. Try each user language in priority order. Stop at the first one with matching subtitles.
2. If none match → fall back to English (tagged (Fallback) in the UI).
3. If English also missing → return empty (no placeholder).

Candidate iteration: if the first subtitle of a language fails to download/convert (e.g. OpenSubtitles .gz returns 401), the handler automatically tries the next one, up to 30 candidates per language — so you always get a working subtitle even when one source is flaky.

🛡️ Bypassing Cloud IP Blocks

Cloud-hosted Stremio addons (Render, Heroku, Railway, etc.) often get 403 Forbidden from OpenSubtitles because their IPs are flagged as datacenters.

SubAlchemy solves this with a Docker container running Cloudflare WARP — all OpenSubtitles traffic is routed through a local SOCKS5 proxy at 127.0.0.1:40000, making the requests appear as legitimate residential traffic. The legacy rest.opensubtitles.org REST API is used with the public VLSub 0.10.3 X-User-Agent header (keyless). On HTTP 401, the provider attempts a one-shot token refresh via the new api.opensubtitles.com/api/v1/login endpoint.

📺 Tizen 9 Compatibility

The /srt/:subId.srt proxy endpoint sends everything Samsung's player needs:

• ✅ Content-Type: application/x-subrip; charset=utf-8
• ✅ Content-Disposition: attachment; filename="<id>.srt" (some Tizen firmware refuses to load without an explicit filename)
• ✅ Full CORS headers (Access-Control-Allow-Origin: * + methods + headers + max-age)
• ✅ OPTIONS preflight handler returning 204 No Content (some Tizen firmware sends a preflight before the GET)
• ✅ Cache-Control: public, max-age=31536000, immutable (subId is content-addressed — player can re-fetch on timeline scrub)

🚀 Self-Hosting

Option A — Deploy to Render (recommended, free tier)

1. Fork the repository on GitHub.
2. Go to https://render.com/ and create a new Web Service.
3. Connect your forked repository.
4. Runtime: select Docker (not Node) — Render will detect the Dockerfile automatically.
5. Environment variables (all optional):
   • ENCRYPTION_KEY — 64-char hex string for AES-256-GCM config encryption. Generate with:

     node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
     

   • OS_API_KEY — for OpenSubtitles v2 API fallback (get one at https://www.opensubtitles.com/api)
6. Deploy. You'll get a URL like https://<your-service>.onrender.com.
7. Share https://<your-service>.onrender.com/configure with your users.

⚠️ Since v2.3.2 the addon depends on lzma-native (native C addon). If the Render build fails with a compile error, add this line to the Dockerfile before npm install:

RUN apt-get update && apt-get install -y python3 make g++

Option B — Local development (no Docker)

git clone https://github.com/texugo7badger/subalchemy.git
cd subalchemy
npm install
npm start

Then open http://localhost:7000/configure and add http://localhost:7000/manifest.json to Stremio.

⚠️ Without Docker+WARP, the OpenSubtitles provider may receive 403 from cloud-flagged IPs. All other providers work normally. lzma-native requires a C/C++ toolchain — install build-essential (Linux) or Xcode CLI tools (macOS).

.env reference (all optional)

PORT=7000
LOG_LEVEL=info

# OpenSubtitles v2 fallback (only used if legacy REST returns 401)
OS_API_KEY=

# Default API keys pre-filled in the UI
SUBDL_API_KEY=
SUBSOURCE_API_KEY=
WYZIE_API_KEY=

# AES-256-GCM encryption for user config in install URL
ENCRYPTION_KEY=

🏗️ Architecture

Stremio client ──GET /subtitles/:type/:id──▶ SubAlchemy (Express)
                                                │
                                                ▼
                              ┌─────────────────────────────────────┐
                              │ 1. Resolve title (Cinemeta / Kitsu) │
                              │ 2. Query 5 providers in parallel    │
                              │    (Promise.all + per-provider 10s)  │
                              │ 3. Pick best sub by user priority   │
                              │ 4. Iterate candidates on failure    │
                              │ 5. Download → detect compression →  │
                              │    decompress .xz/.gz/.zip →        │
                              │    convert ASS/VTT/ZIP → SRT        │
                              │ 6. Clean ads, store in memory       │
                              └─────────────────────────────────────┘
                                                │
Stremio client ◀──HTTPS SRT── /srt/<id>.srt
                              (CORS + Content-Disposition + immutable)

Repository structure

subalchemy/
├── addon.js                  # Express server entrypoint
├── manifest.js               # Stremio addon manifest
├── Dockerfile                # node:20-slim + Cloudflare WARP
├── entrypoint.sh             # Starts dbus + warp-svc + warp-cli + node
└── src/
    ├── handlers/subtitles.js       # ⭐ Priority fallback + candidate iteration
    ├── providers/                   # 5 subtitle providers (BaseProvider interface)
    ├── converters/                  # ASS/VTT/ZIP/XZ/GZ → SRT pipeline
    ├── cache/                       # InflightCache + SubtitleStore (in-memory)
    ├── routes/                      # Express routers (stremio/proxy/configure/etc.)
    ├── meta/                        # Cinemeta + Kitsu title resolution
    └── ui/                          # /configure HTML page (component-based)

🛠️ Tech Stack

• Runtime: Node.js 20 (Docker node:20-slim)
• Web server: Express 4
• HTTP client: Axios 1.18
• Proxy: socks-proxy-agent 8 + Cloudflare WARP daemon
• HTML scraping: Cheerio 1.2 (AnimeTosho)
• ASS parsing: ass-compiler 0.1 + subsrt-ts 2.1
• ZIP extraction: adm-zip 0.5
• XZ decompression: lzma-native 8.0
• GZ decompression: Node.js built-in zlib
• Encoding detection: chardet 2.1 + iconv-lite 0.7

🤝 Recommended Companion Addon: SubSense

For the best experience across all your devices, use SubSense alongside SubAlchemy:

• SubSense — great for PC and Mobile. Fast access to modern formats (VTT/ASS) without conversion overhead.
• SubAlchemy — essential for Samsung TVs and TV sticks. Fetches the same sources but transmutes them into SRT.

When watching on your TV, just select the subtitle labeled SubAlchemy [...] — it will load flawlessly.

💜 Support

If SubAlchemy solved your TV's subtitle problem, consider buying the developer a coffee:

👉 https://ko-fi.com/G4H521S5GK

📜 License

MIT — feel free to fork, modify, and self-host. Pull requests welcome!