mirror of
https://gitlab.com/vyla-entertainment/documentation.git
synced 2026-11-16 15:37:23 -05:00
rewrite
This commit is contained in:
170
sdk/vyla-sdk/contributing.md
Normal file
170
sdk/vyla-sdk/contributing.md
Normal 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.
|
||||
@@ -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). |
|
||||
|
||||
|
||||
Reference in New Issue
Block a user