documentation/sdk/vyla-sdk/reference.md

Vyla SDK API Reference

Complete technical reference for the `@vyla-entertainment/sdk` package: classes, methods, parameters, interfaces, and TypeScript definitions.

Class: VylaSDK

The primary entry point of the package. Instantiated to manage scraper execution, health probing, subtitle retrieval, downloads, and manga discovery.

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

---

Constructor

constructor(options?: VylaSDKOptions)

Creates a new instance of VylaSDK.

Parameters

Parameter	Type	Required	Default	Description
options.tmdbApiKey	string	Optional	null	Your TMDB v3 API Key. Highly recommended; required by sources that query metadata by IMDb ID or episode name.
options.penguManifest	any	Optional	null	Custom manifest definition for the Pengu provider source.

Example

const sdk = new VylaSDK({
  tmdbApiKey: '9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d'
});

---

getSources(excludeDisabled?)

getSources(excludeDisabled?: boolean): SourceConfig[]

Returns the registered list of provider scraper configurations.

Parameters

Parameter	Type	Required	Default	Description
excludeDisabled	boolean	Optional	false	When true, filters out providers marked with disabled: true.

Returns

Array of SourceConfig objects.

Example

const activeSources = sdk.getSources(true);
console.log(`Available active providers: ${activeSources.map(s => s.key).join(', ')}`);

---

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

async getStream(
    key: string,
    id: string | number,
    s?: number | null,
    e?: number | null,
    clientIP?: string | null
): Promise<StreamResult | { allUrls: StreamResult[] }>

Executes the scraper module for a specified provider and resolves streaming candidate URLs.

Parameters

Parameter	Type	Required	Default	Description
key	string	Required	—	The source key identifier (e.g. 'vidlink', 'vixsrc').
id	string | number	Required	—	Numeric TMDB ID or string IMDb ID (for movies and TV shows).
s	number | null	Optional	null	Season number (required for TV episodes).
e	number | null	Optional	null	Episode number (required for TV episodes).
clientIP	string | null	Optional	null	Client IP address passed for upstream geo-token generation.

Returns

A Promise resolving to a StreamResult object, or { allUrls: StreamResult[] } if the source supports multi-URL extraction.

Throws

• Error('Source with key "..." not found') if the key does not exist.
• Error('Source module for key "..." not found') if the source module is disabled or failed to import.
• Upstream network errors or scraper extraction errors if the title cannot be found.

Example

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[]>

Discovers and parses all available subtitle tracks for a movie or TV episode.

Parameters

Parameter	Type	Required	Default	Description
id	string | number	Required	—	TMDB media identifier.
s	number | null	Optional	null	Season number (TV shows).
e	number | null	Optional	null	Episode number (TV shows).

Returns

A Promise resolving to an array of SubtitleResult objects.

---

getDownloads(id, s?, e?)

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

Resolves direct media download packages and torrent/debrid links.

Returns

A Promise resolving to an array of DownloadResult objects.

---

probeSource(key)

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

Sends a lightweight probe request against the designated source to measure responsiveness and availability.

Parameters

Parameter	Type	Required	Description
key	string	Required	The provider key to probe.

Returns

A Promise resolving to a ProbeResult object: { ok: boolean, ms: number | null }.

---

probeAllSources()

async probeAllSources(): Promise<ProbeAllResult>

Concurrently probes all active (non-disabled) sources and compiles a live health map.

Returns

A Promise resolving to a ProbeAllResult dictionary mapping source keys to their probe results.

---

Manga Methods

searchManga(query, page?, perPage?)

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

Queries the manga catalog via atsu.moe using Chrome 131 TLS fingerprinting. Returns paginated title listings.

getManga(id)

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

Retrieves full manga details including description, genres, author, status, and chapter list.

getMangaChapter(mangaId, chapterId)

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

Resolves ordered image URLs, dimensions, and aspect ratios for all pages in a given chapter.

---

TypeScript Interfaces

Interface: SourceConfig

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

Interface: StreamResult

export interface StreamResult {
    url: string;
    headers: {
        "User-Agent": string;
        Referer: string;
        Origin: string;
        [key: string]: string;
    };
    server: string;
    quality: string;
    type: "mp4" | "hls";
    skipVerify?: boolean;
    skipProxy?: boolean;
}

Interface: SubtitleResult

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

Interface: DownloadResult

export interface DownloadResult {
    url: string;
    quality: string;
    size: number | null;
    type: "mkv";
    active: boolean;
}

Interface: ProbeResult & ProbeAllResult

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

export type ProbeAllResult = Record<string, ProbeResult>;