mirror of
https://gitlab.com/vyla-entertainment/documentation.git
synced 2026-11-17 07:57:23 -05:00
made sdk docs up to date
This commit is contained in:
@@ -1,30 +1,35 @@
|
||||
# Contributing a Source Provider
|
||||
|
||||
<p class="page-description">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 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/`. We welcome contributions that expand coverage for movies and television series.
|
||||
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 single function:
|
||||
Every provider module is an ES Module exporting a `getStream` function:
|
||||
|
||||
```typescript
|
||||
export async function getStream(args: StreamArgs): Promise<StreamResult | { allUrls: StreamResult[] }>
|
||||
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.
|
||||
- `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.
|
||||
- `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`.
|
||||
|
||||
---
|
||||
|
||||
@@ -34,43 +39,57 @@ export async function getStream(args: StreamArgs): Promise<StreamResult | { allU
|
||||
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': '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
|
||||
'User-Agent': USER_AGENT,
|
||||
Referer: `${BASE_URL}/`,
|
||||
Origin: BASE_URL
|
||||
};
|
||||
|
||||
export async function getStream({ id, s, e, imdbId }) {
|
||||
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}`;
|
||||
|
||||
const response = await fetch(endpoint, {
|
||||
headers: DEFAULT_HEADERS
|
||||
});
|
||||
try {
|
||||
const response = await fetch(endpoint, {
|
||||
headers: DEFAULT_HEADERS,
|
||||
signal: AbortSignal.timeout(config?.timeout || 15000)
|
||||
});
|
||||
|
||||
if (!response.ok) {
|
||||
throw new Error(`Upstream returned HTTP ${response.status}`);
|
||||
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;
|
||||
}
|
||||
|
||||
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'
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
@@ -78,7 +97,7 @@ export async function getStream({ id, s, e, imdbId }) {
|
||||
|
||||
### 2. Register in `src/config.js`
|
||||
|
||||
Add the source configuration:
|
||||
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
|
||||
{
|
||||
@@ -86,25 +105,54 @@ Add the source configuration:
|
||||
label: 'My Source',
|
||||
sourceFile: 'mysource',
|
||||
proxyParam: 'ms',
|
||||
timeout: 12000,
|
||||
jitter: 400,
|
||||
retries: 1,
|
||||
multiUrl: false,
|
||||
skipProxy: false,
|
||||
skipVerify: false
|
||||
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 8,000–15,000).
|
||||
- `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. Local Testing
|
||||
### 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:
|
||||
|
||||
@@ -114,10 +162,10 @@ node test/index.js mysource 1396 1 1
|
||||
```
|
||||
|
||||
Verify that:
|
||||
1. A valid URL is returned.
|
||||
2. The format is correctly identified as `hls` or `mp4`.
|
||||
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. An invalid ID throws a clean error without crashing.
|
||||
4. Invalid IDs or network timeouts return `null` cleanly without throwing uncaught exceptions.
|
||||
|
||||
---
|
||||
|
||||
@@ -127,4 +175,4 @@ Verify that:
|
||||
- [ ] No hardcoded personal API keys or credentials.
|
||||
- [ ] No untrusted `eval()` or un-sanitized script execution.
|
||||
- [ ] Upstream stream candidate URLs are verified for playback.
|
||||
- [ ] Descriptive errors are thrown with `throw new Error(...)`.
|
||||
- [ ] Timeouts (`AbortSignal.timeout`) are applied to all network requests.
|
||||
Reference in New Issue
Block a user