Files
documentation/sdk/vyla-sdk/contributing.md

5.5 KiB
Raw Blame History

Contributing a Source Provider

Technical guide for authoring, testing, and registering a new video scraping resolver or embed entry in the Vyla SDK.

Overview

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 getStream function:

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.
  • 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.


Implementation Steps

1. Create the Scraper Module

Create a new file in src/sources/<source_name>.js:

import { USER_AGENT } from '../utils/helpers.js';

const BASE_URL = 'https://provider-domain.example.com';

const DEFAULT_HEADERS = {
  'User-Agent': USER_AGENT,
  Referer: `${BASE_URL}/`,
  Origin: BASE_URL
};

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}`;

  try {
    const response = await fetch(endpoint, {
      headers: DEFAULT_HEADERS,
      signal: AbortSignal.timeout(config?.timeout || 15000)
    });

    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;
  }
}

2. Register in src/config.js

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:

{
    key: 'mysource',
    label: 'My Source',
    sourceFile: 'mysource',
    proxyParam: 'ms',
    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 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. 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:

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

node test/index.js mysource 155
node test/index.js mysource 1396 1 1

Verify that:

  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. Invalid IDs or network timeouts return null cleanly without throwing uncaught exceptions.

Contribution Checklist

  • Code is formatted with clean ES Module syntax.
  • No hardcoded personal API keys or credentials.
  • No untrusted eval() or un-sanitized script execution.
  • Upstream stream candidate URLs are verified for playback.
  • Timeouts (AbortSignal.timeout) are applied to all network requests.