# Porting DebridStream's Config-Driven Scraper Pipeline to Your Android TV App

## When to Use This Reference
- Porting a DebridStream-style (Pattern B) config-driven scraper pipeline from decompiled APK analysis into your own Android TV app
- User says "copy it 1:1, not inspired-by" — exact data flow, not a reimagined version
- Building a streaming app that uses Torrentio/public addons for infoHashes and resolves via own debrid clients
- Adding filename-based quality enrichment (4K, HDR, DV, Atmos detection from stream titles)

## Architecture Overview

DebridStream uses two addon types:
1. **External addons** (type: `json_imdb`) — user-configured URLs with `%searchPattern` placeholder. Config tells parser which JSON fields to extract.
2. **Registered addons** (type: `reg_hash`) — go through DebridStream's own backend: `{baseUrl}/{mode}/{encrypted-config}/stream/%searchPattern.json`.

Type 1 can be implemented directly. Type 2 requires a backend proxy.

## Data Flow (1:1 Copy)

```
ScraperAddonConfig[]    ← URL template + JSON parse keys + item type + debrid provider
  │
  ├─ For each addon in parallel (supervisorScope, 8s timeout):
  │     URL.replace("%searchPattern", "movie/tt1234567")
  │     HTTP GET → config-driven parser
  │       Uses: jsonResultsKey, itemType (info_hash/http_url),
  │             sizeAttr (dot-path), torrentNameTargetKey, httpUrlTargetKey
  │       → List<ScraperLink>(infoHash, directUrl, title, videoSize)
  │
  ├─ DebridRouter:
  │     infoHash → checkCachePerProvider → resolveStream via first cached
  │     directUrl → resolveStream via first available provider
  │
  └─ ScraperQualityDetector: filename regex → quality label on stream name
```

## Addon Config Fields (U2.c Mirror)

| Field | Description | Example |
|-------|-------------|---------|
| `url` | HTTPS template with `%searchPattern` | `https://torrentio.strem.fun/stream/%searchPattern.json` |
| `jsonResultsKey` | JSON array field | `streams` |
| `itemType` | `info_hash` or `http_url` | `info_hash` |
| `httpUrlTargetKey` | For http_url items | `url` |
| `sizeAttr` | Dot-path to video size | `behaviorHints.videoSize` |
| `torrentNameTargetKey` | Dot-path to title | `title` |
| `debridProvider` | Specific provider or null | `null` (all) |

## JSON Parser Requirements (U2.f Mirror)

- Dot-notation field resolution: `"behaviorHints.videoSize"` navigates nested objects
- Per-addon field extraction from config
- Two item types: `info_hash` (extract infoHash) vs `http_url` (extract direct URL)

## Quality Detection Regex (C1125i Mirror)

| Pattern | Regex | Detects |
|---------|-------|---------|
| 4K | `[\s\-\.\(\[\]+(4k\|2160p)[\s\-\.\)\]]+` | is4K |
| 1080p | `[\s\-\.\(\[\]+(1080p)[\s\-\.\)\]]+` | isFHD |
| REMUX | `[\s\-\.\(\[\]+(remux\|bdremux)[\s\-\.\)\]]+` | isRemux |
| HEVC | `[\s\-\.\(\[\]+(hevc\|h265\|x265)[\s\-\.\)\]]+` | isHevc |
| Atmos | `[\s\-\.\(\[\]+(atmos)[\s\-\.\)\]]+` | isAtmos |
| DV | `[\s\-\.\(\[\]+(dv\|dovi\|dolby vision)[\s\-\.\)\]]+` | isDV |
| HDR | `[\s\-\.\(\[\]+(hdr\|hdr10)[\s\-\.\)\]]+` | isHDR |
| CAM | `[\s\-\.\(\[\]+(cam\|telesync\|ts)[\s\-\.\)\]]+` | isCAM |

Use Kotlin raw strings (`"""..."""`) for all regex patterns to avoid backslash escape issues.

## Torrentio Endpoint (Verified May 2026)

`https://torrentio.strem.fun/stream/movie/{imdbId}.json` returns **50 streams** with real infoHashes — no debrid tokens needed. Works reliably when reachable (was thought broken due to transient DNS issues, not API failure).

Response: standard Stremio protocol with `infoHash`, `title`, `fileIdx`, `behaviorHints`.

Quality signals are embedded in the `title` field as filename text. Example:
`Forrest.Gump.1994.2160p.BluRay.REMUX.DV.P7.HDR.MULTi.TrueHD.Atmos.7.1.H265-BTM`
→ Flags: **4K, REMUX, DV, HDR, HEVC, Atmos, TrueHD**

## Known Addon Endpoint Status (May 2026)

| URL | Status | Streams |
|-----|--------|---------|
| `torrentio.strem.fun` | ✅ 200, 50 streams, all infoHash | Working |
| `aiostreams.elfhosted.com` | ✅ 200, 1 placeholder (needs config) | Broken |
| `mediafusion.elfhosted.com` | ✅ 200, 0 streams | Broken |
| `comet.elfhosted.com` | ❌ 403 (Cloudflare) | Broken |
| `jackettio.elfhosted.com` | ✅ 200, 1 placeholder | Broken |
| `peerflix.elfhosted.com` | ❌ 404 | Dead |

Only Torrentio returns usable data without configuration.

## Pitfalls

- Don't assume HTTP 200 = useful data. Verify actual infoHash presence.
- Don't use Stremio `{baseUrl}/stream/{type}/{id}.json` for custom addons — each addon may have a different URL format via `%searchPattern`.
- `url` (direct playable URL) is often absent. Pipeline must work with infoHashes.
- 8s per-addon timeout in supervisorScope. One slow addon must not block others.
- Quality regex in Kotlin needs raw strings to avoid escape issues.
- When porting: user wants 1:1 data flow copy, not "inspired by" redesign.