This commit is contained in:
2026-11-15 17:34:41 -08:00
parent bc7c89b528
commit 46152a464d
37 changed files with 1413 additions and 3919 deletions

View File

@@ -48,7 +48,7 @@ Ensure the Microsoft Edge WebView2 Evergreen Runtime is installed. If running a
## Policies & Community
### How do rights holders request removal of a source?
Rights holders can submit source removal requests directly to our team. We promptly review and disable scrapers for requested domains. See our [DMCA Policy](/misc/project/dmca) for contact instructions.
Rights holders can submit source removal requests directly to our team. We promptly review and disable scrapers for requested domains. See our [DMCA Policy](../misc/project/DMCA.md) for contact instructions.
### How can I contribute to Vyla?
We welcome code contributions, documentation improvements, and bug reports on [GitLab](https://gitlab.com/vyla-entertainment). Check out the [Contributing Guide](/sdk/vyla-sdk/contributing) to learn how to author and submit new provider scrapers.
We welcome code contributions, documentation improvements, and bug reports on [GitLab](https://gitlab.com/vyla-entertainment). Check out the [Contributing Guide](../sdk/vyla-sdk/contributing.md) to learn how to author and submit new provider scrapers.

View File

@@ -1,86 +0,0 @@
# Ecosystem Glossary
<p class="page-description">Authoritative definitions for technical terms, protocols, and architectural concepts across the Vyla ecosystem.</p>
## A
### AES-128 Encryption
A symmetric key cipher frequently used in HLS streaming. The playlist references an encryption key endpoint (`#EXT-X-KEY:METHOD=AES-128,URI="..."`). Stream API proxies and rewrites these key URIs to ensure playback permissions and headers match the viewer's session.
---
## C
### Cluster Primary & Worker
Node.js architecture utilized by Stream API. The **Primary** master process allocates CPU affinity, coordinates IPC messaging, and supervises workers. **Workers** handle inbound HTTP client requests, parse streams, and query upstream hosts concurrently.
---
## E
### ExoPlayer (Media3)
Google's high-performance, customizable media player library for Android. Used by Vyla TV to render adaptive 4K/HDR HLS streams with hardware acceleration.
---
## F
### Fallback Priority Queue
A client-side architecture where candidate video streams emitted by Stream API are queued in memory. If the currently playing stream crashes or drops offline, the player immediately mounts the next candidate in the queue without interrupting the viewer.
---
## H
### HLS (HTTP Live Streaming)
An adaptive bitrate streaming communications protocol developed by Apple. Video is divided into a sequence of small HTTP-based file chunks (.ts or .m4s) indexed by a master `.m3u8` playlist.
### HLS.js
A JavaScript library that implements an HLS client using HTML5 video and Media Source Extensions (MSE). Used by custom web players to play Vyla HLS streams in browsers lacking native HLS support.
---
## J
### Jitter Staggering
A randomized delay (0 to 800ms) injected before scraper network requests fire. Prevents dozens of concurrent scrapers from triggering upstream Cloudflare or DDoS rate limits at the same millisecond.
---
## M
### M3U8 Playlist
A UTF-8 encoded text file representing an HLS playlist. Stream API intercepts and rewrites master and media M3U8 playlists so that chunk and encryption key URLs route through the proxy with valid CORS headers.
---
## P
### Progressive Streaming
A delivery pattern where metadata and media candidates are emitted to client players in real time over Server-Sent Events (SSE) as each scraper finishes, rather than waiting for all scrapers to complete.
### Provider / Scraper
A self-contained JavaScript module in `@vyla-entertainment/sdk` (`src/sources/`) that queries an upstream video host, extracts stream URLs, and formats headers.
---
## S
### Server-Sent Events (SSE)
A standardized HTML5 server-to-client streaming technology over a persistent HTTP connection (`Content-Type: text/event-stream`). Used by Stream API `/movie` and `/tv` routes to emit `meta`, `source`, and `done` events.
### Sidecar Process
An architectural pattern used in Vyla Home where a secondary runtime process (Node.js) is bundled adjacent to the primary native application shell (Tauri Rust binary) to manage local services.
---
## T
### Tauri v2
A framework for building tiny, ultra-fast native applications for all major desktop and mobile platforms using web frontends and Rust backends. Vyla Home and Vyla Go are built on Tauri v2.
### TMDB (The Movie Database)
A community-built movie and television database. Vyla standardizes all movie and TV series queries on numeric TMDB IDs.
### TS Segment De-Masking (120-Byte Stripping)
A de-obfuscation routine implemented in Stream API. Certain CDNs disguise video chunks by prepending a 120-byte fake image header (PNG, JPEG, TikTok CDN). Stream API removes these 120 bytes, restoring valid MPEG-TS video for media players.

View File

@@ -1,94 +0,0 @@
# Troubleshooting & Diagnostics
<p class="page-description">Step-by-step diagnostic workflows and resolutions for common issues across Vyla Home, Vyla Go, Vyla TV, Stream API, and the SDK.</p>
## Desktop: Vyla Home
### 1. Windows: "WebView2 runtime initialization error"
- **Cause**: The Microsoft Edge WebView2 runtime is missing or corrupted on the host machine.
- **Resolution**:
1. Download and run the Evergreen Bootstrapper installer from [Microsoft's WebView2 page](https://developer.microsoft.com/en-us/microsoft-edge/webview2/).
2. If using portable builds, verify that `WebView2Loader.dll` exists in `bin\WebView2Loader.dll`.
### 2. Windows: "OS Error 32: File in use by another process"
- **Cause**: A previous Tauri, Node.js, or Cargo process is still running in the background and holding a file lock.
- **Resolution**: Terminate any dangling processes in PowerShell:
```powershell
Stop-Process -Name "vyla-home", "node", "cargo" -Force -ErrorAction SilentlyContinue
```
### 3. Linux: Build Fails with Missing WebKit or AppIndicator
- **Cause**: Linux requires native GTK3 and WebKit development headers.
- **Resolution**: Install required system packages:
- **Fedora**: `sudo dnf install webkit2gtk4.1-devel libappindicator-gtk3-devel librsvg2-devel`
- **Ubuntu/Debian**: `sudo apt install libwebkit2gtk-4.1-dev libayatana-appindicator3-dev librsvg2-dev`
### 4. Inspecting Node Sidecar Logs
If Vyla Home launches but media fails to resolve:
- **Windows**: Open `%APPDATA%\vyla-home\vyla-home-files\logs\node-debug.log`
- **macOS**: Open `~/Library/Application Support/vyla-home/vyla-home-files/logs/node-debug.log`
---
## Mobile: Vyla Go
### 1. Emulator DNS Timeouts when Connecting to GitLab
- **Cause**: Android emulators occasionally fail to resolve remote domains when private DNS is active.
- **Resolution**: Disable private DNS mode via ADB:
```powershell
& "$env:LOCALAPPDATA\Android\Sdk\platform-tools\adb.exe"
shell settings put global private_dns_mode off
```
### 2. Dumping Crash Logs from Device
To capture a full logcat dump of crash traces:
```powershell
& "$env:LOCALAPPDATA\Android\Sdk\platform-tools\adb.exe" logcat -d | Select-String "VylaGo|AndroidRuntime|FATAL"
```
### 3. Resetting Cached App Data
```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
```
---
## Living Room: Vyla TV
### 1. Build Fails during `assembleDebug`
- **Cause**: Incompatible Java Development Kit (JDK) or missing Android TV SDK platform.
- **Resolution**:
1. Ensure JDK 17 or JDK 21 is active: `java -version`.
2. Ensure Android TV API level 26 or higher is installed via Android Studio SDK Manager.
### 2. Video Stalls or Fails to Play on Fire TV
- **Cause**: Hardware codec mismatch or network buffer underrun.
- **Resolution**:
1. Inside the player, press the Down button on your D-pad to open the stream switcher.
2. Select an alternative provider (e.g. switch from an adaptive HLS stream to a direct 1080p stream).
---
## Backend: Stream API
### 1. SSE Events Delayed or Arriving All at Once
- **Cause**: The reverse proxy (Nginx, Cloudflare, Caddy) is buffering chunked responses.
- **Resolution**:
1. In Nginx, ensure `proxy_buffering off;` and `proxy_cache off;` are configured in your `location` block.
2. In Cloudflare, ensure response buffering is disabled for your streaming subdomain.
### 2. `EADDRINUSE: address already in use :::7860`
- **Cause**: A previous Stream API instance is already bound to port 7860.
- **Resolution**:
```bash
lsof -i :7860
kill -9 <PID>
```
### 3. TMDB API Warnings in Console
- **Warning**: `Warning: TMDB_API_KEY not set, imdb-required sources will be unavailable`
- **Resolution**: Add `TMDB_API_KEY=your_key` to your `.env` file and restart the service.