mirror of
https://gitlab.com/vyla-entertainment/documentation.git
synced 2026-11-16 15:37:23 -05:00
178 lines
5.5 KiB
Markdown
178 lines
5.5 KiB
Markdown
# 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. |