From 36b2b33ecc9268c3f8b22d61f9402d21e41a9efb Mon Sep 17 00:00:00 2001 From: alwaysmesmerizingyou Date: Sat, 14 Nov 2026 19:05:02 -0800 Subject: [PATCH] fixed syntax issues --- ARCHITECTURE.md | 32 +++--- concepts/providers.md | 108 ++++++++------------ guides/error-handling.md | 68 ++++--------- index.html | 16 +-- products/go.md | 66 +++++-------- products/home.md | 89 ++++------------- products/player.md | 74 +++----------- products/tv.md | 60 ++++-------- resources/troubleshooting.md | 11 +-- scripts/bundle-css.mjs | 1 + sdk/vyla-sdk/contributing.md | 75 +++++++------- sdk/vyla-sdk/index.md | 57 ++++------- sdk/vyla-sdk/reference.md | 95 +++++++----------- src/css/bundle.css | 122 ++++++++++++++++++++++- src/css/bundle.min.css | 2 +- src/css/features.css | 35 +++++++ src/css/highlight.css | 80 ++++++++------- src/css/layout.css | 2 - src/css/roots.css | 6 ++ src/js/main.js | 118 +++++++++++++++++++--- src/js/prism.js | 28 ++++++ start-here/architecture.md | 136 +++++++++----------------- start-here/introduction.md | 87 +++++----------- stream-api/authentication/index.md | 59 +++++------ stream-api/deployment/self-hosting.md | 71 +++++--------- stream-api/overview/index.md | 75 +++++++------- stream-api/reference/media-data.md | 78 ++++++--------- stream-api/reference/operations.md | 66 ++++++------- stream-api/reference/paths.md | 102 +++++++++---------- 29 files changed, 842 insertions(+), 977 deletions(-) create mode 100644 src/js/prism.js diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index e0db006..4328690 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -1,28 +1,28 @@ # Vyla Ecosystem Architecture -> High-level architecture, module boundaries, communication protocols, and design principles of the Vyla Ecosystem. +High-level architecture, module boundaries, communication protocols, and design principles of the Vyla Ecosystem. ## System Topology -| Ecosystem Layer | Core Technologies | Primary Responsibilities | -| :--- | :--- | :--- | -| **Client Interfaces** | Vyla Home (Tauri v2), Vyla Go (Mobile), Vyla TV (ExoPlayer), Web Players | Render UI, manage local user state, initiate playback via SSE, handle failover queues. | -| **Stream API Gateway** | Node.js Cluster, SSE, HTTP Proxy | Multi-core IPC caching (1,500 entries, 5-min TTL), HLS/AES key rewriting, 120-byte fake image mask stripping. | -| **Vyla SDK Resolver** | `@vyla-entertainment/sdk` (ESM) | 60+ provider scrapers, randomized jitter scheduling, two-phase stream validation, manga scraping with Chrome 131 TLS fingerprinting. | -| **Upstream Hosts** | Third-party CDNs & Video Hosts | Remote video segment delivery, HLS manifest endpoints, subtitle hosts. | +- **Client Interfaces**: Vyla Home (Tauri v2), Vyla Go (Mobile), Vyla TV (ExoPlayer), Web Players. Render UI, manage local state, initiate playback via SSE, and handle failover queues. +- **Stream API Gateway**: Node.js Cluster, SSE, HTTP Proxy. Multi-core IPC caching (1,500 entries, 5-min TTL), HLS/AES key rewriting, and 120-byte fake image mask stripping. +- **Vyla SDK Resolver**: `@vyla-entertainment/sdk` (ESM). 60+ provider scrapers, randomized jitter scheduling, two-phase stream validation, and manga scraping with Chrome 131 TLS fingerprinting. +- **Upstream Hosts**: Remote video segment delivery, HLS manifest endpoints, and subtitle hosts. + +--- ## Projects Overview -| Directory / Package | Language / Framework | Purpose | -| :--- | :--- | :--- | -| `Documentation` | HTML5, Vanilla JS, CSS3 | Official developer documentation platform hosted at [vyla.cc](https://vyla.cc). | -| `Stream API` | Node.js (Cluster, HTTP, SSE) | Self-hosted streaming microservice gateway with caching and reverse proxying. | -| `SDK` | Node.js (ESM), TLS Client | Core multi-provider scraping library (`@vyla-entertainment/sdk`). | -| `Home` | Tauri v2, Rust, Node.js Sidecar | Native desktop application for Windows, macOS, and Linux. | -| `TV` | Kotlin, Jetpack Compose, ExoPlayer | Native 10-foot Leanback streaming application for Android TV and Fire TV. | -| `Go` | Tauri v2 Mobile, WebGL Shaders | Native mobile client for Android devices. | +- **Documentation**: Developer documentation platform hosted at [vyla.cc](https://vyla.cc). +- **Stream API**: Self-hosted streaming microservice gateway with caching and reverse proxying. +- **SDK**: Core multi-provider scraping library (`@vyla-entertainment/sdk`). +- **Home**: Native desktop application for Windows, macOS, and Linux (Tauri v2 + Rust + Node.js sidecar). +- **TV**: Native 10-foot Leanback streaming application for Android TV and Fire TV (Kotlin + Jetpack Compose + ExoPlayer). +- **Go**: Native mobile client for Android devices (Tauri v2 Mobile). -## Core Architectural Invariants +--- + +## Core Invariants 1. **Decoupled Resolution**: Client interfaces never scrape providers directly; they interact through `@vyla-entertainment/sdk` or the Stream API gateway. 2. **Progressive Playback**: Streaming links are emitted incrementally over Server-Sent Events (SSE). Players start playback on the first candidate (3-8s) and queue subsequent sources as fallbacks. diff --git a/concepts/providers.md b/concepts/providers.md index 5c8d5aa..63e9775 100644 --- a/concepts/providers.md +++ b/concepts/providers.md @@ -4,32 +4,30 @@ ## Overview -At the heart of the Vyla ecosystem is the **Provider Layer**. Rather than relying on a single upstream video host, Vyla SDK aggregates over 60 independent, community-maintained scraping resolvers. - -Each provider operates with distinct upstream mechanics, domain rotations, rate-limiting policies, and security defenses. This document explains how Vyla orchestrates these disparate sources into a unified, high-reliability streaming pipeline. +Rather than relying on a single upstream host, the Vyla SDK aggregates over 60 independent provider scrapers. Each scraper handles its own domain logic, extraction mechanics, and header requirements. --- -## Provider Configuration Interface +## Provider Configuration -In `@vyla-entertainment/sdk`, each provider is declared in `src/config.js` via the `SourceConfig` interface: +Scrapers are configured in `src/config.js`: ```typescript export interface SourceConfig { - key: string; // Unique source identifier (e.g. "vidlink", "vixsrc") - label: string; // Human-readable display label - sourceFile: string; // Scraper module filename in src/sources/ - proxyParam: string; // Query parameter used for HLS proxy routing - timeout: number; // Total milliseconds allowed before source abort - sourcesTimeout?: number; // Secondary timeout for multi-server extraction - jitter: number; // Maximum randomized startup delay in ms - retries: number; // Number of automatic retry attempts on error - multiUrl: boolean; // Returns multiple stream candidate URLs if true - skipProxy?: boolean; // If true, returns direct upstream URLs without proxy - skipVerify?: boolean; // If true, bypasses verification checks - verifyHeaders?: boolean; // Injects custom headers into verification probes - disabled?: boolean; // If true, provider is completely excluded - cdnHeaders?: { // Custom headers injected for specific CDN patterns + key: string; + label: string; + sourceFile: string; + proxyParam: string; + timeout: number; + sourcesTimeout?: number; + jitter: number; + retries: number; + multiUrl: boolean; + skipProxy?: boolean; + skipVerify?: boolean; + verifyHeaders?: boolean; + disabled?: boolean; + cdnHeaders?: { pattern: RegExp; headers: { Referer: string; Origin: string; }; }[]; @@ -38,80 +36,56 @@ export interface SourceConfig { --- -## The Query Pipeline +## Query Pipeline -When a client requests a title (`getStream()` in SDK or `/movie` / `/tv` in Stream API), the engine executes the following pipeline: - -| Pipeline Stage | Operation | Purpose & Verification | -| :--- | :--- | :--- | -| **1. Source Filtering** | `SOURCES.filter(!disabled)` | Excludes disabled scrapers and selects active providers based on configuration. | -| **2. Jitter Staggering** | Sleep between `0` and `cfg.jitter` ms | Disperses outbound connection spikes across time to prevent DDoS protection triggers. | -| **3. Concurrent Scraping** | Parallel async scraper execution | Scrapers parse HTML/JSON endpoints using customized `User-Agent`, `Referer`, and `Origin` headers. | -| **4. Two-Phase Verification** | `verifyStream()` then `verifyPlayable()` | Phase 1 validates HTTP status ($< 400$ via HEAD). Phase 2 parses HLS manifests and verifies segment availability. Dead streams are discarded. | -| **5. Proxy URL Rewriting** | Encodes target URL into `/api?url=...` | Adds proxy flags, sets required playback headers, and prepares segment de-obfuscation. | -| **6. Progressive Emission** | Pushes SSE `source` event | Delivers playable stream candidates to the client player immediately without waiting for slower providers. | +1. **Source Filtering**: Excludes disabled scrapers and loads active configurations. +2. **Jitter Delay**: Sleeps for a randomized duration between `0` and `cfg.jitter` ms to avoid burst requests. +3. **Concurrent Scraping**: Runs scrapers in parallel with provider-specific `User-Agent`, `Referer`, and `Origin` headers. +4. **Two-Phase Verification**: Validates candidate URLs via `verifyStream()` (HTTP status < 400) and `verifyPlayable()` (HLS playlist and segment checks). +5. **Proxy URL Rewriting**: Encodes verified streams into `/api?url=...` with required proxy flags. +6. **Progressive Emission**: Pushes candidate streams over Server-Sent Events (SSE) immediately. --- -## Jitter Staggering & Rate-Limit Defense +## Jitter Staggering -If a client triggers 60 scrapers instantaneously, your client IP address could send hundreds of simultaneous HTTP requests in the same millisecond, triggering upstream Cloudflare or DDoS rate limits. +To prevent triggering upstream rate limits when querying dozens of scrapers simultaneously, each scraper applies random jitter: -To mitigate this, Vyla introduces **per-source jitter**: ```javascript const jitterDelay = Math.floor(Math.random() * (cfg.jitter || 400)); await new Promise(resolve => setTimeout(resolve, jitterDelay)); ``` -By staggering outbound requests across a 100ms–800ms window, upstream hosts perceive natural traffic patterns, dramatically reducing HTTP 429 (Too Many Requests) errors. + +This spreads outbound requests across a 100ms–800ms window, reducing HTTP 429 errors. --- -## Two-Phase Playback Verification +## Two-Phase Verification -Many streaming extractors successfully return a URL, only for that URL to return an HTTP 403 Forbidden, an empty manifest, or a dead video chunk. To protect players from stalling, Vyla validates every candidate through two independent verification stages before emitting it: +1. **Phase 1 (`verifyStream`)**: Sends a lightweight HTTP `HEAD` request with source-specific headers. Discards any response >= 400. +2. **Phase 2 (`verifyPlayable`)**: Fetches the initial playlist bytes, verifies the `#EXTM3U` header, confirms playable segment paths, and tests the first chunk or key URI. -### Phase 1: `verifyStream()` -- Dispatches a lightweight HTTP `HEAD` request to the upstream target URL. -- Enforces custom `User-Agent`, `Referer`, and `Origin` headers. -- Requires HTTP status code `< 400` within 4,000 milliseconds. - -### Phase 2: `verifyPlayable()` -- Fetches the initial playlist bytes through the local proxy. -- Validates the presence of the `#EXTM3U` header tag. -- Checks for stream definitions: - - If a Master Playlist: ensures valid `#EXT-X-STREAM-INF` entries exist. - - If a Media Playlist: ensures valid `#EXTINF` duration tags and playable segment URIs exist. -- Attempts a test read on the first media segment or key URI. -- Only candidates that pass both phases are deemed **verified**. +Only streams that pass both checks are returned to the client. --- -## The Universal HLS Proxy & Byte-Mask Stripper +## Proxy & Header Stripping -Modern streaming hosts often protect their video segments by adding CORS restrictions, token signatures, or binary header masking. Stream API handles this transparently: +- **M3U8 Rewriting**: Rewrites AES-128 encryption key URIs and `.ts` segment paths to route through the proxy with CORS headers (`Access-Control-Allow-Origin: *`). +- **120-Byte Mask Stripping**: Slices off fake 120-byte image headers prepended by certain CDNs: -### 1. M3U8 Playlist Rewriting -When an HLS stream is proxied, Stream API fetches the upstream playlist and rewrites every internal URI: -- **AES-128 Key URIs**: `#EXT-X-KEY:METHOD=AES-128,URI="/api?url=&=1"` -- **Video Chunks**: Segment URIs are rewritten to route back through the `/api` proxy endpoint. -- **CORS Headers**: Returned with `Access-Control-Allow-Origin: *` and `Access-Control-Allow-Headers: *`. - -### 2. Segment Byte-Mask Stripping -Certain major CDNs mask MPEG-TS chunks by prepending a 120-byte fake image header (`image/png`, `image/jpeg`, TikTok CDN, or `letsgocdn` signatures) so firewalls treat them as images. - -When Stream API proxies these segments, it inspects the leading bytes and automatically strips the 120-byte image wrapper: ```javascript const needsStrip = searchParams.has('tt') || STRIP_REGEX.test(cleanUrl); if (needsStrip && (chunk[0] === 0x89 || chunk[0] === 0xFF || chunk[0] === 0x00)) { - return chunk.subarray(120); // Strips fake header, leaving clean MPEG-TS + return chunk.subarray(120); } ``` --- -## Inter-Process Caching +## In-Memory Caching -Verified stream results are cached in-memory with a **5-minute Time-To-Live (TTL)**: -- **Cache Key**: `source_key + tmdb_id + season + episode` -- In multi-core cluster deployments, cache entries are coordinated across workers via inter-process communication (IPC) messages (`cache:get`, `cache:hit`, `cache:set`). -- Automatic prune routines run every 30 seconds to evict expired items and enforce maximum cache limits (default: 1,500 entries). +Verified stream candidates are cached in-memory for 5 minutes (300,000 ms): +- Cache keys format: `source_key + tmdb_id + season + episode`. +- In cluster mode, workers coordinate entries via IPC messages (`cache:get`, `cache:hit`, `cache:set`). +- Expired entries are pruned every 30 seconds, maintaining a 1,500-entry ceiling. diff --git a/guides/error-handling.md b/guides/error-handling.md index 8e77e52..2c5df17 100644 --- a/guides/error-handling.md +++ b/guides/error-handling.md @@ -4,44 +4,32 @@ ## Overview -Streaming from distributed upstream web providers is inherently dynamic. Upstream CDN nodes rotate domains, regional ISPs implement traffic shaping, and token signatures expire. - -Building a resilient client requires planning for failure at every step. This guide explains how Vyla handles errors internally and how client players should respond. +Upstream video providers can rotate domains, experience rate limits, or suffer transient outages. This guide explains how Vyla handles errors internally and how client players should respond. --- -## Error Classification Matrix +## Error Classification -| Error Type | Common Cause | Stream API / SDK Behavior | Recommended Player Action | -| :--- | :--- | :--- | :--- | -| **HTTP 400 Bad Request** | Missing or malformed TMDB ID, invalid season/episode | Returns immediate JSON error payload without querying providers. | Validate input parameters client-side before sending requests. | -| **HTTP 429 Too Many Requests** | Upstream host rate-limiting client IP | SDK provider applies backoff delay and retries up to `retries` limit. | If proxy returns 429, respect the `retry_after` header and back off. | -| **HTTP 502 Bad Gateway** | Upstream provider host is unreachable or timed out | Provider is discarded; other scrapers continue executing. | Fall back to the next available stream candidate in your queue. | -| **SSE Disconnect** | Network hiccup or client tab backgrounded | Connection drops; `EventSource.onerror` fires. | If video is already playing, do not interrupt. Otherwise, reconnect after 2 seconds. | -| **HLS Fatal Media Error** | Segment buffer stall, corrupt chunk, or missing decryption key | Player triggers `Hls.Events.ERROR` with `fatal: true`. | Call `hls.destroy()` and load the next candidate from your fallback queue. | +- **HTTP 400 Bad Request**: Missing or invalid TMDB ID or episode parameters. Validate input parameters on the client before requesting streams. +- **HTTP 429 Too Many Requests**: Upstream host rate limit triggered. The SDK applies backoff delays; clients should respect the `retry_after` header. +- **HTTP 502 Bad Gateway**: Upstream host unreachable or timed out. That provider is discarded while other scrapers continue running. +- **SSE Disconnect**: Network drop or backgrounded tab. If media is already buffering, do not interrupt. Otherwise, reconnect after a brief delay. +- **HLS Fatal Media Error**: Buffer stall or missing encryption key (`fatal: true`). Destroy the player instance and mount the next queued fallback stream. --- -## Client Fallback Queue Strategy +## Client Fallback Strategy -Always treat streaming candidate resolution as a prioritized queue rather than a single static link: +Treat stream candidates as a prioritized queue rather than a single static link: -### Queue Priority Assignment +1. **Mount First Candidate**: Mount the first verified source that arrives over SSE. +2. **Queue Subsequent Sources**: Push subsequent incoming `source` events into a fallback array. +3. **Capture Timestamp on Error**: If a fatal error occurs, record `video.currentTime`. +4. **Teardown & Reconnect**: Call `hls.destroy()`, dequeue the next candidate, mount it, and seek back to the saved timestamp once metadata loads. -| Candidate Stream | Player State | Fallback Precedence | -| :--- | :--- | :--- | -| **Candidate 1** (`vidlink`) | **Active Playback** | Mounted into HLS.js or ExoPlayer on arrival. | -| **Candidate 2** (`vixsrc`) | **Standby Backup** | Enqueued as Priority #1 fallback stream. | -| **Candidate 3** (`cinecat`) | **Standby Backup** | Enqueued as Priority #2 fallback stream. | +--- -### Recovery Sequence on Stream Stall -1. **Error Interception**: Player detects a fatal network or decode event (`data.fatal === true`). -2. **Timestamp Preservation**: Record current playback offset (e.g. `currentTime = 142.5s`). -3. **Buffer Teardown**: Call `hls.destroy()` or `player.release()` to release media pipelines and decoders. -4. **Queue Advancement**: Dequeue the next available verified candidate from the standby queue. -5. **Seamless Seek**: Mount the fallback source and seek immediately to the preserved timestamp upon `loadedmetadata`. - -### Implementing Fallback Recovery in JavaScript +## Implementation Example ```javascript function attachHlsPlayer(videoElement, candidate, fallbackQueue) { @@ -57,15 +45,11 @@ function attachHlsPlayer(videoElement, candidate, fallbackQueue) { hls.on(Hls.Events.ERROR, (event, data) => { if (!data.fatal) return; - console.warn(`Encountered fatal error on ${candidate.source}:`, data.type); - switch (data.type) { case Hls.ErrorTypes.NETWORK_ERROR: - console.log("Attempting network recovery..."); hls.startLoad(); break; case Hls.ErrorTypes.MEDIA_ERROR: - console.log("Attempting media recovery..."); hls.recoverMediaError(); break; default: @@ -73,7 +57,6 @@ function attachHlsPlayer(videoElement, candidate, fallbackQueue) { if (fallbackQueue.length > 0) { const nextCandidate = fallbackQueue.shift(); const lastTime = videoElement.currentTime; - console.warn(`Switching to fallback candidate: ${nextCandidate.label}`); attachHlsPlayer(videoElement, nextCandidate, fallbackQueue); videoElement.addEventListener('loadedmetadata', () => { @@ -81,7 +64,7 @@ function attachHlsPlayer(videoElement, candidate, fallbackQueue) { videoElement.play(); }, { once: true }); } else { - showErrorOverlay("All available streaming providers have failed."); + showErrorOverlay("All available streaming providers failed."); } break; } @@ -93,20 +76,7 @@ function attachHlsPlayer(videoElement, candidate, fallbackQueue) { --- -## Client-Side Timeout Budgets +## Timeout Budgets -Never leave users hanging on an indefinite spinner. Implement a two-tiered timeout budget: - -1. **Initial Candidate Timeout (8–10 seconds)**: If no `type: "source"` event has arrived within 8 seconds, update the UI to indicate extended searching. -2. **Hard Timeout (20 seconds)**: If the stream has not completed or emitted a viable candidate within 20 seconds: - - Call `eventSource.close()`. - - Render a helpful empty-state UI with a "Retry" button or an option to change the server URL. - ---- - -## Decoupled Subtitle Fallback - -Subtitles originate from independent subtitle repositories (e.g. OpenSubtitles, SubDL). If a subtitle track fails to load: -- The video playback must continue uninterrupted. -- Log a warning in the console. -- Offer the viewer an in-player menu to toggle alternative subtitle providers or upload a local `.srt`/`.vtt` file. +- **First Candidate Timeout (8–10s)**: If no source event arrives within 8 seconds, inform the user that extended search is underway. +- **Hard Abort Timeout (20–25s)**: If no viable source is verified before the watchdog timer expires, close the connection and display an empty state with a retry button. diff --git a/index.html b/index.html index 43339c9..e46cde1 100644 --- a/index.html +++ b/index.html @@ -127,20 +127,7 @@ - - - + @@ -823,6 +810,7 @@ + diff --git a/products/go.md b/products/go.md index 509474b..0ff4299 100644 --- a/products/go.md +++ b/products/go.md @@ -2,105 +2,83 @@

The native Android mobile client for the Vyla ecosystem, combining hardware-accelerated shaders, automated runtime management, and mobile streaming.

-Vyla Go mobile streaming application interface +Vyla Go mobile application ## Overview -**Vyla Go** brings the power of the Vyla media ecosystem directly to Android smartphones and tablets. Built using **Tauri v2 Mobile**, Vyla Go delivers a fluid, responsive touch experience backed by native hardware acceleration and custom WebGL shaders. - -Designed for mobile reliability on varying cellular and Wi-Fi networks, Vyla Go automatically coordinates local resource extraction, service fallbacks, and remote update fetching without requiring constant manual APK re-installations. +**Vyla Go** brings the Vyla media ecosystem to Android phones and tablets. Built with **Tauri v2 Mobile**, Vyla Go delivers a responsive touch interface with WebGL hardware shaders and background playback support. --- ## Downloads -Official APK packages are published on the [Vyla Go GitLab Releases](https://gitlab.com/vyla-entertainment/go/-/releases): +Official APKs are available on [GitLab Releases](https://gitlab.com/vyla-entertainment/go/-/releases): -| Package | Target Architectures | Compatibility | Download Link | -| :--- | :--- | :--- | :--- | -| **Universal APK** | `arm64-v8a`, `armeabi-v7a`, `x86_64` | Android 7.0+ (API 24+) | [Download Universal APK](https://gitlab.com/vyla-entertainment/go/-/releases) | -| **ARM64 APK** | `aarch64` | Modern 64-bit Android Devices | [Download ARM64 APK](https://gitlab.com/vyla-entertainment/go/-/releases) | +- **[Universal APK](https://gitlab.com/vyla-entertainment/go/-/releases)**: Supports `arm64-v8a`, `armeabi-v7a`, and `x86_64` on Android 7.0+ (API 24+). +- **[ARM64 APK](https://gitlab.com/vyla-entertainment/go/-/releases)**: Optimized for modern 64-bit Android devices. --- ## Key Features -- **Tauri v2 Mobile Architecture**: Native Rust-backed Android application layer with secure Chromium WebView rendering. -- **Hardware-Accelerated WebGL Shaders**: Real-time dynamic glassmorphism, responsive ambient backdrops, and fluid gesture navigation. -- **Automated Resource Management**: Downloads and unpacks core service updates directly from official release channels, keeping scraper definitions up to date. -- **Low-Latency Mobile Playback**: Supports HLS and direct stream resolution with adaptive mobile bitrate handling. +- **Tauri v2 Mobile**: Native Rust Android layer with secure Chromium WebView rendering. +- **WebGL Hardware Shaders**: Dynamic backdrops and smooth gesture animations. +- **Automated Resource Updates**: Fetches and applies runtime payload updates directly from release channels without requiring full APK reinstalls for minor script updates. +- **Low-Latency Streaming**: Adaptive mobile bitrate switching with background audio playback. --- ## Building from Source ### Prerequisites -Before compiling Vyla Go, ensure your development environment has: -- **Node.js**: v20 or newer -- **Rust & Cargo**: Latest stable toolchain -- **Android Studio**: Android SDK & NDK (v29+) -- **Cross-Compilation Targets**: - +- Node.js 20+ +- Rust & Cargo +- Android Studio with Android SDK & NDK (API 29+) + +Add cross-compilation targets: ```bash rustup target add aarch64-linux-android x86_64-linux-android ``` ### Build Commands - ```bash -# 1. Install project dependencies npm install - -# 2. Package the runtime update payload npm run build:payload - -# 3. Compile the release APKs npm run build:apk ``` -The compiled release packages are output to: +Output APK location: ``` src-tauri/gen/android/app/build/outputs/apk/universal/release/app-universal-release.apk ``` --- -## Developer & Debugging Guide (ADB) +## Debugging with ADB -The Vyla Go repository provides complete ADB integration for debugging, log collection, and direct device installation: - -### Streaming Device Logs -Monitor the application logs in real time via ADB: +### Stream Logs ```powershell -# Stream live application logs tagged VylaGo & "$env:LOCALAPPDATA\Android\Sdk\platform-tools\adb.exe" logcat -s VylaGo +``` -# Clear the log buffer and stream fresh output +Clear and re-stream: +```powershell & "$env:LOCALAPPDATA\Android\Sdk\platform-tools\adb.exe" logcat -c & "$env:LOCALAPPDATA\Android\Sdk\platform-tools\adb.exe" logcat -s VylaGo ``` ### Crash Diagnostics -Inspect unhandled exceptions, native SIGSEGV errors, and runtime failures: ```powershell & "$env:LOCALAPPDATA\Android\Sdk\platform-tools\adb.exe" logcat -d | Select-String "VylaGo|AndroidRuntime|FATAL" ``` -### Direct Device Installation -Install your newly built APK directly to a connected USB or Wi-Fi debug device: +### Install to Connected Device ```powershell & "$env:LOCALAPPDATA\Android\Sdk\platform-tools\adb.exe" install -r "src-tauri\gen\android\app\build\outputs\apk\universal\release\app-universal-release.apk" ``` -### Resetting App State -To completely terminate and purge cached app state: +### Reset App State ```powershell & "$env:LOCALAPPDATA\Android\Sdk\platform-tools\adb.exe" shell am force-stop com.vyla.go & "$env:LOCALAPPDATA\Android\Sdk\platform-tools\adb.exe" shell pm clear com.vyla.go ``` - -### Fixing Emulator DNS Timeouts -When running Android emulators that fail to reach remote release endpoints: -```powershell -& "$env:LOCALAPPDATA\Android\Sdk\platform-tools\adb.exe" shell settings put global private_dns_mode off -``` diff --git a/products/home.md b/products/home.md index 0ea24e1..8d4604c 100644 --- a/products/home.md +++ b/products/home.md @@ -2,75 +2,51 @@

The native desktop control center and player runtime for Windows, macOS, and Linux built on Tauri v2 and an embedded Node.js sidecar.

-Vyla Home desktop application preview displaying streaming interface +Vyla Home desktop application preview ## Overview -**Vyla Home** is the flagship desktop application of the Vyla ecosystem. Engineered for performance and privacy, Vyla Home packages the entire Vyla streaming runtime into a lightweight native shell using **Tauri v2** and an embedded Node.js sidecar process. - -Instead of running heavy web browsers with excessive RAM overhead, Vyla Home leverages system-native WebViews (WebView2 on Windows, WebKit on macOS/Linux), ensuring instant boot times, hardware-accelerated video decoding, and tiny background resource footprints. +**Vyla Home** is the desktop client for the Vyla ecosystem. Built with **Tauri v2** and an embedded Node.js sidecar process, Vyla Home uses native system WebViews (WebView2 on Windows, WebKit on macOS/Linux) for fast startups and hardware-accelerated video decoding with minimal memory usage. --- ## Downloads -Official binary releases are published directly to the [Vyla Home GitLab Releases](https://gitlab.com/vyla-entertainment/home/-/releases): +Binary packages are available on [GitLab Releases](https://gitlab.com/vyla-entertainment/home/-/releases): -| Platform | Package Format | Architecture | Download Link | -| :--- | :--- | :--- | :--- | -| **Windows** | Setup Installer (`.exe`) / Portable | x86_64 (64-bit) | [Download for Windows (.exe)](https://gitlab.com/vyla-entertainment/home/-/releases) | -| **macOS** | Disk Image (`.dmg`) | Universal (Apple Silicon & Intel) | [Download for macOS (.dmg)](https://gitlab.com/vyla-entertainment/home/-/releases) | -| **Linux** | Source Build / Flatpak (in progress) | x86_64, aarch64 | [Build from Source](#linux-build-guide) | - -:::callout-info -When launching Vyla Home for the first time, the application will automatically perform a self-check, initialize local caches, and establish secure RPC connections. -::: +- **Windows**: [Download Setup Installer / Portable (.exe)](https://gitlab.com/vyla-entertainment/home/-/releases) (x86_64) +- **macOS**: [Download Disk Image (.dmg)](https://gitlab.com/vyla-entertainment/home/-/releases) (Universal: Apple Silicon & Intel) +- **Linux**: Build from source using the steps below. --- -## Architectural Implementation +## Architecture -Vyla Home operates via a dual-process architecture: +- **Tauri Main Process (Rust)**: Manages window state, system tray icons, native menus, and hosts the WebView. +- **Stdio IPC**: Bi-directional JSON-RPC stream passing messages between Rust and the Node.js sidecar over `stdin` and `stdout`. +- **Node.js Sidecar**: Runs `ServiceManager` for local/remote failover, verifies update signatures via `UpdateClient`, manages Discord Rich Presence, and caches local media metadata. -| Process Layer | Tech Stack | Responsibilities & Capabilities | -| :--- | :--- | :--- | -| **Tauri Main Process** | Rust | Manages native OS window lifecycle, system tray icons, native menus, and hosts the secure WebView renderer. | -| **Inter-Process Channel** | Stdio IPC | Bi-directional JSON-RPC stream communicating over standard input and standard output (`stdin` / `stdout`). | -| **Node.js Sidecar Process** | Node.js (`main.js`) | Orchestrates `ServiceManager` for local/remote fallback, verifies update cryptographic signatures via `UpdateClient`, manages Discord Rich Presence, and handles local cached data. | +### Storage Locations +- **Windows**: `%APPDATA%\vyla-home\vyla-home-files\` +- **macOS**: `~/Library/Application Support/vyla-home/vyla-home-files/` +- **Linux**: `~/.local/share/vyla-home/vyla-home-files/` -### File Locations & Directory Structure -Vyla Home stores its configuration, cryptographic keys, cached catalogs, and logs in standard operating system directories: - -| OS | Default Storage Path | -| :--- | :--- | -| **Windows** | `%APPDATA%\vyla-home\vyla-home-files\` | -| **macOS** | `~/Library/Application Support/vyla-home/vyla-home-files/` | -| **Linux** | `~/.local/share/vyla-home/vyla-home-files/` | - -### Diagnostics & Logs -If you encounter runtime issues, inspect the sidecar debug log: +### Sidecar Logs - **Windows**: `%APPDATA%\vyla-home\vyla-home-files\logs\node-debug.log` - **macOS/Linux**: `/logs/node-debug.log` --- -## Windows Troubleshooting: WebView2 Runtime +## Windows Troubleshooting -On Windows systems, Vyla Home utilizes Microsoft's Evergreen WebView2 runtime. If your installation encounters a `WebView2 runtime initialization error`: - -1. Ensure the Microsoft Edge WebView2 Evergreen Runtime is installed from [Microsoft's official site](https://developer.microsoft.com/en-us/microsoft-edge/webview2/). -2. For portable or standalone deployments, verify that `WebView2Loader.dll` exists in the `bin/` directory adjacent to the binary: - -```bash -vyla-home\bin\WebView2Loader.dll -``` +If you encounter a `WebView2 runtime initialization error`: +1. Install the Microsoft Edge WebView2 Evergreen Runtime from Microsoft. +2. For portable installs, confirm `WebView2Loader.dll` is present in the `bin/` directory adjacent to the executable. --- ## Linux Build Guide -To build and run Vyla Home natively on Linux distributions (such as Fedora, Ubuntu, Debian, or Arch): - ### 1. Install System Dependencies :::code-group @@ -106,20 +82,11 @@ source "$HOME/.cargo/env" ### 3. Clone and Build ```bash -# Clone the repository git clone https://gitlab.com/vyla-entertainment/home.git vyla-home cd vyla-home - -# Install Node dependencies npm install - -# Package runtime payload npm run build:payload - -# Launch in developer mode npm run dev - -# Or compile production binary npm run build ``` @@ -127,30 +94,14 @@ npm run build ## Developer Workflows -The Vyla Home repository includes specialized scripts for continuous development and release management: - ```bash -# Start the full application in development mode with hot reload npm run dev -``` - -```bash -# Package the local application payload into update-payload.zip npm run build:payload -``` - -```bash -# Test the UI shell with a simulated test harness npm run dev -- -- --env VYLA_TEST_UI=1 -``` - -```bash -# Compile and package a full production installer release npm run release:full ``` -### Resolving File Locks (OS Error 32) -If a hung process locks the binary during development on Windows: +If a hung process locks the binary during Windows development: ```powershell Stop-Process -Name "vyla-home", "node", "cargo" -Force -ErrorAction SilentlyContinue ``` diff --git a/products/player.md b/products/player.md index bd26ffb..ca0433a 100644 --- a/products/player.md +++ b/products/player.md @@ -1,71 +1,38 @@ # Building a Custom Player -

Architectural principles, format handling, and engineering guidelines for building resilient video players backed by Vyla infrastructure.

+

Architectural principles, format handling, and engineering guidelines for building video players backed by Vyla infrastructure.

## Overview -In the Vyla ecosystem, you are never locked into an official frontend. Vyla provides the discovery, resolution, and proxy layers; your application owns the player experience. Whether you are building a custom web portal, desktop client, or mobile app, this guide covers the core engineering patterns required for a robust player. +Vyla handles discovery, scraping, and proxying; your app owns the player. Whether building a web player, desktop shell, or mobile UI, this guide outlines the core playback patterns. --- -## Integration Boundaries +## Integration Paths -Choose your integration point based on your architecture: - -| Architecture | Integration Point | Data Flow | Best For | -| :--- | :--- | :--- | :--- | -| **Node.js Backend** | **Vyla SDK Directly** | `sdk.getStream()` in-process | Applications with full backend control, custom authentication, and server-side session tracking. | -| **Browser / Mobile** | **Stream API Gateway** | SSE `/movie` or `/tv` over HTTP | Web applications, smart TV frontends, or lightweight mobile clients requiring an HTTP/SSE source feed. | +- **Node.js Backends**: Use the Vyla SDK directly in-process via `sdk.getStream()`. Ideal for custom authentication and server-side tracking. +- **Web / Mobile / TV**: Connect to the Stream API gateway via HTTP/SSE (`/movie` or `/tv`). Ideal for frontend players requiring a live streaming feed. --- -## Playback Formats: HLS vs Direct Video +## Playback Formats -Resolved candidate streams come in two primary container types: - -1. **HLS Streams (`type: "hls"`)**: - - Master M3U8 playlists containing multiple bitrate/resolution variants. - - Proxied through Stream API (`/api?url=...`), which automatically rewrites chunk URLs and AES-128 encryption key URIs. - - Requires native HLS support (Safari on macOS/iOS) or a JavaScript HLS MSE library such as [HLS.js](https://github.com/video-dev/hls.js/) in modern browsers. -2. **Direct Media Files (`type: "mp4"`)**: - - Progressive MP4 or MKV streams. - - Proxied with HTTP Range header forwarding (`206 Partial Content`), allowing smooth scrubbing and seeking. - - Directly assignable to the HTML5 `