# 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.