diff --git a/sdk/vyla-sdk/contributing.md b/sdk/vyla-sdk/contributing.md index 15c7836..258632a 100644 --- a/sdk/vyla-sdk/contributing.md +++ b/sdk/vyla-sdk/contributing.md @@ -1,30 +1,35 @@ # Contributing a Source Provider -
Technical guide for authoring, testing, and contributing a new video scraping resolver to the Vyla SDK.
+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/`. We welcome contributions that expand coverage for movies and television series. +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 single function: +Every provider module is an ES Module exporting a `getStream` function: ```typescript -export async function getStream(args: StreamArgs): PromiseThe official Node.js scraping and resolver library for movies, television series, subtitles, downloads, and manga.
+The official Node.js scraping and resolver library for movies, television series, embed configurations, subtitles, downloads, and manga.
## Overview
-`@vyla-entertainment/sdk` is the core media resolver engine for Vyla. It runs in Node.js (ES Modules) to query 60+ streaming scrapers, extract subtitles, find media downloads, and browse manga archives.
+`@vyla-entertainment/sdk` is the core media resolver engine for Vyla. It runs in Node.js (ES Modules) to query 65+ streaming scrapers, expose dedicated vs. aggregator source lists, provide pre-configured embed player URL templates, extract subtitles, find media downloads, and browse manga archives.
---
@@ -24,10 +24,12 @@ npm install @vyla-entertainment/sdk
## Capabilities
-- **Streaming**: Resolve direct MP4 and adaptive HLS (`.m3u8`) links with `getStream()`, `getSources()`, and `probeSource()`.
+- **Streaming**: Resolve direct MP4, MKV, DASH (`.mpd`), and adaptive HLS (`.m3u8`) links with `getStream()`, `getSources()`, and `probeSource()`.
+- **Source Categorization**: Separate single-host providers (`DEDICATED_SOURCES`) from multi-provider scrapers (`AGGREGATOR_SOURCES`) via `config.js`.
+- **Embed Configuration**: Pre-mapped movie and TV embed URL templates with `ads: false` tagging in `embed_config.js` (`EMBEDS` / `EMBED_MAP`).
- **Subtitles**: Fetch `.vtt` and `.srt` subtitle tracks with `getSubtitles()`.
-- **Downloads**: Find direct video files with file size metadata using `getDownloads()`.
-- **Manga**: Search titles, list chapters, and fetch page images with `searchManga()` and `getMangaChapter()`.
+- **Downloads**: Find direct `.mp4` download links using `getDownloads()`.
+- **Manga**: Search titles, list chapters, and fetch page images with `searchManga()`, `getManga()`, and `getMangaChapter()`.
---
@@ -35,21 +37,26 @@ npm install @vyla-entertainment/sdk
```javascript
import VylaSDK from '@vyla-entertainment/sdk';
+import EMBEDS from '@vyla-entertainment/sdk/src/embed_config.js';
const sdk = new VylaSDK({
tmdbApiKey: process.env.TMDB_API_KEY
});
const sources = sdk.getSources(true);
-console.log(`Active sources: ${sources.length}`);
+const dedicated = sources.filter(s => s.dedicated);
+console.log(`Active sources: ${sources.length} (${dedicated.length} dedicated)`);
try {
const stream = await sdk.getStream('vidlink', 155);
- console.log(stream.url, stream.type);
+ console.log(stream.url, stream.allUrls);
} catch (err) {
console.error(err.message);
}
+const adFreeEmbeds = EMBEDS.filter(e => e.ads === false);
+console.log(`Ad-free embeds: ${adFreeEmbeds.length}`);
+
const subtitles = await sdk.getSubtitles(155);
console.log(`Subtitles found: ${subtitles.length}`);
```
@@ -58,7 +65,7 @@ console.log(`Subtitles found: ${subtitles.length}`);
## Documentation Sections
-- **[Quickstart](quickstart.md)** — Step-by-step tutorial for movies, TV episodes, and error handling.
-- **[API Reference](reference.md)** — Complete methods, arguments, return shapes, and TypeScript types.
+- **[Quickstart](quickstart.md)** — Step-by-step tutorial for movies, TV episodes, embeds, and error handling.
+- **[API Reference](reference.md)** — Complete methods, config exports, return shapes, and TypeScript types.
- **[Manga Module](manga.md)** — Manga search, chapter indexes, and page loading.
-- **[Contributing Scrapers](contributing.md)** — How to write and test new source scrapers.
+- **[Contributing Scrapers](contributing.md)** — How to write and register new source and embed scrapers.
\ No newline at end of file
diff --git a/sdk/vyla-sdk/manga.md b/sdk/vyla-sdk/manga.md
index 2ada00b..ce9c923 100644
--- a/sdk/vyla-sdk/manga.md
+++ b/sdk/vyla-sdk/manga.md
@@ -34,8 +34,8 @@ const sdk = new VylaSDK();
const searchResult = await sdk.searchManga('Chainsaw Man', 1, 10);
console.log(`Total results: ${searchResult.total}`);
-searchResult.items.forEach((manga) => {
- console.log(`[ID: ${manga.id}] ${manga.title} - ${manga.latestChapter}`);
+searchResult.results.forEach((manga) => {
+ console.log(`[ID: ${manga.id}] ${manga.title} (${manga.status})`);
});
```
@@ -43,15 +43,22 @@ searchResult.items.forEach((manga) => {
```json
{
"page": 1,
- "perPage": 10,
"total": 42,
- "items": [
+ "results": [
{
"id": "chainsaw-man",
"title": "Chainsaw Man",
- "cover": "https://cdn.atsu.moe/covers/chainsaw-man.webp",
+ "englishTitle": "Chainsaw Man",
+ "authors": ["Tatsuki Fujimoto"],
+ "type": "Manga",
+ "medium": "MANGA",
"status": "Ongoing",
- "latestChapter": "Chapter 180"
+ "year": 2018,
+ "rating": 8.7,
+ "popularity": 120000,
+ "poster": "https://cdn.atsu.moe/static/covers/chainsaw-man.webp",
+ "posterSmall": "https://cdn.atsu.moe/static/covers/chainsaw-man-sm.webp",
+ "posterMedium": "https://cdn.atsu.moe/static/covers/chainsaw-man-md.webp"
}
]
}
@@ -61,18 +68,18 @@ searchResult.items.forEach((manga) => {
### 2. Fetching Manga Details & Chapters
-Retrieve full metadata, descriptions, genres, and the complete chapter index:
+Retrieve full metadata, synopsis, genres, and the complete chapter index:
```javascript
const mangaDetails = await sdk.getManga('chainsaw-man');
console.log('Title:', mangaDetails.title);
-console.log('Synopsis:', mangaDetails.description);
+console.log('Synopsis:', mangaDetails.synopsis);
console.log('Genres:', mangaDetails.genres.join(', '));
console.log('Available Chapters:', mangaDetails.chapters.length);
const latest = mangaDetails.chapters[0];
-console.log(`Latest Chapter: ${latest.chapterNumber} (ID: ${latest.id})`);
+console.log(`Latest Chapter: ${latest.number} (ID: ${latest.id})`);
```
---
@@ -85,23 +92,31 @@ To render the reader view, fetch the ordered page image assets for a specific ch
const mangaId = 'chainsaw-man';
const chapterId = 'chapter-1';
-const pages = await sdk.getMangaChapter(mangaId, chapterId);
+const chapter = await sdk.getMangaChapter(mangaId, chapterId);
-console.log(`Chapter contains ${pages.length} pages.`);
+console.log(`Chapter ${chapter.number} contains ${chapter.pages.length} pages.`);
-pages.forEach((page, index) => {
- console.log(`Page ${index + 1}: ${page.url} [${page.width}x${page.height}]`);
+chapter.pages.forEach((page) => {
+ console.log(`Page ${page.number}: ${page.url} [${page.width}x${page.height}]`);
});
```
-#### Page Object Structure
+#### Chapter Response Structure
```json
{
- "index": 1,
- "url": "https://cdn.atsu.moe/data/.../01.webp",
- "width": 1080,
- "height": 1600,
- "aspectRatio": 0.675
+ "id": "chapter-1",
+ "number": 1,
+ "title": "Dog & Chainsaw",
+ "scanlatorId": null,
+ "pages": [
+ {
+ "number": 1,
+ "url": "https://cdn.atsu.moe/static/data/.../01.webp",
+ "width": 1080,
+ "height": 1600,
+ "aspectRatio": 0.675
+ }
+ ]
}
```
@@ -113,4 +128,4 @@ When rendering manga pages in a frontend reader:
1. **Prevent Cumulative Layout Shift (CLS)**: Use the provided `aspectRatio` or `width`/`height` in CSS (`aspect-ratio: attr(width) / attr(height);`) to reserve vertical scroll space before each image finishes downloading.
2. **Preload Neighboring Pages**: Implement a 2-page lookahead preloader so viewers turning pages experience instantaneous transitions.
-3. **Session Cleanup**: In long-running background tasks, invoke `cleanup()` from the module when closing reader sessions to terminate idle TLS sockets.
+3. **Session Cleanup**: In long-running background tasks, invoke `cleanup()` from `src/manga/atsu.js` when closing reader sessions to terminate idle TLS sockets.
\ No newline at end of file
diff --git a/sdk/vyla-sdk/quickstart.md b/sdk/vyla-sdk/quickstart.md
index 924037d..8bd7bf3 100644
--- a/sdk/vyla-sdk/quickstart.md
+++ b/sdk/vyla-sdk/quickstart.md
@@ -1,6 +1,6 @@
# Vyla SDK Quickstart
-Get up and running with the Vyla SDK in under five minutes. Learn how to resolve movies, television episodes, subtitles, and downloads.
+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 @@ -49,9 +49,8 @@ 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); + console.log('All Candidates:', result.allUrls.length); + console.log('Headers:', result.headers); } catch (error) { console.error(`Failed to resolve ${sourceKey}:`, error.message); } @@ -78,7 +77,24 @@ try { --- -## 4. Multi-Source Concurrent Resolution with Fallbacks +## 4. Filtering Dedicated vs. Aggregator Sources + +Sources in `config.js` mark single-host/dedicated providers with `dedicated: true`, while multi-provider aggregators omit it: + +```javascript +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: @@ -90,10 +106,11 @@ async function resolveFastestStream(tmdbId, s = null, e = null) { try { const stream = await Promise.race([ sdk.getStream(cfg.key, tmdbId, s, e), - new Promise((_, reject) => + 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; @@ -117,9 +134,39 @@ console.log('Primary Source:', sources[0].label, sources[0].stream.url); --- -## 5. Fetching Subtitles and Downloads +## 6. Using Embed Player Configurations -Subtitles and direct download links can be fetched in parallel: +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: + +```javascript +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: ```javascript const [subtitles, downloads] = await Promise.all([ @@ -132,15 +179,15 @@ subtitles.slice(0, 5).forEach((sub) => { console.log(`[${sub.type.toUpperCase()}] ${sub.label}: ${sub.file}`); }); -console.log('--- Download Packages ---'); +console.log('--- Download Links ---'); downloads.forEach((dl) => { - console.log(`[${dl.quality}] Size: ${dl.size ? (dl.size / (1024**3)).toFixed(2) + ' GB' : 'Unknown'} -> ${dl.url}`); + console.log(`[${dl.source}] ${dl.label} -> ${dl.url}`); }); ``` --- -## 6. Live Source Health Probing +## 8. Live Source Health Probing To check which providers are operational in your network environment: @@ -149,7 +196,7 @@ 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' : 'offline'}`); + console.log(`[${icon}] ${key}: ${status.ok ? `${status.ms}ms (movie=${status.movie}, tv=${status.tv})` : 'offline'}`); } ``` @@ -157,6 +204,6 @@ for (const [key, status] of Object.entries(healthReport)) { ## Next Steps -- Consult the [Complete API Reference](reference.md) for exhaustive class and method parameters. +- Consult the [Complete API Reference](reference.md) for exhaustive class, config, and method parameters. - Learn how to integrate manga reading with the [Manga SDK Guide](manga.md). -- Deploy an HTTP/SSE bridge with the [Stream API Guide](../../stream-api/overview/index.md). +- Deploy an HTTP/SSE bridge with the [Stream API Guide](../../stream-api/overview) \ No newline at end of file diff --git a/sdk/vyla-sdk/reference.md b/sdk/vyla-sdk/reference.md index 9c411e1..3619066 100644 --- a/sdk/vyla-sdk/reference.md +++ b/sdk/vyla-sdk/reference.md @@ -1,6 +1,6 @@ # Vyla SDK API Reference -Technical reference for `@vyla-entertainment/sdk`: classes, methods, parameters, and TypeScript definitions.
+Technical reference for `@vyla-entertainment/sdk`: classes, methods, config exports, parameters, and TypeScript definitions.
## Class: `VylaSDK` @@ -20,7 +20,7 @@ constructor(options?: VylaSDKOptions) **Parameters:** - `options.tmdbApiKey` *(string, optional)* — TMDB v3 API Key for metadata lookups. -- `options.penguManifest` *(any, optional)* — Custom manifest for the Pengu provider source. +- `options.penguManifest` *(string, optional)* — Custom Stremio manifest URL for the Pengu provider source. ```javascript const sdk = new VylaSDK({ @@ -36,7 +36,7 @@ const sdk = new VylaSDK({ getSources(excludeDisabled?: boolean): SourceConfig[] ``` -Returns registered provider scraper configurations. +Returns registered provider scraper configurations from `SOURCES`. **Parameters:** - `excludeDisabled` *(boolean, optional)* — When `true`, filters out scrapers with `disabled: true`. Default: `false`. @@ -45,7 +45,8 @@ Returns registered provider scraper configurations. ```javascript const activeSources = sdk.getSources(true); -console.log(activeSources.map(s => s.key).join(', ')); +const dedicatedActive = activeSources.filter(s => s.dedicated); +const aggregatorActive = activeSources.filter(s => !s.dedicated); ``` --- @@ -59,10 +60,10 @@ async getStream( s?: number | null, e?: number | null, clientIP?: string | null -): Promise