This commit is contained in:
2026-10-11 11:06:58 -07:00
parent ad9a41036f
commit f28898089e
25 changed files with 3320 additions and 453 deletions

View File

@@ -0,0 +1,170 @@
# Contributing to Sources
<p class="page-description">Help maintain, fix broken scrapers, and add new video or download providers to the Vyla SDK.</p>
Third-party streaming and scraping endpoints frequently change their DOM layout, API endpoints, tokens, and CDN protections. Community contributions are vital to keeping providers operational.
---
## Getting Started
### 1. Clone the repository
Clone the SDK repository to your local machine:
```bash
git clone https://gitlab.com/vyla-entertainment/vyla-sdk.git
cd vyla-sdk
```
### 2. Install dependencies
Ensure you are running Node.js 18 or newer:
```bash
npm install
```
### 3. Environment configuration
Copy the example environment file and add your TMDB API key:
```bash
cp .env.example .env
```
Open `.env` and set your key:
```ini
TMDB_API_KEY=your_actual_tmdb_api_key_here
```
---
## Project Structure
- `src/sources/`: Scraper implementations for each provider.
- `src/config.js`: Source registry containing timeouts, retries, headers, and proxy flags.
- `src/downloads/downloads.js`: Downloader resolver extracting direct MP4 streams.
- `src/subtitles.js`: Subtitle mirror aggregation endpoints.
- `test/index.js`: Test runner for testing streams, subtitles, and downloads.
---
## Testing Sources
Testing is driven by `test/index.js`. Open the file and update `CONFIG` to target the source you are fixing or adding:
```javascript
const CONFIG = {
DEBUG: true,
MOVIE_ID: "936075",
TV_ID: "37854",
TV_SEASON: "1",
TV_EPISODE: "1",
STREAM_SOURCE: "vidrock",
TEST_SUBTITLE: false,
TEST_DOWNLOAD: false,
TEST_MOVIE: true,
TEST_TV: true,
EXTRA_SDK_PARAMS: {}
};
```
Run the test suite:
```bash
npm test
```
When `DEBUG: true` is enabled, all outbound fetch calls, headers, request payloads, and raw responses will be logged to your terminal and saved to `test/debug-output.json`.
---
## Fixing or Adding a Source
### 1. Source Resolver
All source files are located in `src/sources/`. Each module must export an asynchronous `getStream` function:
```javascript
export async function getStream({ id, s, e, clientIP, audio, sdk, config }) {
const isTv = Boolean(s && e);
const mediaId = id;
const streamUrl = "https://example-cdn.com/stream/playlist.m3u8";
return {
url: streamUrl,
quality: "auto",
isM3U8: true,
headers: {
Referer: "https://example-provider.to/",
Origin: "https://example-provider.to"
},
allUrls: [
{
url: streamUrl,
quality: "1080p",
isM3U8: true
}
]
};
}
```
### 2. Registering in `src/config.js`
Add or update the source entry inside the `SOURCES` array in `src/config.js`:
```javascript
{
key: 'mysource',
label: 'MySource',
sourceFile: 'mysource',
proxyParam: 'ms',
timeout: 25000,
jitter: 500,
retries: 2,
multiUrl: true,
skipProxy: true,
cdnHeaders: [{
pattern: /cdn\.mysource\.to/i,
headers: {
Referer: 'https://mysource.to/',
Origin: 'https://mysource.to',
},
}],
}
```
- `skipProxy`: Set to `true` if the stream plays directly in client players without server-side proxying.
- `multiUrl`: Set to `true` if the scraper provides multiple resolutions or fallback mirrors.
- `cdnHeaders`: Include custom headers required by the upstream CDN to avoid HTTP 403 Forbidden responses.
---
## Download Providers
Downloads are handled automatically by `src/downloads/downloads.js`. The downloader queries active sources that have `skipProxy: true` enabled and inspects returned streams:
- URLs ending in `.mp4` or containing `.mp4` queries are automatically extracted.
- `.m3u8` streams are filtered out because they are HLS segment playlists rather than direct file downloads.
- If you are implementing a provider that supplies raw MP4 video files, return them in `allUrls` or `url` with `skipProxy: true` in `src/config.js`.
To verify download resolution in `test/index.js`, toggle:
```javascript
TEST_DOWNLOAD: true
```
---
## Submitting Pull Requests
1. Verify that your updated source passes tests for both movies (`TEST_MOVIE: true`) and TV shows (`TEST_TV: true`).
2. Ensure you have not committed your `.env` file or personal TMDB API keys.
3. Push your branch and open a Merge Request on GitLab.

View File

@@ -19,7 +19,7 @@ The SDK can be used independently of the self-hosted Stream API. If you prefer t
- **Automated Anime Sub/Dub Routing**: Automatically configures audio track requirements (`sub` vs `dub`) based on provider naming conventions.
- **Multi-Source Subtitle Aggregation**: Merges subtitle tracks from multiple redundant subtitle mirrors into a unified VTT/SRT format.
- **Metadata Fallbacks**: Automatically maps TMDB IDs to external IDs (such as IMDB and AniList) for smooth stream lookups.
- **Self-Contained**: No need to deploy a separate API server — all streaming functionality runs within your existing Node.js application.
- **Self-Contained**: No need to deploy a separate API server - all streaming functionality runs within your existing Node.js application.
---
@@ -82,8 +82,8 @@ const geoStream = await sdk.getStream("sourcename", "155", null, null, "203.0.11
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `key` | `string` | **Yes** | — | Unique key identifier for the provider (e.g. `"sourcename"`). |
| `id` | `string` | **Yes** | — | TMDB media ID (e.g., `"155"`). |
| `key` | `string` | **Yes** | - | Unique key identifier for the provider (e.g. `"sourcename"`). |
| `id` | `string` | **Yes** | - | TMDB media ID (e.g., `"155"`). |
| `s` | `string \| number` | **No** | `null` | Season number (required for TV shows). |
| `e` | `string \| number` | **No** | `null` | Episode number (required for TV shows). |
| `clientIP` | `string` | **No** | `null` | End-user IP address forwarded for geo-restricted scrapers. |
@@ -127,7 +127,7 @@ const tvSubs = await sdk.getSubtitles("1399", 1, 1);
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `id` | `string` | **Yes** | — | TMDB media ID. |
| `id` | `string` | **Yes** | - | TMDB media ID. |
| `s` | `string \| number` | **No** | `null` | Season number (required for TV shows). |
| `e` | `string \| number` | **No** | `null` | Episode number (required for TV shows). |