3.7 KiB
Providers
How Vyla SDK sources are configured, selected, and verified.
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:
- All active (non-disabled) providers are queried simultaneously with per-source random jitter to stagger upstream requests
- Each provider has its own timeout, retry count, and backoff delay
- Every returned URL is verified - first via a HEAD request to the raw upstream URL, then via a proxied HLS playability check
- Only URLs that pass both verification steps appear in the response as
sourceevents
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 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:
- Fetches the upstream M3U8 with the correct
Referer,Origin, and any provider-specific headers - Rewrites all segment URLs and encryption key URIs in the playlist to route through the same proxy
- 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:
verifyStream- a HEAD request to the raw upstream URL. Must return HTTP< 400.verifyPlayable- fetches the proxied URL, validates#EXTM3U, checks for#EXTINFor#EXT-X-STREAM-INF, then fetches the first segment.