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.

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.

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, used by some providers
jitter Max random delay (ms) before the request fires, to stagger upstream hits
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

Providers with disabled: true are completely skipped — they won't appear in health checks or fanout responses.

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 — in the worst case this can be 60+ seconds (e.g. cinezo has a 60 s timeout), though most sources emit well before then.

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; the aggregate source-results cache is keyed by tmdb_id + season + episode + base. Cache hits skip the provider fetch entirely and return near-instantly. 

CACHE_TTL = 5 minutes

The cache resets on server restart. Cache size is reported in the /api/health response under the cache field.

The HLS Proxy

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

http://localhost:7860/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: *

This means your player never talks to the provider directly — all HLS traffic flows through the proxy, keeping CORS and rate-limiting issues fully contained.

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 (skipped for SKIP_VERIFY sources). 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 with a range request.

Sources that fail either step — HTTP errors, timeouts, non-HLS/non-MP4 content — are silently dropped. MP4 sources skip the #EXTM3U check and are verified via HEAD + content-type inspection instead. HTTP 429 responses and timeout/abort errors are treated as passing (stream exists but is rate-limited).

/test runs the same two-step verification pipeline as /movie and /tv. Check the ok field in the response body — HTTP status is always 200 regardless of result.

Disabled Providers

Providers marked disabled: true in config are completely excluded from:

  • /api/movie and /api/tv fanout
  • /api/health probes
  • GET /api?sources_meta listings

If a provider you expect to see is missing from responses, check whether it's been disabled.

Multi-URL Sources

Some providers return multiple candidate stream URLs (via allUrls). For these, verification runs through each candidate in order and returns the first one that passes. If none pass, the source is dropped.

For providers with SKIP_VERIFY, all candidate URLs are returned as separate source events without verification. These are not distinguished by numbered labels in the response.