mirror of
https://gitlab.com/vyla-entertainment/documentation.git
synced 2026-11-17 07:57:23 -05:00
huge rewrite
This commit is contained in:
@@ -1,97 +1,162 @@
|
||||
# SDK quickstart
|
||||
# Vyla SDK Quickstart
|
||||
|
||||
<p class="page-description">Install Vyla SDK, resolve a source, and build a safe server-side integration.</p>
|
||||
<p class="page-description">Get up and running with the Vyla SDK in under five minutes. Learn how to resolve movies, television episodes, subtitles, and downloads.</p>
|
||||
|
||||
## Before you start
|
||||
## Prerequisites
|
||||
|
||||
Vyla SDK is for **server-side Node.js**. It contains provider integrations and makes outbound requests from the process where you install it. Do not import it into a browser bundle or expose provider results, credentials, or internal source keys directly to untrusted clients.
|
||||
Ensure you have Node.js 20+ installed on your system. Create a new Node.js project:
|
||||
|
||||
You need Node.js 18 or later and, for sources that resolve title metadata, a TMDB API key.
|
||||
|
||||
## Install and initialize
|
||||
|
||||
:::code-group
|
||||
```bash [npm]
|
||||
npm install @vyla-entertainment/sdk
|
||||
```bash
|
||||
mkdir vyla-demo && cd vyla-demo
|
||||
npm init -y
|
||||
npm pkg set type="module"
|
||||
npm install @vyla-entertainment/sdk dotenv
|
||||
```
|
||||
```bash [pnpm]
|
||||
pnpm install @vyla-entertainment/sdk
|
||||
|
||||
Create a `.env` file containing your TMDB API key:
|
||||
|
||||
```ini
|
||||
TMDB_API_KEY=your_tmdb_api_key_here
|
||||
```
|
||||
```bash [yarn]
|
||||
yarn add @vyla-entertainment/sdk
|
||||
```
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## 1. Initializing the SDK
|
||||
|
||||
Create an `index.js` file and initialize the `VylaSDK` class:
|
||||
|
||||
```javascript
|
||||
import VylaSDK from "@vyla-entertainment/sdk";
|
||||
import 'dotenv/config';
|
||||
import VylaSDK from '@vyla-entertainment/sdk';
|
||||
|
||||
const vyla = new VylaSDK({
|
||||
tmdbApiKey: process.env.TMDB_API_KEY,
|
||||
penguManifest: process.env.PENGU_MANIFEST
|
||||
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:
|
||||
|
||||
```javascript
|
||||
const sourceKey = 'vidlink';
|
||||
const tmdbId = 155;
|
||||
|
||||
try {
|
||||
const result = await sdk.getStream(sourceKey, tmdbId);
|
||||
console.log('Stream Candidate URL:', result.url);
|
||||
console.log('Container Type:', result.type);
|
||||
console.log('Video Quality:', result.quality);
|
||||
console.log('Upstream Server:', result.server);
|
||||
} 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:
|
||||
|
||||
```javascript
|
||||
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. Multi-Source Concurrent Resolution with Fallbacks
|
||||
|
||||
In production, you should query multiple active providers concurrently and select the fastest viable stream:
|
||||
|
||||
```javascript
|
||||
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)
|
||||
)
|
||||
]);
|
||||
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);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Fetching Subtitles and Downloads
|
||||
|
||||
Subtitles and direct download links can be fetched in parallel:
|
||||
|
||||
```javascript
|
||||
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 Packages ---');
|
||||
downloads.forEach((dl) => {
|
||||
console.log(`[${dl.quality}] Size: ${dl.size ? (dl.size / (1024**3)).toFixed(2) + ' GB' : 'Unknown'} -> ${dl.url}`);
|
||||
});
|
||||
```
|
||||
|
||||
:::callout-warning
|
||||
Keep `TMDB_API_KEY` and any deployment configuration in server-side environment variables. Never commit them or send them to a client.
|
||||
:::
|
||||
---
|
||||
|
||||
## Resolve a movie
|
||||
## 6. Live Source Health Probing
|
||||
|
||||
First inspect active providers. Provider availability changes over time, so select a key from the running configuration instead of hard-coding a placeholder.
|
||||
To check which providers are operational in your network environment:
|
||||
|
||||
```javascript
|
||||
const providers = vyla.getSources(true);
|
||||
console.table(providers.map(({ key, label }) => ({ key, label })));
|
||||
const healthReport = await sdk.probeAllSources();
|
||||
|
||||
const provider = providers[0];
|
||||
const result = await vyla.getStream(provider.key, 155);
|
||||
const candidates = result.allUrls ?? [result];
|
||||
|
||||
console.log(candidates.map(({ url, type, quality }) => ({ url, type, quality })));
|
||||
for (const [key, status] of Object.entries(healthReport)) {
|
||||
const icon = status.ok ? 'OK' : 'FAIL';
|
||||
console.log(`[${icon}] ${key}: ${status.ok ? status.ms + 'ms' : 'offline'}`);
|
||||
}
|
||||
```
|
||||
|
||||
`155` is a TMDB movie ID. For an episode, include season and episode:
|
||||
---
|
||||
|
||||
```javascript
|
||||
const result = await vyla.getStream(provider.key, 1396, 1, 1);
|
||||
```
|
||||
## Next Steps
|
||||
|
||||
## Read manga
|
||||
|
||||
Search manga titles, retrieve chapter listings, and resolve reader-ready page images directly:
|
||||
|
||||
```javascript
|
||||
const search = await vyla.searchManga("Steel Ball Run", 1, 5);
|
||||
const firstResult = search.results[0];
|
||||
|
||||
const manga = await vyla.getManga(firstResult.id);
|
||||
const firstChapter = manga.chapters[manga.chapters.length - 1];
|
||||
|
||||
const chapterData = await vyla.getMangaChapter(manga.id, firstChapter.id);
|
||||
console.log(chapterData.pages.map(p => p.url));
|
||||
```
|
||||
|
||||
## Make it resilient
|
||||
|
||||
Provider results are inherently variable: a source can fail, time out, return more than one candidate, or be temporarily disabled. In production:
|
||||
|
||||
1. Probe sources or maintain a recent availability signal before choosing one.
|
||||
2. Give every provider call a request deadline in your application.
|
||||
3. Treat `allUrls` as fallback candidates, not a guarantee that every URL will play.
|
||||
4. Return only the fields your client needs and validate requests at your own API boundary.
|
||||
5. Cache and rate-limit at your boundary to avoid repeatedly triggering upstream work.
|
||||
|
||||
```javascript
|
||||
const health = await vyla.probeAllSources();
|
||||
const usableKey = Object.entries(health).find(([, result]) => result.ok)?.[0];
|
||||
|
||||
if (!usableKey) throw new Error("No providers are currently available");
|
||||
|
||||
const stream = await vyla.getStream(usableKey, 155);
|
||||
```
|
||||
|
||||
## Next steps
|
||||
|
||||
- Read the complete [SDK reference](/sdk) for methods and return shapes.
|
||||
- Learn provider flags, timeout behavior, and source keys in [Providers](/concepts/providers).
|
||||
- Choose [Stream API](/stream-api/overview) only when an SSE HTTP interface better fits your client architecture.
|
||||
- Consult the [Complete API Reference](/sdk/vyla-sdk/reference) for exhaustive class and method parameters.
|
||||
- Learn how to integrate manga reading with the [Manga SDK Guide](/sdk/vyla-sdk/manga).
|
||||
- Deploy an HTTP/SSE bridge with the [Stream API Guide](/stream-api/overview).
|
||||
|
||||
Reference in New Issue
Block a user