mirror of
https://gitlab.com/vyla-entertainment/documentation.git
synced 2026-11-14 22:47:26 -05:00
171 lines
4.4 KiB
Markdown
171 lines
4.4 KiB
Markdown
# 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/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/manga/`: Manga catalog search and reader page resolvers.
|
|
- `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, downloads, and manga.
|
|
|
|
---
|
|
|
|
## 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. |