mirror of
https://gitlab.com/vyla-entertainment/documentation.git
synced 2026-11-16 15:37:23 -05:00
140 lines
4.4 KiB
Markdown
140 lines
4.4 KiB
Markdown
# Contributing a Source Provider
|
||
|
||
<p class="page-description">Complete technical guide for authoring, testing, and contributing a new video scraping resolver to the Vyla SDK.</p>
|
||
|
||
## Overview
|
||
|
||
The Vyla SDK maintains its high reliability through a distributed collection of independent provider scrapers located in `src/sources/`. We welcome contributions of new sources that expand coverage for movies, television, and international content.
|
||
|
||
---
|
||
|
||
## Scraper Architecture
|
||
|
||
Every provider module is a self-contained ES Module adhering to a single exported contract:
|
||
|
||
```typescript
|
||
export async function getStream(args: StreamArgs): Promise<StreamResult | { allUrls: StreamResult[] }>
|
||
```
|
||
|
||
### The `args` Object
|
||
When your scraper's `getStream()` is invoked, the SDK passes a normalized `args` context containing:
|
||
|
||
| Field | Type | Description |
|
||
| :--- | :--- | :--- |
|
||
| `id` | `string \| number` | The TMDB numeric media ID or string IMDb ID. |
|
||
| `s` | `number \| null` | Season number for television episodes (or `null` for movies). |
|
||
| `e` | `number \| null` | Episode number for television episodes (or `null` for movies). |
|
||
| `clientIP` | `string \| null` | The viewer's client IP address (if passed from an upstream proxy). |
|
||
| `fetch` | `Function` | Node.js fetch wrapper pre-configured with timeout controls. |
|
||
| `imdbId` | `string \| null` | Automatically resolved IMDb ID (if TMDB API key is configured). |
|
||
| `title` | `string \| null` | Verified media title string. |
|
||
| `year` | `number \| null` | Media release year. |
|
||
|
||
---
|
||
|
||
## Step-by-Step Implementation Guide
|
||
|
||
### Step 1: Create the Scraper Module
|
||
Create a new file in `src/sources/<source_name>.js`:
|
||
|
||
```javascript
|
||
const BASE_URL = 'https://provider-domain.example.com';
|
||
|
||
const DEFAULT_HEADERS = {
|
||
'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36',
|
||
'Referer': `${BASE_URL}/`,
|
||
'Origin': BASE_URL,
|
||
};
|
||
|
||
export async function getStream({ id, s, e, imdbId }) {
|
||
const isTv = s != null && e != null;
|
||
const endpoint = isTv
|
||
? `${BASE_URL}/api/tv/${id}/${s}/${e}`
|
||
: `${BASE_URL}/api/movie/${id}`;
|
||
|
||
const response = await fetch(endpoint, {
|
||
headers: DEFAULT_HEADERS
|
||
});
|
||
|
||
if (!response.ok) {
|
||
throw new Error(`Upstream returned HTTP ${response.status}`);
|
||
}
|
||
|
||
const data = await response.json();
|
||
if (!data.streamUrl) {
|
||
throw new Error('No stream found in upstream response');
|
||
}
|
||
|
||
return {
|
||
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'
|
||
};
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### Step 2: Register in `src/config.js`
|
||
|
||
Add your provider configuration to the `SOURCES` array in `src/config.js`:
|
||
|
||
```javascript
|
||
{
|
||
key: 'mysource',
|
||
label: 'My Source',
|
||
sourceFile: 'mysource',
|
||
proxyParam: 'ms',
|
||
timeout: 12000,
|
||
jitter: 400,
|
||
retries: 1,
|
||
multiUrl: false,
|
||
skipProxy: false,
|
||
skipVerify: false
|
||
}
|
||
```
|
||
|
||
#### Configuration Field Guidelines:
|
||
- `key`: Lowercase alphanumeric identifier without spaces (e.g. `vidlink`, `cinecat`).
|
||
- `label`: Clean display title shown in UI menus.
|
||
- `proxyParam`: Unique 2-to-4 character query flag used by the Stream API HLS proxy (must not collide with existing flags).
|
||
- `timeout`: Maximum execution budget before aborting (typically 8,000ms–15,000ms).
|
||
- `jitter`: Random delay ceiling (typically 300ms–500ms) to avoid server burst locks.
|
||
|
||
---
|
||
|
||
### Step 3: Local Testing
|
||
|
||
Run your scraper against known TMDB titles using the test runner:
|
||
|
||
```bash
|
||
# Test a known movie (The Dark Knight - TMDB 155)
|
||
node test/index.js mysource 155
|
||
|
||
# Test a known TV episode (Breaking Bad S01E01 - TMDB 1396)
|
||
node test/index.js mysource 1396 1 1
|
||
```
|
||
|
||
Verify that:
|
||
1. A valid URL is printed.
|
||
2. The `type` is correctly identified as `'hls'` or `'mp4'`.
|
||
3. Required upstream headers (`Referer`, `Origin`, `User-Agent`) are included.
|
||
4. Testing an invalid ID throws a clean error without crashing the process.
|
||
|
||
---
|
||
|
||
## Contribution Rules & Checklist
|
||
|
||
Before submitting a Pull Request to the GitLab repository:
|
||
|
||
- [ ] Code is formatted with clean ES Module syntax.
|
||
- [ ] No hardcoded personal API keys or credentials.
|
||
- [ ] Provider does not execute external untrusted `eval()` or un-sanitized script execution.
|
||
- [ ] Upstream stream candidate URLs must be verified for playback.
|
||
- [ ] Errors are thrown with informative messages (`throw new Error(...)`).
|