documentation/start-here/architecture.md

Architecture & System Design

Component boundaries, communication protocols, and media pipelines across the Vyla ecosystem.

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:

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:

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:

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:

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:

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.