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

8.8 KiB

Vyla SDK API Reference

Technical reference for `@vyla-entertainment/sdk`: classes, methods, config exports, parameters, and TypeScript definitions.

Class: VylaSDK

The primary entry point for media scraping, subtitle retrieval, downloads, and manga discovery.

import VylaSDK from '@vyla-entertainment/sdk';

Constructor

constructor(options?: VylaSDKOptions)

Parameters:

  • options.tmdbApiKey (string, optional) — TMDB v3 API Key for metadata lookups.
  • options.penguManifest (string, optional) — Custom Stremio manifest URL for the Pengu provider source.
const sdk = new VylaSDK({
  tmdbApiKey: '9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d'
});

getSources(excludeDisabled?)

getSources(excludeDisabled?: boolean): SourceConfig[]

Returns registered provider scraper configurations from SOURCES.

Parameters:

  • excludeDisabled (boolean, optional) — When true, filters out scrapers with disabled: true. Default: false.

Returns: Array of SourceConfig objects.

const activeSources = sdk.getSources(true);
const dedicatedActive = activeSources.filter(s => s.dedicated);
const aggregatorActive = activeSources.filter(s => !s.dedicated);

getStream(key, id, s?, e?, clientIP?)

async getStream(
    key: string,
    id: string | number,
    s?: number | null,
    e?: number | null,
    clientIP?: string | null
): Promise<StreamResponse | null>

Executes a provider scraper module to resolve candidate stream URLs. Any subtitles field on the raw source response is stripped; use getSubtitles() for subtitle tracks.

Parameters:

  • key (string, required) — Provider key (e.g. 'vidlink', 'vixsrc').
  • id (string | number, required) — TMDB ID or IMDb ID.
  • s (number, optional) — Season number (for TV series). Default: null.
  • e (number, optional) — Episode number (for TV series). Default: null.
  • clientIP (string, optional) — Client IP address passed for upstream geo-token generation. Default: null.

Returns: A Promise resolving to a StreamResponse object or null.

const movieStream = await sdk.getStream('vidlink', 155);
const episodeStream = await sdk.getStream('vixsrc', 1396, 1, 1);

getSubtitles(id, s?, e?)

async getSubtitles(
    id: string | number,
    s?: number | null,
    e?: number | null
): Promise<SubtitleResult[]>

Retrieves subtitle tracks from configured subtitle providers (sub.vdrk.site and opensubtitles-v3.strem.io) for a movie or TV episode.

Parameters:

  • id (string | number, required) — TMDB media ID.
  • s (number, optional) — Season number. Default: null.
  • e (number, optional) — Episode number. Default: null.

Returns: Array of SubtitleResult objects.


getDownloads(id, s?, e?)

async getDownloads(
    id: string | number,
    s?: number | null,
    e?: number | null
): Promise<DownloadResult[]>

Resolves direct .mp4 download URLs from active sources configured with skipProxy: true, deduplicated by URL.

Returns: Array of DownloadResult objects.


probeSource(key)

async probeSource(key: string): Promise<ProbeResult>

Probes a single provider against a test movie (936075) and TV episode (37854 S01E01) to check responsiveness.

Parameters:

  • key (string, required) — Provider key to probe.

Returns: { ok: boolean, movie: boolean, tv: boolean, ms: number | null }.


probeAllSources()

async probeAllSources(): Promise<ProbeAllResult>

Concurrently probes all active (non-disabled) sources and returns a health map keyed by source key.


Manga Methods

searchManga(query, page?, perPage?)

async searchManga(query: string, page?: number, perPage?: number): Promise<MangaSearchResult>

Queries the manga catalog via atsu.moe using Chrome 131 TLS fingerprinting.

getManga(id)

async getManga(id: string): Promise<MangaDetails>

Retrieves full manga details, authors, genres, tags, and chapter list.

getMangaChapter(mangaId, chapterId)

async getMangaChapter(mangaId: string, chapterId: string): Promise<MangaChapterPages>

Resolves ordered image URLs and dimensions for all pages in a chapter.


Config & Embed Exports

src/config.js

import SOURCES, {
  SOURCE_MAP,
  DEDICATED_SOURCES,
  AGGREGATOR_SOURCES,
  HEALTH_PROBE_ID
} from '@vyla-entertainment/sdk/src/config.js';
  • SOURCES (default) — Full array of SourceConfig objects.
  • SOURCE_MAP — Lookup object mapping source.key to its SourceConfig.
  • DEDICATED_SOURCES — Filtered array of entries where dedicated is truthy.
  • AGGREGATOR_SOURCES — Filtered array of entries where dedicated is falsy/omitted.
  • HEALTH_PROBE_ID — Default TMDB probe ID ('155').

src/embed_config.js

import EMBEDS, { EMBED_MAP } from '@vyla-entertainment/sdk/src/embed_config.js';
  • EMBEDS (default) — Array of EmbedConfig objects containing movie and TV URL templates ({id}, {s}, {e}).
  • EMBED_MAP — Lookup object mapping embed.key to its EmbedConfig.

TypeScript Interfaces

Interface: VylaSDKOptions

export interface VylaSDKOptions {
    tmdbApiKey?: string | null;
    penguManifest?: string | null;
}

Interface: SourceConfig

export interface SourceConfig {
    key: string;
    label: string;
    sourceFile: string;
    proxyParam: string;
    timeout: number;
    jitter: number;
    retries: number;
    multiUrl?: boolean;
    dedicated?: boolean;
    skipProxy?: boolean;
    skipVerify?: boolean;
    verifyHeaders?: Record<string, string>;
    disabled?: boolean;
    sourcesTimeout?: number;
    cdnHeaders?: {
        pattern: RegExp;
        headers: {
            Referer?: string;
            Origin?: string;
            [key: string]: string | undefined;
        };
    }[];
}

Interface: EmbedConfig

export interface EmbedConfig {
    key: string;
    label: string;
    movie: string;
    tv: string;
    ads?: boolean;
}

Interface: StreamCandidate & StreamResponse

export interface StreamCandidate {
    url: string;
    headers?: Record<string, string>;
    server: string;
    quality: string;
    type: "mp4" | "hls" | "dash" | "mkv" | string;
    label?: string;
    skipProxy?: boolean;
    skipVerify?: boolean;
    audio?: string;
}

export interface StreamResponse {
    url: string;
    headers?: Record<string, string>;
    server?: string;
    quality?: string;
    type?: string;
    allUrls: StreamCandidate[];
}

Interface: SubtitleResult

export interface SubtitleResult {
    label: string;
    file: string;
    type: "vtt" | "srt";
    source: "v1" | "v2" | "opensubtitles" | "febbox" | string;
}

Interface: DownloadResult

export interface DownloadResult {
    source: string;
    label: string;
    url: string;
}

Interface: ProbeResult & ProbeAllResult

export interface ProbeResult {
    ok: boolean;
    movie?: boolean;
    tv?: boolean;
    ms: number | null;
}

export type ProbeAllResult = Record<string, ProbeResult>;

Interfaces: Manga

export interface MangaSearchItem {
    id: string;
    title: string;
    englishTitle: string | null;
    authors: string[];
    type: string;
    medium: string;
    status: string;
    year: number | null;
    rating: number | null;
    popularity: number | null;
    poster: string | null;
    posterSmall: string | null;
    posterMedium: string | null;
}

export interface MangaSearchResult {
    page: number;
    total: number;
    results: MangaSearchItem[];
}

export interface MangaChapterSummary {
    id: string;
    number: number;
    title: string;
    pageCount: number;
    createdAt: string | null;
}

export interface MangaDetails {
    id: string;
    title: string;
    englishTitle: string | null;
    synopsis: string | null;
    status: string;
    type: string;
    medium: string;
    rating: number | null;
    views: number | null;
    authors: string[];
    genres: string[];
    tags: string[];
    poster: string | null;
    totalChapters: number;
    chapters: MangaChapterSummary[];
}

export interface MangaPage {
    number: number;
    url: string | null;
    width: number;
    height: number;
    aspectRatio: number;
}

export interface MangaChapterPages {
    id: string;
    number: number;
    title: string;
    scanlatorId: string | null;
    pages: MangaPage[];
}