mirror of
https://gitlab.com/vyla-entertainment/documentation.git
synced 2026-11-20 01:17:23 -05:00
fixed syntax issues
This commit is contained in:
@@ -1,40 +1,36 @@
|
||||
# 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>
|
||||
<p class="page-description">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.
|
||||
The Vyla SDK uses independent provider scrapers located in `src/sources/`. We welcome contributions that expand coverage for movies and television series.
|
||||
|
||||
---
|
||||
|
||||
## Scraper Architecture
|
||||
## Scraper Contract
|
||||
|
||||
Every provider module is a self-contained ES Module adhering to a single exported contract:
|
||||
Every provider module is an ES Module exporting a single function:
|
||||
|
||||
```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. |
|
||||
### Context Arguments (`args`)
|
||||
- `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.
|
||||
- `fetch` *(Function)* — Pre-configured fetch wrapper with timeout controls.
|
||||
- `imdbId` *(string | null)* — Auto-resolved IMDb ID.
|
||||
- `title` *(string | null)* — Verified title string.
|
||||
- `year` *(number | null)* — Media release year.
|
||||
|
||||
---
|
||||
|
||||
## Step-by-Step Implementation Guide
|
||||
## Implementation Steps
|
||||
|
||||
### Step 1: Create the Scraper Module
|
||||
### 1. Create the Scraper Module
|
||||
Create a new file in `src/sources/<source_name>.js`:
|
||||
|
||||
```javascript
|
||||
@@ -43,7 +39,7 @@ 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,
|
||||
'Origin': BASE_URL
|
||||
};
|
||||
|
||||
export async function getStream({ id, s, e, imdbId }) {
|
||||
@@ -80,9 +76,9 @@ export async function getStream({ id, s, e, imdbId }) {
|
||||
|
||||
---
|
||||
|
||||
### Step 2: Register in `src/config.js`
|
||||
### 2. Register in `src/config.js`
|
||||
|
||||
Add your provider configuration to the `SOURCES` array in `src/config.js`:
|
||||
Add the source configuration:
|
||||
|
||||
```javascript
|
||||
{
|
||||
@@ -99,41 +95,36 @@ Add your provider configuration to the `SOURCES` array in `src/config.js`:
|
||||
}
|
||||
```
|
||||
|
||||
#### 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.
|
||||
**Key Fields:**
|
||||
- `key`: Lowercase identifier without spaces (e.g. `mysource`).
|
||||
- `label`: Clean display label for client UIs.
|
||||
- `proxyParam`: Unique 2-to-4 character query flag for the HLS proxy.
|
||||
- `timeout`: Maximum execution budget in ms (typically 8,000–15,000).
|
||||
- `jitter`: Random delay ceiling in ms (typically 300–500).
|
||||
|
||||
---
|
||||
|
||||
### Step 3: Local Testing
|
||||
### 3. Local Testing
|
||||
|
||||
Run your scraper against known TMDB titles using the test runner:
|
||||
Run your scraper against known TMDB titles:
|
||||
|
||||
```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'`.
|
||||
1. A valid URL is returned.
|
||||
2. The format 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.
|
||||
4. An invalid ID throws a clean error without crashing.
|
||||
|
||||
---
|
||||
|
||||
## Contribution Rules & Checklist
|
||||
|
||||
Before submitting a Pull Request to the GitLab repository:
|
||||
## Contribution Checklist
|
||||
|
||||
- [ ] 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(...)`).
|
||||
- [ ] No untrusted `eval()` or un-sanitized script execution.
|
||||
- [ ] Upstream stream candidate URLs are verified for playback.
|
||||
- [ ] Descriptive errors are thrown with `throw new Error(...)`.
|
||||
|
||||
Reference in New Issue
Block a user