mirror of
https://gitlab.com/vyla-entertainment/documentation.git
synced 2026-11-14 22:47:26 -05:00
144 lines
8.8 KiB
Markdown
144 lines
8.8 KiB
Markdown
# Architecture & System Design
|
||
|
||
<p class="page-description">Deep architectural breakdown of the Vyla Ecosystem: component boundaries, communication protocols, video delivery pipelines, and failover topologies.</p>
|
||
|
||
## High-Level Architecture
|
||
|
||
The Vyla architecture cleanly separates **presentation**, **gateway mediation**, and **content resolution**. This decoupling ensures that any individual layer can be replaced, scaled, or run independently.
|
||
|
||
| Architecture Tier | Components | Protocols & Interfaces | Core Responsibilities |
|
||
| :--- | :--- | :--- | :--- |
|
||
| **Presentation Tier** | Vyla Home, Vyla Go, Vyla TV, Third-Party Web Players | SSE (HTTP/1.1), REST (JSON), HLS / DASH | Render user interface, manage local state, execute video playback via HLS.js or ExoPlayer Media3. |
|
||
| **Gateway Tier** | Stream API (`server.js`) | Node.js Cluster IPC, HTTP/REST, SSE, Reverse Proxy | Expose public endpoints, manage 1,500-entry in-memory cache, rewrite M3U8 playlists & AES keys, strip 120-byte obfuscation masks. |
|
||
| **Resolver Tier** | Vyla SDK (`@vyla-entertainment/sdk`) | Direct ESM function calls, HTTP/HTTPS scrapers | Scrape 60+ upstream providers concurrently, enforce random jitter delays, run two-phase stream validation. |
|
||
| **Upstream Hosts** | Public Third-Party CDNs & Video Hosts | Encrypted TLS/HTTPS, M3U8, MP4 | Deliver raw media segments and video assets. |
|
||
|
||
---
|
||
|
||
## Component Boundaries & Responsibilities
|
||
|
||
### 1. Vyla Home (Desktop)
|
||
- **Runtime Environment**: Built on [Tauri v2](https://v2.tauri.app/) using Rust and an embedded Node.js sidecar service.
|
||
- **IPC Protocol**: Communicates with the sidecar process via standard input/output (`stdin`/`stdout`) passing JSON-RPC messages.
|
||
- **Responsibilities**:
|
||
- Manages application lifecycle, window management, and native system tray.
|
||
- Automatically checks, verifies cryptographic signatures (`update-signing.pem`), and extracts delta updates from GitLab releases.
|
||
- Houses the local `ServiceManager` and `Patcher` for offline and local service fallback.
|
||
- Dispatches Discord Rich Presence activity updates (`discord-rpc.js`).
|
||
- Persists configuration and cache to platform-specific AppData locations.
|
||
|
||
### 2. Vyla Go (Mobile)
|
||
- **Runtime Environment**: Tauri v2 for Android (`tauri-android`) targeting ARM64 (`aarch64`) and x86_64 architectures.
|
||
- **Responsibilities**:
|
||
- Touch-optimized interface utilizing WebGL hardware shaders and glassmorphism styling.
|
||
- Automated resource management: fetches, unpacks, and hot-patches runtime assets directly from remote releases without requiring full APK reinstallations for minor script updates.
|
||
- Background playback coordination and media notification integration.
|
||
|
||
### 3. Vyla TV (Leanback)
|
||
- **Runtime Environment**: Native Android application written in Kotlin utilizing Jetpack Compose and Google's [ExoPlayer (Media3)](https://developer.android.com/media/media3/exoplayer).
|
||
- **Responsibilities**:
|
||
- Strictly optimized for D-pad remote controls, 10-foot viewing distances, and Android TV / Google TV operating systems.
|
||
- Native HLS stream parsing, hardware-accelerated 4K/HDR decoding, playback speed manipulation, audio track selection, and subtitle overlay.
|
||
- Local client storage for user favorites, watch progress resume, and TMDB catalog browsing.
|
||
|
||
### 4. Stream API (Gateway)
|
||
- **Runtime Environment**: Node.js microservice utilizing the native `cluster` module for multi-core process forking.
|
||
- **Responsibilities**:
|
||
- Acts as an HTTP/SSE bridge for clients that cannot run the Node.js SDK directly (e.g. mobile apps, TV apps, browser frontends).
|
||
- Emits real-time playback events (`meta`, `source`, `done`) over Server-Sent Events.
|
||
- Proxies HLS media streams (`/api?url=...`), automatically rewriting playlist chunk URIs and AES encryption key endpoints to bypass browser CORS and network restrictions.
|
||
- Strips obfuscation masks (e.g. 120-byte fake PNG/JPEG headers used by ByteDance/TikTok-based content delivery networks).
|
||
- Caches verified results for 5 minutes (TTL = 300,000 ms) in a shared inter-process memory map.
|
||
|
||
### 5. Vyla SDK (`@vyla-entertainment/sdk`)
|
||
- **Runtime Environment**: Pure ES Module Node.js library.
|
||
- **Responsibilities**:
|
||
- Houses the core provider scraping modules (60+ scrapers in `src/sources/`).
|
||
- Implements jitter scheduling, retry backoff, and custom header injection (`User-Agent`, `Referer`, `Origin`).
|
||
- Performs two-phase verification on resolved candidate URLs.
|
||
- Houses the Manga resolver engine leveraging `node-tls-client` to bypass TLS fingerprint blocking on `atsu.moe`.
|
||
|
||
---
|
||
|
||
## Playback Data Flow: Step-by-Step
|
||
|
||
Understanding how a media stream is discovered, verified, and played:
|
||
|
||
1. **Client Establishes SSE Connection**
|
||
The viewer selects a title (e.g., TMDB ID `155`), and the client initiates an HTTP Server-Sent Events handshake:
|
||
|
||
```http
|
||
GET /movie?id=155 HTTP/1.1
|
||
Host: api.vyla.cc
|
||
Accept: text/event-stream
|
||
```
|
||
|
||
2. **Stream API Emits Initial Metadata**
|
||
Stream API validates the identifier, queries TMDB for metadata and artwork, queries subtitle providers, and immediately delivers a `meta` event:
|
||
|
||
```json
|
||
data: {"type": "meta", "meta": {"title": "The Dark Knight", "year": 2008}, "subtitles": [{"lang": "English", "url": "..."}]}
|
||
```
|
||
|
||
3. **SDK Initiates Concurrent Provider Queries**
|
||
The SDK filters active provider scrapers from configuration, applies randomized per-source jitter (0–500 ms) to avoid burst-rate triggers, and initiates upstream HTTP scraping requests concurrently.
|
||
|
||
4. **Two-Phase Stream Verification**
|
||
- **Phase A (`verifyStream`)**: Executes an HTTP `HEAD` or range `GET` request against candidate stream URLs. Responses with status $\ge 400$ are discarded immediately.
|
||
- **Phase B (`verifyPlayable`)**: Downloads and parses the master HLS manifest (`#EXT-X-STREAM-INF`), validates chunk resolution, and tests segment availability.
|
||
|
||
5. **Progressive Source Delivery**
|
||
As each provider scraper completes two-phase verification, Stream API immediately pushes a `source` event over the active SSE stream:
|
||
|
||
```json
|
||
data: {"type": "source", "source": "vidlink", "url": "https://api.vyla.cc/api?url=...", "quality": "1080p", "type": "hls"}
|
||
```
|
||
|
||
6. **Instant Client Playback**
|
||
The client media player (ExoPlayer, HLS.js, or AVPlayer) immediately begins playback upon receiving the first valid source event (typically within 3–8 seconds). Subsequent incoming sources are enqueued into a client-side fallback list.
|
||
|
||
7. **Stream Completion**
|
||
Once all configured source scrapers have either returned verified streams or reached their timeout thresholds (typically 15–25 seconds), Stream API emits the completion event and closes the connection:
|
||
|
||
```json
|
||
data: {"type": "done", "total": 4}
|
||
```
|
||
|
||
---
|
||
|
||
## The HLS Proxy & De-Obfuscation Mechanics
|
||
|
||
Many upstream streaming hosts employ strict CORS restrictions, IP-bound tokens, or binary header obfuscation. Vyla resolves this transparently:
|
||
|
||
### Playlist & Key Rewriting
|
||
When a stream URL is proxied through `/api?url=<URL>&<param>=1`, the gateway:
|
||
1. Requests the upstream playlist with provider-mandated `Referer` and `Origin` headers.
|
||
2. Intercepts `#EXT-X-KEY:METHOD=AES-128,URI="..."` and rewrites the key URI to route through the proxy.
|
||
3. Rewrites all chunk lines (`.ts` / `.m4s`) so that browser audio/video fetch calls pass through the proxy with valid `Access-Control-Allow-Origin: *` headers.
|
||
|
||
### Byte-Mask Stripping
|
||
Certain modern providers mask `.ts` video chunks as fake image files (`image/png`, `image/jpeg`, `letsgocdn`, or TikTok CDN formats) by prepending a 120-byte image header before the MPEG-TS sync byte (`0x47`):
|
||
```
|
||
[ 120-byte Fake PNG Header (0x89 0x50 0x4E 0x47...) ] + [ MPEG-TS Payload (0x47...) ]
|
||
```
|
||
When Stream API detects these signatures via regular expressions (`TIKTOK_REGEX`, `STRIP_REGEX`), it slices off the first 120 bytes:
|
||
```javascript
|
||
const stripped = (full[0] === 0x89 || full[0] === 0xFF || full[0] === 0x00)
|
||
? full.subarray(120)
|
||
: full;
|
||
```
|
||
The resulting clean MPEG-TS stream is delivered to players with `Content-Type: video/MP2T`, enabling seamless playback across all platforms.
|
||
|
||
---
|
||
|
||
## Deployment Topologies
|
||
|
||
Choose the deployment architecture that fits your infrastructure:
|
||
|
||
| Topology | Components Used | Best For | Security & Networking |
|
||
| :--- | :--- | :--- | :--- |
|
||
| **All-in-One Desktop** | Vyla Home | Casual users wanting local playback on a single PC | Fully local, runs on localhost, zero open ports |
|
||
| **Living Room TV** | Vyla TV + Hosted Stream API | Smart TVs, Chromecast, NVIDIA Shield | TV connects over LAN/WAN to a secure Stream API gateway |
|
||
| **Private Family Server** | Stream API on VPS/NAS | Multi-device households streaming across phones, PCs, and TVs | Run behind Nginx/Caddy with TLS, enable API key protection |
|
||
| **Custom Platform** | SDK in Node.js backend | Developers building bespoke streaming web applications | Complete control over DB, auth, caching, and playback logic |
|