fixed syntax issues

This commit is contained in:
2026-11-14 19:05:02 -08:00
parent 2cec85a8f3
commit 36b2b33ecc
29 changed files with 842 additions and 977 deletions

View File

@@ -1,143 +1,101 @@
# 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>
<p class="page-description">Component boundaries, communication protocols, and media pipelines across the Vyla ecosystem.</p>
## High-Level Architecture
## System Layers
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.
Vyla decouples presentation, streaming gateway mediation, and provider scraping into three distinct tiers:
| 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. |
- **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 Boundaries & Responsibilities
## Component Details
### 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.
### 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.
### 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.
### 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.
### 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.
### 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.
### 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.
### 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.
### 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`.
### 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 Data Flow: Step-by-Step
## Playback Pipeline
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:
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. **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:
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. **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.
3. **Concurrent Scraper Queries**: The SDK queries active scrapers concurrently with randomized jitter (0–500 ms) to prevent rate limits.
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.
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 Delivery**
As each provider scraper completes two-phase verification, Stream API immediately pushes a `source` event over the active SSE stream:
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 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.
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 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:
7. **Stream Close**: When all scrapers finish or time out, Stream API emits the completion event:
```json
data: {"type": "done", "total": 4}
```
---
## The HLS Proxy & De-Obfuscation Mechanics
## Reverse Proxy & Mask Stripping
Many upstream streaming hosts employ strict CORS restrictions, IP-bound tokens, or binary header obfuscation. Vyla resolves this transparently:
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 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.
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 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:
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 resulting clean MPEG-TS stream is delivered to players with `Content-Type: video/MP2T`, enabling seamless playback across all platforms.
The stripped payload is returned with `Content-Type: video/MP2T`.
---
## Deployment Topologies
## Common Deployments
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 |
- **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.

View File

@@ -1,82 +1,47 @@
# Vyla Entertainment
# Vyla
<p class="page-description">A community-built, decentralized media ecosystem and developer platform focused on privacy, user sovereignty, and self-hosted streaming infrastructure.</p>
<p class="page-description">An open-source, modular media ecosystem. Native apps for desktop, mobile, and TV backed by a scraper SDK and self-hosted streaming gateway.</p>
<img class="vyla-banner" src="/src/assets/images/devices.webp" alt="The Vyla Ecosystem across Desktop, Android, and Android TV devices" loading="lazy" decoding="async" fetchpriority="low" />
<img class="vyla-banner" src="/src/assets/images/devices.webp" alt="Vyla across devices" loading="lazy" decoding="async" fetchpriority="low" />
## What is Vyla?
**Vyla** is an open-source, modular media ecosystem built on a simple foundation: **users and developers should have absolute sovereignty over their media experience.**
Vyla is an open-source media stack built for privacy and user control:
Unlike centralized streaming platforms that lock users into closed walled gardens, proprietary codecs, and telemetry tracking, Vyla separates the entire media stack into distinct, reusable layers:
1. **Client Frontends**: Native applications for Desktop (Windows, macOS, Linux), Mobile (Android), and Television (Android TV / Google TV).
2. **Scraper & Resolver SDK**: A high-performance Node.js scraping engine (`@vyla-entertainment/sdk`) aggregating over 60 distributed upstream providers with automatic jitter buffering and HLS playback verification.
3. **Stream API Gateway**: A self-hostable HTTP and Server-Sent Events (SSE) microservice proxy delivering low-latency progressive playback manifests, subtitle tracks, and media downloads.
- **Client Apps**: Native frontends for Desktop (Windows, macOS, Linux), Android Mobile, and Android TV.
- **Vyla SDK (`@vyla-entertainment/sdk`)**: A Node.js scraping engine querying 60+ upstream sources with jitter buffering and stream validation.
- **Stream API**: A self-hostable HTTP and Server-Sent Events (SSE) gateway delivering live stream manifests, subtitles, and downloads.
:::callout-note
**Core Policy**: Vyla does not host, upload, store, or distribute video files or copyrighted media. The ecosystem provides client applications and self-hosted scraping tools that resolve publicly accessible links on demand.
Vyla does not host, upload, or store video files. It resolves publicly accessible web links on demand.
:::
---
## Ecosystem Architecture at a Glance
## Ecosystem Components
The Vyla Ecosystem is designed around modularity. Each component functions autonomously or seamlessly interconnects with other components:
| Layer | Components | Core Capabilities |
| :--- | :--- | :--- |
| **User Interfaces** | **Vyla Home**, **Vyla Go**, **Vyla TV** | Desktop Tauri v2 with embedded sidecar, Android mobile client with WebGL shaders, and native Android TV (Jetpack Compose + ExoPlayer). |
| **Distribution Gateway** | **Stream API** | Node.js cluster gateway, SSE progressive source emitter, M3U8 playlist & key rewriting proxy, and 120-byte fake-image obfuscation stripper. |
| **Resolver Engine** | **Vyla SDK** (`@vyla-entertainment/sdk`) | 60+ modular source scrapers, two-phase stream verification (`verifyStream` / `verifyPlayable`), manga TLS-fingerprinted extraction, and subtitle normalization. |
- **[Vyla Home](/products/home)** — Desktop app built with Tauri v2 and Rust. Includes auto-updates, Discord RPC, and offline fallbacks.
- **[Vyla Go](/products/go)** — Android mobile client with shader animations and background playback.
- **[Vyla TV](/products/tv)** — Android TV and Fire TV app with D-pad navigation and ExoPlayer playback.
- **[Stream API](/stream-api/overview)** — High-concurrency Node.js streaming gateway with cluster caching and M3U8 reverse proxying.
- **[Vyla SDK](/sdk)** — Core resolver module for Node.js backends and scrapers.
- **[Web Player](/products/player)** — Lightweight HLS integration for custom web players.
---
## The Vyla Component Matrix
## Design Principles
| Component | Platform / Tech Stack | Primary Responsibility | Documentation |
| :--- | :--- | :--- | :--- |
| **Vyla Home** | Tauri v2, Node.js Sidecar, Rust | Full desktop control center, automatic updates, Discord RPC | [Vyla Home Guide](/products/home) |
| **Vyla Go** | Tauri v2 Mobile, WebGL Shaders | Android mobile runtime, automated payload download, background playback | [Vyla Go Guide](/products/go) |
| **Vyla TV** | Kotlin, Jetpack Compose, ExoPlayer | 10-foot Leanback television UI, D-pad navigation, 4K/HDR streaming | [Vyla TV Guide](/products/tv) |
| **Stream API** | Node.js, Cluster Workers, SSE | Self-hosted HTTP streaming gateway, M3U8 proxy, segment stripper | [Stream API Overview](/stream-api/overview) |
| **Vyla SDK** | Node.js (ESM), TLS Client, Cheerio | Multi-provider video resolver, subtitle extractor, manga engine | [SDK Overview](/sdk) |
| **Custom Player** | HLS.js, Video.js, HTML5 | Custom web and native playback integration layer | [Build a Player](/products/player) |
- **No Telemetry**: No mandatory accounts, analytics, or tracking.
- **Automatic Failover**: Queries multiple providers with randomized jitter. If a provider fails, the player moves to the next candidate instantly.
- **Progressive Delivery**: Stream API emits metadata and video candidates over Server-Sent Events (SSE) so playback starts in 3 to 8 seconds.
- **Self-Hostable**: Run every service locally or deploy to your own VPS.
---
## Core Principles
## Quick Navigation
- **Zero Centralized Telemetry**: Vyla frontends never require mandatory tracking, user account creation, or proprietary telemetry services.
- **Failover by Design**: Video resolution queries multiple providers concurrently with randomized jitter. If one upstream host goes down or throttles, the client seamlessly shifts to the next viable candidate.
- **Progressive Delivery**: Stream API delivers media metadata instantly, followed by source candidates streamed over Server-Sent Events (SSE) as each scraper resolves. Players start playback within 3 to 8 seconds without waiting for the slowest source.
- **Local Sovereignty**: Every part of Vyla can be self-hosted locally on your laptop, home server, NAS, or virtual private server (VPS).
---
## Where to Begin
Select your path based on your role:
:::code-group
<!-- tab: End Users -->
- **On Desktop (Windows, macOS, Linux)?** Download and run [Vyla Home](/products/home).
- **On Android Phone or Tablet?** Install the native [Vyla Go APK](/products/go).
- **On Android TV, Google TV, or Fire TV?** Install the [Vyla TV APK](/products/tv).
- **Need help with setup?** Read the [Troubleshooting Guide](/resources/troubleshooting).
<!-- tab: Backend Developers -->
- **Embedding scrapers in a Node.js project?** Check out the [SDK Quickstart](/sdk/vyla-sdk/quickstart) and [Complete API Reference](/sdk/vyla-sdk/reference).
- **Want to author a new provider?** Follow the [Contributing a Source Guide](/sdk/vyla-sdk/contributing).
- **Integrating Manga discovery?** Read the [Manga SDK Documentation](/sdk/vyla-sdk/manga).
<!-- tab: Frontend & App Developers -->
- **Connecting a web or mobile player?** Read [Paths & Playback Events](/stream-api/reference/paths) and the [Client Integration Guide](/guides/integrations).
- **Building fallback strategies?** Study the [Error Handling Guide](/guides/error-handling).
- **Self-hosting the streaming gateway?** Read the [Self-Hosting Guide](/stream-api/deployment/self-hosting).
---
## Legal Notice & DMCA Compliance
Vyla is self-hosted software intended for personal educational and development use. All stream resolution and scraper logic interacts with publicly available web sources. Rights holders can review our takedown policies in the [DMCA Policy](/misc/project/dmca).
- **Desktop Users**: Get started with [Vyla Home](/products/home).
- **Mobile & TV**: Check out [Vyla Go](/products/go) and [Vyla TV](/products/tv).
- **Node.js Developers**: See the [SDK Quickstart](/sdk/vyla-sdk/quickstart) and [API Reference](/sdk/vyla-sdk/reference).
- **Self-Hosters**: Read the [Self-Hosting Guide](/stream-api/deployment/self-hosting).
- **Need Help?**: Visit the [FAQ](/resources/faq) or [Troubleshooting](/resources/troubleshooting).