mirror of
https://gitlab.com/vyla-entertainment/documentation.git
synced 2026-11-15 06:57:21 -05:00
102 lines
5.1 KiB
Markdown
102 lines
5.1 KiB
Markdown
# Architecture & System Design
|
||
|
||
<p class="page-description">Component boundaries, communication protocols, and media pipelines across the Vyla ecosystem.</p>
|
||
|
||
## System Layers
|
||
|
||
Vyla decouples presentation, streaming gateway mediation, and provider scraping into three distinct tiers:
|
||
|
||
- **Presentation Tier** (`Vyla Home`, `Vyla Go`, `Vyla TV`, custom web players): Handles the UI, player state, and media rendering using ExoPlayer Media3 or HLS.js. Connects via Server-Sent Events (SSE) and HTTP.
|
||
- **Gateway Tier** (`Stream API`): A Node.js cluster gateway. Manages in-memory LRU caching (1,500 entries, 5-minute TTL), rewrites HLS manifests and AES keys, and strips obfuscation headers.
|
||
- **Resolver Tier** (`@vyla-entertainment/sdk`): Directly queries 60+ scrapers with jitter delays, performs two-phase stream verification, and resolves subtitle tracks.
|
||
- **Upstream Hosts**: External CDNs and video hosts serving raw HLS manifests, video segments, and subtitle files.
|
||
|
||
---
|
||
|
||
## Component Details
|
||
|
||
### Vyla Home (Desktop)
|
||
- **Runtime**: Built with Tauri v2, Rust, and a local Node.js sidecar service.
|
||
- **IPC**: Communicates with the sidecar over standard I/O passing JSON-RPC messages.
|
||
- **Features**: System tray integration, automated delta updates, Discord Rich Presence, and local cache persistence.
|
||
|
||
### Vyla Go (Mobile)
|
||
- **Runtime**: Tauri v2 Mobile targeting Android ARM64 and x86_64 architectures.
|
||
- **Features**: Touch UI with WebGL shaders, background audio playback, and runtime asset patching.
|
||
|
||
### Vyla TV (Leanback)
|
||
- **Runtime**: Native Android app written in Kotlin with Jetpack Compose and ExoPlayer (Media3).
|
||
- **Features**: D-pad remote navigation, hardware-accelerated 4K/HDR decoding, audio track selection, and watch progress tracking.
|
||
|
||
### Stream API (Gateway)
|
||
- **Runtime**: Node.js microservice using the native `cluster` module.
|
||
- **Features**: Emits real-time playback events (`meta`, `source`, `done`) over SSE. Proxies HLS streams, rewrites encryption keys, strips 120-byte fake image masks, and caches verified sources for 5 minutes.
|
||
|
||
### Vyla SDK (`@vyla-entertainment/sdk`)
|
||
- **Runtime**: Pure ES Module Node.js package.
|
||
- **Features**: Contains 60+ modular scrapers in `src/sources/`, random jitter scheduling, retry backoff, two-phase validation (`verifyStream` / `verifyPlayable`), and Manga scraping with TLS client fingerprint spoofing.
|
||
|
||
---
|
||
|
||
## Playback Pipeline
|
||
|
||
1. **Client Handshake**: The player initiates an HTTP Server-Sent Events connection with a TMDB ID:
|
||
```http
|
||
GET /movie?id=155 HTTP/1.1
|
||
Host: api.vyla.cc
|
||
Accept: text/event-stream
|
||
```
|
||
|
||
2. **Metadata Delivery**: Stream API fetches TMDB details and subtitle tracks, emitting the first event immediately:
|
||
```json
|
||
data: {"type": "meta", "meta": {"title": "The Dark Knight", "year": 2008}, "subtitles": [{"lang": "English", "url": "..."}]}
|
||
```
|
||
|
||
3. **Concurrent Scraper Queries**: The SDK queries active scrapers concurrently with randomized jitter (0–500 ms) to prevent rate limits.
|
||
|
||
4. **Two-Phase Validation**:
|
||
- `verifyStream`: Tests candidate URLs with HTTP `HEAD` or range requests. Any response with status >= 400 is discarded.
|
||
- `verifyPlayable`: Validates the master HLS playlist and confirms video segment availability.
|
||
|
||
5. **Progressive Source Emission**: As each scraper verifies a working link, Stream API pushes a `source` event:
|
||
```json
|
||
data: {"type": "source", "source": "vidlink", "url": "https://api.vyla.cc/api?url=...", "quality": "1080p", "type": "hls"}
|
||
```
|
||
|
||
6. **Instant Playback**: The player starts playback on the very first source (typically within 3 to 8 seconds) and retains subsequent sources as automatic fallbacks.
|
||
|
||
7. **Stream Close**: When all scrapers finish or time out, Stream API emits the completion event:
|
||
```json
|
||
data: {"type": "done", "total": 4}
|
||
```
|
||
|
||
---
|
||
|
||
## Reverse Proxy & Mask Stripping
|
||
|
||
Many video hosts enforce strict CORS policies or mask video chunks behind fake image headers. Stream API handles this transparently:
|
||
|
||
### Playlist & Key Rewriting
|
||
When a stream is routed through `/api?url=<URL>`:
|
||
1. Stream API fetches the playlist using upstream `Referer` and `Origin` headers.
|
||
2. It rewrites `#EXT-X-KEY` AES encryption endpoints to route through the local proxy.
|
||
3. It rewrites `.ts` chunk paths so the player can fetch them with permissive CORS headers.
|
||
|
||
### Byte-Mask Stripping
|
||
Certain hosts prepend a 120-byte fake image header (`image/png` or `image/jpeg`) before the MPEG-TS sync byte (`0x47`). Stream API detects these headers and strips the prefix:
|
||
```javascript
|
||
const stripped = (full[0] === 0x89 || full[0] === 0xFF || full[0] === 0x00)
|
||
? full.subarray(120)
|
||
: full;
|
||
```
|
||
The stripped payload is returned with `Content-Type: video/MP2T`.
|
||
|
||
---
|
||
|
||
## Common Deployments
|
||
|
||
- **Single Desktop**: Run Vyla Home locally on your PC. No external ports or public servers required.
|
||
- **Smart TV Setup**: Run Vyla TV on your Android TV device connected to a hosted Stream API gateway on your local network or VPS.
|
||
- **Private Home Server**: Run Stream API on a home NAS or VPS behind Nginx with TLS and API key authentication.
|
||
- **Custom Application**: Import `@vyla-entertainment/sdk` into your own Node.js backend.
|