# Provider Matrix & Documentation

Tobuzz Extractor utilizes an isolated, provider-agnostic architecture. Every provider implements the `MediaProvider` interface.

---

## The Core Lifecycle: Extracted ≠ Validated ≠ Playable

Understanding the candidate lifecycle is critical when maintaining or debugging providers:

1. **Extracted Stage**:
   The provider successfully parses iframe HTML, API JSON, or WASM output to discover a candidate stream URL.
2. **Validated Stage**:
   Tobuzz Extractor's preflight validation engine (`src/core/validation.ts`) unrolls proxy wrappers if present and performs bounded probes against the master playlist, variant playlist, first segment, and key endpoints. It confirms non-HTML headers, HTTP 200/206 status, and absence of plaintext authentication errors ("IP not in range", "invalid token").
3. **Playable Stage**:
   The final normalized source object is returned with appropriate headers or proxy wrappers (`/api/media-proxy`) so downstream clients (such as Tobuzz or the embedded diagnostic player) can play media without CORS or token expiration errors.

---

## Registered Provider Status Matrix

| Priority | Provider Name | Provider ID | Status | Content | Output Type | Proxy Req. | Preflight Validation | Test Coverage | Implementation |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| **1** | **VidNest** | `vidnest` | **WORKING** | Movies, TV | HLS (`.m3u8`), MP4 | No | Full Playlist/Segment | Unit + Mock + Live | `src/providers/vidnest/index.ts` |
| **2** | **Vidsrc.su** | `vidsrcsu` | **WORKING** | Movies, TV | HLS (`.m3u8`) | No | Full Playlist/Segment | Unit + Mock + Live | `src/providers/vidsrcsu/index.ts` |
| **3** | **Vidsrc.to** | `vidsrcto` | **WORKING** | Movies, TV | HLS (`.m3u8`) | **Yes** (`/api/media-proxy`) | Unwrapped Full Playlist | Unit + Mock + Live | `src/providers/vidsrcto/index.ts` |

---

## Provider Status Classifications

- **WORKING**: Provider resolves candidates, passes preflight validation, and streams play successfully end-to-end in test cases.
- **PARTIALLY WORKING**: Provider works for specific content types (e.g. Movies only) or specific servers, but fails on others.
- **BROKEN**: Upstream provider changed API routes, decryption keys, or anti-bot checks. Fails preflight validation.
- **UNSUPPORTED**: Provider requires headless browsers (Puppeteer/Playwright), persistent browser cookies, or desktop binaries prohibited in edge serverless environments.

---

## Registered Provider Overview

### 1. VidNest (`vidnest`)
- **Architecture**: Multi-server API provider (`alfa`, `gama`, `prime`, `catflix`, `zeta`, `ophim`, `beta`, `sigma`, `lamda`, `hexa`, `delta`).
- **Decryption**: Custom 64-char Base64 lookup cipher.
- **Key Feature**: Automatic audio language classification (Tier 0: explicit English audio preferred over Tier 1 dual audio and Tier 3 non-English audio).
- **Implementation**: `src/providers/vidnest/index.ts`

### 2. Vidsrc.su (`vidsrcsu`)
- **Architecture**: Static header signatures (`X-Client-Fingerprint`, `bW90aGFmYWth`), HMAC request signing (`X-Request-Signature`), and WebAssembly payload decryption.
- **Key Feature**: Queries server list and resolves HLS candidates with required Referer headers.
- **Implementation**: `src/providers/vidsrcsu/index.ts`

### 3. Vidsrc.to (`vidsrcto`)
- **Architecture**: 5-step iframe chain navigation (`vidsrc.to` -> `vsembed.ru` -> `cloudorchestranova.com` -> `playerUrl` -> `api.php`), WebAssembly ChaCha20 cipher decryption, stream host token fetching (`/generate.php`).
- **Key Feature**: Returns proxied HLS URLs (`/api/media-proxy`) to prevent client IP-lock and CORS issues. Unwrapped by validation engine during preflight verification.
- **Implementation**: `src/providers/vidsrcto/index.ts`