documentation/sdk/vyla-sdk/contributing.md

Contributing to Sources

Help maintain, fix broken scrapers, and add new video or download providers to the Vyla SDK.

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:

git clone https://gitlab.com/vyla-entertainment/sdk.git
cd vyla-sdk

2. Install dependencies

Ensure you are running Node.js 18 or newer:

npm install

3. Environment configuration

Copy the example environment file and add your TMDB API key:

cp .env.example .env

Open .env and set your key:

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:

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:

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:

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:

{
    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:

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.