# Contributing a Source Provider

Technical guide for authoring, testing, and registering a new video scraping resolver or embed entry in the Vyla SDK.

## Overview The Vyla SDK uses independent provider scrapers located in `src/sources/` and embed player templates in `src/embed_config.js`. We welcome contributions that expand coverage for movies and television series. --- ## Scraper Contract Every provider module is an ES Module exporting a `getStream` function: ```typescript export async function getStream(args: StreamArgs): Promise ``` ### Context Arguments (`args`) `createStreamArgs()` in `src/utils/helpers.js` passes the following properties to `getStream`: - `id` *(string | number)* — TMDB numeric ID or string IMDb ID. - `s` *(number | null)* — Season number for television series (or `null` for movies). - `e` *(number | null)* — Episode number for television series (or `null` for movies). - `clientIP` *(string | null)* — Client IP address forwarded for geo-token generation. - `absoluteBase` *(string | null)* — Base URL prefix when running behind a local proxy. - `audio` *('sub' | 'dub')* — Audio preference inferred from the source key. - `sdk` *(VylaSDK)* — The active `VylaSDK` instance. - `config` *(SourceConfig)* — The matching entry from `src/config.js`. - `tmdbApiKey` *(string)* — Resolved TMDB API key. If your source needs title, year, or IMDb ID metadata, call `getTmdbMetadata(id, isTv, tmdbApiKey)` or `resolveImdbId(id, isTv, tmdbApiKey)` from `../utils/helpers.js`. --- ## Implementation Steps ### 1. Create the Scraper Module Create a new file in `src/sources/.js`: ```javascript import { USER_AGENT } from '../utils/helpers.js'; const BASE_URL = 'https://provider-domain.example.com'; const DEFAULT_HEADERS = { 'User-Agent': USER_AGENT, Referer: `${BASE_URL}/`, Origin: BASE_URL }; export async function getStream(args) { const { id, s, e, config } = args || {}; if (!id) return null; const isTv = s != null && e != null; const endpoint = isTv ? `${BASE_URL}/api/tv/${id}/${s}/${e}` : `${BASE_URL}/api/movie/${id}`; try { const response = await fetch(endpoint, { headers: DEFAULT_HEADERS, signal: AbortSignal.timeout(config?.timeout || 15000) }); if (!response.ok) return null; const data = await response.json(); if (!data?.streamUrl) return null; const allUrls = [ { url: data.streamUrl, headers: { ...DEFAULT_HEADERS, Referer: data.referer || DEFAULT_HEADERS.Referer }, server: 'MySource - Primary', quality: data.quality || '1080p', type: data.streamUrl.includes('.m3u8') ? 'hls' : 'mp4' } ]; return { url: allUrls[0].url, headers: allUrls[0].headers, allUrls }; } catch { return null; } } ``` --- ### 2. Register in `src/config.js` Add the source configuration object to `SOURCES`. Set `dedicated: true` if the source is a single-host/dedicated catalog rather than a multi-provider aggregator: ```javascript { key: 'mysource', label: 'My Source', sourceFile: 'mysource', proxyParam: 'ms', timeout: 25000, jitter: 500, retries: 2, multiUrl: true, dedicated: true, cdnHeaders: [{ pattern: /provider-domain\.example\.com/i, headers: { Referer: 'https://provider-domain.example.com/', Origin: 'https://provider-domain.example.com', }, }], } ``` **Key Fields:** - `key`: Lowercase identifier without spaces (e.g. `mysource`). - `label`: Clean display label for client UIs. - `sourceFile`: Filename inside `src/sources/` (without `.js`). - `proxyParam`: Unique 2-to-4 character query flag for the HLS proxy. - `timeout`: Maximum execution budget in ms (typically 20,000–35,000). - `jitter`: Random delay ceiling in ms (typically 300–500). - `retries`: Number of retry attempts during health probing. - `multiUrl`: Whether the source returns multiple stream candidates in `allUrls`. - `dedicated`: Set to `true` for dedicated single-host sources; omit or set `false` for aggregators. - `disabled`: Optional boolean to exclude the source from active loading and probing. --- ### 3. Register an Embed Player in `src/embed_config.js` (Optional) If the provider offers a standalone iframe embed player, add an entry to `EMBEDS` in `src/embed_config.js` using `{id}`, `{s}`, and `{e}` placeholders: ```javascript { key: 'mysource', label: 'My Source', movie: 'https://provider-domain.example.com/embed/movie/{id}', tv: 'https://provider-domain.example.com/embed/tv/{id}/{s}/{e}', ads: false, } ``` Set `ads: false` only when the embed is verified ad-free. --- ### 4. Local Testing Run your scraper against known TMDB titles: ```bash node test/index.js mysource 155 node test/index.js mysource 1396 1 1 ``` Verify that: 1. A valid `url` and `allUrls` array are returned (or `null` when unavailable). 2. The format `type` is correctly identified (`hls`, `dash`, `mp4`, or `mkv`). 3. Required upstream headers (`Referer`, `Origin`, `User-Agent`) are included. 4. Invalid IDs or network timeouts return `null` cleanly without throwing uncaught exceptions. --- ## Contribution Checklist - [ ] Code is formatted with clean ES Module syntax. - [ ] No hardcoded personal API keys or credentials. - [ ] No untrusted `eval()` or un-sanitized script execution. - [ ] Upstream stream candidate URLs are verified for playback. - [ ] Timeouts (`AbortSignal.timeout`) are applied to all network requests.