vyla-entertainment/documentation
2
0
Fork 0
mirror of https://gitlab.com/vyla-entertainment/documentation.git synced 2026-11-14 22:47:26 -05:00
Code Issues Packages Projects Releases Wiki Activity

huge rewrite

Browse Source
This commit is contained in:
alwaysmesmerizingyou
2026-11-14 18:21:12 -08:00
parent f465d1ec0d
commit 2cec85a8f3
69 changed files with 11479 additions and 1576 deletions
Download Patch File Download Diff File Expand all files Collapse all files

155
start-here/architecture.md
View File

@@ -1,44 +1,143 @@
# Our Architecture
# Architecture & System Design
<p class="page-description">How Vyla Home, SDK, and Stream API relate, and where each responsibility belongs.</p>
<p class="page-description">Deep architectural breakdown of the Vyla Ecosystem: component boundaries, communication protocols, video delivery pipelines, and failover topologies.</p>
## The Vyla stack
## High-Level Architecture
Vyla separates local application management, provider resolution, and client-facing delivery. That separation lets each layer be used on its own while keeping the integration points clear.
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 Home
| 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. |
Home is responsible for a desktop session: local configuration, encrypted local credentials, update coordination, managed processes, and the embedded interface. It is the right layer for launching and supervising a local experience.
---
### Vyla SDK
## Component Boundaries & Responsibilities
The SDK contains the provider-facing work: source configuration, stream resolution, subtitle retrieval, manga discovery and page resolution, download lookup, and health probes. It is the right layer when your Node.js application needs to decide how requests are authorized, cached, selected, and returned.
### 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.
### Stream API
### 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.
Stream API wraps the SDK in a self-hosted HTTP service. Its movie and TV endpoints use Server-Sent Events so metadata can arrive first and usable sources can be delivered progressively. It also provides subtitle, download, health, test, and optional debug routes.
### 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.
## Common deployment patterns
### 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.
| Pattern | Best for | Key decision |
| --- | --- | --- |
| Home only | a managed local desktop experience | Home owns the lifecycle of bundled local services |
| App + SDK | a Node.js backend with a custom product API | your app owns authentication, policy, and response design |
| Player + Stream API | browser or mobile clients that need a stable HTTP contract | deploy Stream API and place it behind TLS when exposed remotely |
| Home + Stream API | a local player backed by a local service | keep the service bound and access-controlled for the local environment |
### 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`.
## Data flow for playback
---
1. A client provides a TMDB media ID (plus season and episode for TV).
2. Stream API, or your own SDK-based backend, asks active providers for candidates.
3. Candidates are checked and successful sources are returned progressively.
4. The player begins with the first compatible candidate and keeps later candidates as fallbacks.
5. Subtitle and download lookups are separate operations; neither should block first playback.
## Playback Data Flow: Step-by-Step
Provider availability varies by source and network environment. Build the player experience around fallbacks and empty-result states, as described in [Error handling](/guides/error-handling).
Understanding how a media stream is discovered, verified, and played:
## Data flow for manga
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
```
1. A client provides a search term, or direct manga identifier.
2. The SDK queries the manga provider for title details, metadata, and chapter listings.
3. When reading a chapter, the SDK resolves ordered page assets with dimensions and aspect ratios for responsive layout rendering.
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 |

94
start-here/introduction.md
View File

@@ -1,54 +1,82 @@
# Vyla Entertainment
<p class="page-description">A community-built media project focused on freedom, privacy, and giving people control over their own experience.</p>
<p class="page-description">A community-built, decentralized media ecosystem and developer platform focused on privacy, user sovereignty, and self-hosted streaming infrastructure.</p>
<img class="vyla-banner" src="/src/assets/images/devices.png" alt="A collage of films and shows available through a Vyla experience" loading="lazy" fetchpriority="low" />
<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" />
## About Vyla
## What is Vyla?
Vyla is a community-built media project created around a simple idea: **people should have control over how they experience their media.**
**Vyla** is an open-source, modular media ecosystem built on a simple foundation: **users and developers should have absolute sovereignty over their media experience.**
We started Vyla because we wanted something clean, private, and easy to use without relying on a single company or centralized service. What began as a small project has grown into a collection of applications and tools for desktop, Android, Android TV, and more.
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:
Vyla is not a streaming service, and we do not host or provide the media itself. Instead, we build the software that brings the experience together while leaving control in the hands of the person using it.
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.
## Where we come from
:::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 started as a small web project focused on creating a better way to discover and watch movies and shows. Over time, it grew into a broader project with applications for different platforms alongside the tools that power them.
---
We care about keeping Vyla open, accessible, and community-driven. Our project has also been shared by communities such as **FMHY** and **r/Piracy**, where people interested in alternative and self-hosted media solutions have discovered Vyla.
## Ecosystem Architecture at a Glance
We are proud to be part of a wider community of people who build, share, and explore alternatives to traditional media platforms.
The Vyla Ecosystem is designed around modularity. Each component functions autonomously or seamlessly interconnects with other components:
## What we make
| 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 is made up of several projects designed for different ways of using the platform.
---
| Platform | Description | Link |
| --- | --- | --- |
| Vyla Home | Desktop app | [Learn more](/products/home) |
| Vyla Go | Android app | [Learn more](/products/go) |
| Vyla TV | Android TV app | [Learn more](/products/tv) |
| Vyla SDK | Developer SDK | [Learn more](/sdk) |
| Stream API | Self-hosted API | [Learn more](/stream-api/overview) |
## The Vyla Component Matrix
## Made for people, not platforms
| 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) |
We believe software should give people more control, not less.
---
That means keeping Vyla local and self-hostable, avoiding unnecessary centralized dependencies, and allowing developers and users to decide how they want to use the project.
## Core Principles
Vyla can be as simple as a TV or mobile app, a desktop application, or the foundation for a completely custom media experience. **You decide how much of Vyla you use and where it runs.**
- **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).
## Start exploring
---
- **On desktop?** See [Vyla Home](/products/home).
- **On Android?** See [Vyla Go](/products/go).
- **Using Android TV?** See [Vyla TV](/products/tv).
- **Building something with Vyla?** Start with the [SDK quickstart](/sdk/vyla-sdk/quickstart).
- **Building your own client?** See the [Stream API](/stream-api/overview).
- **Want to understand how everything fits together?** Visit [Our Architecture](/start-here/architecture).
## Where to Begin
:::callout-info
Vyla is self-hosted software and does not host or distribute media. Please respect applicable laws, upstream terms, and rights-holder requests. See the [DMCA policy](/misc/project/dmca) for removal information.
:::
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).