Files
documentation/sdk/vyla-sdk/contributing.md

178 lines
5.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Contributing a Source Provider
<p class="page-description">Technical guide for authoring, testing, and registering a new video scraping resolver or embed entry in the Vyla SDK.</p>
## 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<StreamResult | null>
```
### 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/<source_name>.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.