# Providers

<p class="page-description">How Vyla SDK sources are configured, selected, and verified.</p>

Vyla SDK aggregates multiple independent providers. Each has different internal mechanisms, reliability profiles, and timeout characteristics. This page explains the source layer that powers both direct SDK use and the optional Stream API.

:::callout-note
Provider availability and performance can vary based on your network environment. When self-hosting, providers may work differently than on residential connections due to IP-based blocking from upstream sources.
:::

---

## How Providers Are Used

When your app calls `getStream()`-directly or through Stream API:

1. All active (non-disabled) providers are queried **simultaneously** with per-source random jitter to stagger upstream requests
2. Each provider has its own **timeout**, **retry count**, and **backoff delay**
3. Every returned URL is **verified** - first via a HEAD request to the raw upstream URL, then via a proxied HLS playability check
4. Only URLs that pass both verification steps appear in the response as `source` events

Because the endpoint is SSE, **verified sources are emitted immediately as each provider resolves** - your player receives them progressively. The stream closes once every provider has either resolved or timed out.

:::callout-info
Call `sdk.getSources(true)` to inspect enabled providers and `sdk.probeAllSources()` for a live availability signal. If you use Stream API, its `/health` endpoint exposes probes over HTTP.
:::

---

## Provider Configuration

Each provider is defined with the following properties:

| Field | Description |
| --- | --- |
| `key` | Internal identifier used in API responses and the `source` field |
| `label` | Human-readable name shown in the `label` field |
| `proxyParam` | Short query parameter used to route proxied requests |
| `timeout` | Maximum time (ms) to wait for a stream URL |
| `sourcesTimeout` | Optional secondary timeout (ms) for an internal source-listing step |
| `jitter` | Max random delay (ms) before the request fires |
| `retries` | Number of retry attempts on failure |
| `skipProxy` | If `true`, stream URLs are returned as-is without proxy wrapping |
| `disabled` | If `true`, the provider is excluded from all requests |

---

## Response Time

The first `source` event typically arrives within **3–8 seconds**. Subsequent sources stream in as each provider resolves. The stream closes once the **slowest configured provider** times out.

**Best practice:** always show a loading state, begin playback on the first `source` event, and implement a client-side timeout for the overall stream. See the [Error Handling](/guides/error-handling) guide.

---

## Caching

Results are cached in-memory with a **5-minute TTL**. The per-source stream cache is keyed by `source_key + tmdb_id + season + episode`.

```
CACHE_TTL = 5 minutes
```

---

## The HLS Proxy

All provider stream URLs are wrapped in the server proxy (unless `skipProxy: true`):

```
http://YOUR_API_URL/api?url=<encoded_stream_url>&<proxyParam>=1
```

When your player fetches this path from your self-hosted instance, the server:

1. Fetches the upstream M3U8 with the correct `Referer`, `Origin`, and any provider-specific headers
2. Rewrites all segment URLs and encryption key URIs in the playlist to route through the same proxy
3. Returns the rewritten playlist with `Access-Control-Allow-Origin: *`

---

## Stream Verification

Before a URL is emitted as a `source` event, it passes two verification steps:

1. **`verifyStream`** - a HEAD request to the raw upstream URL. Must return HTTP `< 400`.
2. **`verifyPlayable`** - fetches the proxied URL, validates `#EXTM3U`, checks for `#EXTINF` or `#EXT-X-STREAM-INF`, then fetches the first segment.