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

5.7 KiB

Vyla SDK Quickstart

Get up and running with the Vyla SDK in under five minutes. Learn how to resolve movies, television episodes, embed URLs, subtitles, and downloads.

Prerequisites

Ensure you have Node.js 20+ installed on your system. Create a new Node.js project:

mkdir vyla-demo && cd vyla-demo
npm init -y
npm pkg set type="module"
npm install @vyla-entertainment/sdk dotenv

Create a .env file containing your TMDB API key:

TMDB_API_KEY=your_tmdb_api_key_here

1. Initializing the SDK

Create an index.js file and initialize the VylaSDK class:

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

const sdk = new VylaSDK({
  tmdbApiKey: process.env.TMDB_API_KEY
});

console.log('Vyla SDK initialized successfully!');

2. Resolving a Movie Stream

To resolve a movie stream, supply the source key and the numeric TMDB movie ID:

const sourceKey = 'vidlink';
const tmdbId = 155;

try {
  const result = await sdk.getStream(sourceKey, tmdbId);
  console.log('Stream Candidate URL:', result.url);
  console.log('All Candidates:', result.allUrls.length);
  console.log('Headers:', result.headers);
} catch (error) {
  console.error(`Failed to resolve ${sourceKey}:`, error.message);
}

3. Resolving a Television Episode

For TV series, provide the TMDB show ID, season number, and episode number:

const showId = 1396;
const season = 1;
const episode = 1;

try {
  const tvStream = await sdk.getStream('vixsrc', showId, season, episode);
  console.log('TV Episode Stream:', tvStream.url);
} catch (error) {
  console.error('TV stream resolution failed:', error.message);
}

4. Filtering Dedicated vs. Aggregator Sources

Sources in config.js mark single-host/dedicated providers with dedicated: true, while multi-provider aggregators omit it:

import { DEDICATED_SOURCES, AGGREGATOR_SOURCES } from '@vyla-entertainment/sdk/src/config.js';

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

console.log(`Dedicated: ${DEDICATED_SOURCES.length}, Aggregators: ${AGGREGATOR_SOURCES.length}`);
console.log(`Active Dedicated: ${dedicatedActive.length}, Active Aggregators: ${aggregatorActive.length}`);

5. Multi-Source Concurrent Resolution with Fallbacks

In production, you should query multiple active providers concurrently and select the fastest viable stream:

async function resolveFastestStream(tmdbId, s = null, e = null) {
  const activeSources = sdk.getSources(true);

  const queryPromises = activeSources.map(async (cfg) => {
    try {
      const stream = await Promise.race([
        sdk.getStream(cfg.key, tmdbId, s, e),
        new Promise((_, reject) =>
          setTimeout(() => reject(new Error('Timeout')), cfg.timeout || 10000)
        )
      ]);
      if (!stream?.url) return null;
      return { source: cfg.key, label: cfg.label, stream };
    } catch {
      return null;
    }
  });

  const results = await Promise.all(queryPromises);
  const successful = results.filter(Boolean);

  if (successful.length === 0) {
    throw new Error('No viable streaming sources resolved.');
  }

  console.log(`Resolved ${successful.length} valid streams!`);
  return successful;
}

const sources = await resolveFastestStream(155);
console.log('Primary Source:', sources[0].label, sources[0].stream.url);

6. Using Embed Player Configurations

Use EMBEDS or EMBED_MAP from embed_config.js to build iframe player URLs for movies and TV episodes, and filter by ads === false when you only want ad-free embeds:

import EMBEDS, { EMBED_MAP } from '@vyla-entertainment/sdk/src/embed_config.js';

const adFreeEmbeds = EMBEDS.filter(embed => embed.ads === false);
console.log('Ad-free embeds:', adFreeEmbeds.map(e => e.label).join(', '));

function buildEmbedUrl(key, tmdbId, season = null, episode = null) {
  const cfg = EMBED_MAP[key];
  if (!cfg) return null;

  if (season != null && episode != null) {
    return cfg.tv
      .replace('{id}', encodeURIComponent(tmdbId))
      .replace('{s}', encodeURIComponent(season))
      .replace('{e}', encodeURIComponent(episode));
  }

  return cfg.movie.replace('{id}', encodeURIComponent(tmdbId));
}

console.log('Movie Embed:', buildEmbedUrl('cinezo', 155));
console.log('TV Embed:', buildEmbedUrl('cinesrc', 1396, 1, 1));

7. Fetching Subtitles and Downloads

Subtitles and direct MP4 download links can be fetched in parallel:

const [subtitles, downloads] = await Promise.all([
  sdk.getSubtitles(155),
  sdk.getDownloads(155)
]);

console.log('--- Subtitle Tracks ---');
subtitles.slice(0, 5).forEach((sub) => {
  console.log(`[${sub.type.toUpperCase()}] ${sub.label}: ${sub.file}`);
});

console.log('--- Download Links ---');
downloads.forEach((dl) => {
  console.log(`[${dl.source}] ${dl.label} -> ${dl.url}`);
});

8. Live Source Health Probing

To check which providers are operational in your network environment:

const healthReport = await sdk.probeAllSources();

for (const [key, status] of Object.entries(healthReport)) {
  const icon = status.ok ? 'OK' : 'FAIL';
  console.log(`[${icon}] ${key}: ${status.ok ? `${status.ms}ms (movie=${status.movie}, tv=${status.tv})` : 'offline'}`);
}

Next Steps