Metadata-Version: 2.4
Name: videx-local
Version: 1.2.3
Summary: The ultra-fast, private, local-first media workstation and educational course archival engine.
License-Expression: MIT
Project-URL: Homepage, https://videx.binhakim.dev/
Project-URL: Repository, https://github.com/ws0x/Videx
Project-URL: Issues, https://github.com/ws0x/Videx/issues
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: yt-dlp[default]<2027.0.0,>=2026.7.4
Requires-Dist: rich>=13.0.0
Requires-Dist: questionary>=2.0.0
Requires-Dist: fastapi>=0.110.0
Requires-Dist: uvicorn[standard]>=0.29.0
Requires-Dist: tomli>=2.0.1; python_version < "3.11"
Provides-Extra: dev
Requires-Dist: ruff>=0.6.0; extra == "dev"
Requires-Dist: mypy>=1.10.0; extra == "dev"
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Requires-Dist: httpx>=0.27.0; extra == "dev"
Requires-Dist: pip-audit>=2.7.0; extra == "dev"
Requires-Dist: setuptools>=83.0.0; extra == "dev"
Provides-Extra: web
Dynamic: license-file

<div align="center">

# ⚡ Videx

**The Ultra-Fast, Private, Local-First Media Download Engine & Educational Course Archiver**

[![CI Build](https://img.shields.io/badge/build-passing-brightgreen?style=for-the-badge&logo=githubactions&logoColor=white)](https://github.com/ws0x/Videx/actions)
[![Tests Coverage](https://img.shields.io/badge/coverage-80.92%25-success?style=for-the-badge&logo=pytest&logoColor=white)](https://github.com/ws0x/Videx)
[![Python Version](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](LICENSE)
[![Release](https://img.shields.io/github/v/release/ws0x/Videx?style=for-the-badge&logo=github&color=purple)](https://github.com/ws0x/Videx/releases)
[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey?style=for-the-badge&logo=linux&logoColor=white)](https://github.com/ws0x/Videx/releases)

<p align="center">
  <a href="#-quick-start">Quick Start</a> •
  <a href="#-key-features--problems-solved">Features</a> •
  <a href="#-installation-options">Installation</a> •
  <a href="#-user-flows">User Flows</a> •
  <a href="#-course-studio--curriculum-archival">Course Studio</a> •
  <a href="#-cli-command-suite">CLI Suite</a> •
  <a href="#-security--privacy-invariants">Security</a>
</p>

</div>

---

## 🔍 Overview & What is Videx?

**Videx** is an ultra-fast, local-first media workstation and structured educational course archiver. It bridges the gap between raw CLI extractors (`yt-dlp`, `aria2c`, `ffmpeg`) and modern desktop tools by offering an interactive **Course Studio DAG explorer**, a **local Web Companion interface**, an **isolated Browser Extension**, and a **background Daemon Queue**.

Whether you want to download compatible videos or playlists, inspect an authorized course, preserve public courseware, or generate **Plex / Jellyfin / Kodi NFO metadata**, Videx does it entirely on your own machine. Provider depth varies and is documented in the [provider capability matrix](docs/PROVIDER-CAPABILITY-MATRIX.md).

### 🌟 Why Choose Videx Over Other Tools?

| Feature / Capability | Videx | Generic YT-DLP CLI | Web Downloaders / Cloud Services |
| :--- | :---: | :---: | :---: |
| **Local-First & Zero Telemetry** | 🛡️ **100% Private** | 🛡️ 100% Private | ❌ Sells data / Tracks IP |
| **Evidence-qualified URL Auto-Routing** | ✅ **One CLI workflow for compatible sources** | ⚠️ Complex flags required | ⚠️ Single platform only |
| **Interactive Course Studio** | ✅ **Visual DAG Tree & Section picker** | ❌ No GUI or syllabus viewer | ❌ None |
| **Multi-Connection Acceleration** | ⚡ **Built-in `aria2c` multi-socket** | ⚠️ Manual configuration | ❌ Server bandwidth throttled |
| **Anti-Throttling & 429 Retry** | 🔄 **Jittered Exponential Backoff** | ⚠️ Basic retries | ❌ Failures & bans |
| **Plex / Jellyfin / Kodi NFO Metadata** | 🎬 **Automatic `.nfo` & Season mapping** | ❌ Manual post-processing | ❌ None |
| **Credential Security** | 🔒 **Fail-Closed Local Session Handling** | ⚠️ Plaintext disk cookies | ⚠️ Plaintext credentials in cloud |
| **Background Daemon & Web Companion** | 🖥️ **Integrated Web UI & REST API** | ❌ None | ⚠️ Cloud-hosted only |

---

## ⚡ Key Features & Problems Solved

### 1. 🚀 Saturated Network Speed (`aria2c` Engine)
* **Problem**: Single-stream HTTP downloads throttle bandwidth on high-speed gigabit connections.
* **Videx Solution**: Automatically leverages `aria2c` multi-connection segmenting (up to 16 concurrent TCP connections per stream) with transparent fallback to multi-threaded parallel engines, saturating your downstream bandwidth while preserving maximum stream fidelity.

### 2. 📚 Full-Featured Educational Course Studio
* **Problem**: Downloading multi-chapter online courses requires scraping complex API tokens, leading to disorganized folders and missing subtitles.
* **Videx Solution**: Provider adapters for **Coursera**, **edX**, **MIT OCW**, and **Udemy**, with explicit access and evidence boundaries. MIT OpenCourseWare has a live public fixture; Udemy, Coursera, and edX remain evidence-gated for broader media claims. Where a provider exposes permitted media, view the syllabus, select modules or lectures, validate video streams, extract subtitles (`.vtt` / `.srt`), and generate Plex-ready directory structures.

### 3. 🎯 Universal Smart CLI
* **Problem**: Users are forced to remember different subcommands and flags for videos, playlists, music, or courses.
* **Videx Solution**: Run `videx <URL>` on a compatible source. Videx inspects the URL, routes it to the available extractor, prompts for quality/audio choices, and explains unsupported or authorization-required sources.

### 4. 🔒 Fail-Closed Privacy & Credential Security
* **Problem**: Other tools save authentication cookies in plaintext files or send session tokens to remote servers.
* **Videx Solution**: Browser-extension session handoffs stay strictly in ephemeral companion process memory (with a strict 120s TTL). An optional authorized Netscape `cookies.txt` upload is stored locally with restrictive permissions, referenced only by its job, and removed after use or bounded orphan cleanup. Neither path is sent to Videx servers or included in exported logs/manifests.

### 5. 🛡️ Resilient Anti-Throttling & Self-Healing
* **Problem**: Large downloads fail halfway through due to HTTP 429 (Too Many Requests) or 503 gateway drops.
* **Videx Solution**: Integrated jittered exponential backoff retries transient rate-limit errors safely across multiple cycles without breaking the pipeline.

---

## 🚀 Quick Start

### 1. Download Any Video or Playlist (CLI)
```bash
# Auto-detects URL, prompts for resolution, and downloads with maximum speed
videx https://www.youtube.com/watch?v=dQw4w9WgXcQ

# Force specific resolution or audio extraction
videx https://www.youtube.com/watch?v=dQw4w9WgXcQ -q 1080
videx https://www.youtube.com/watch?v=dQw4w9WgXcQ --audio -f mp3
```

### 2. Inspect & Download a Course
```bash
# View the complete hierarchical curriculum DAG in terminal
videx course tree https://ocw.mit.edu/courses/18-06-linear-algebra-spring-2010/

# Download the full course or specific modules
videx course get https://ocw.mit.edu/courses/18-06-linear-algebra-spring-2010/
videx course get https://ocw.mit.edu/courses/18-06-linear-algebra-spring-2010/ --sections "1,2"
# Download only item IDs copied from `course tree --json`
videx course get https://ocw.mit.edu/courses/18-06-linear-algebra-spring-2010/ --items "item_10,item_11" --no-subs
```

### 3. Launch the Local Web Companion UI
```bash
videx app
```
*Opens `http://127.0.0.1:8765` in your browser with interactive progress tracking and the **Course Studio**.*

---

## 📦 Installation Options

Choose the installation method that fits your operating system and environment:

### Option 1: Standalone GitHub Release Binaries (Recommended)
Download pre-compiled, self-contained standalone executables from the [**GitHub Releases Page**](https://github.com/ws0x/Videx/releases/latest):

| Operating System | Binary Package | Architecture |
| :--- | :--- | :--- |
| **Windows** | [`videx-windows-x86_64.exe`](https://github.com/ws0x/Videx/releases/latest) | x86_64 / AMD64 |
| **macOS (Apple Silicon)** | [`videx-macos-arm64`](https://github.com/ws0x/Videx/releases/latest) | Apple Silicon (M1/M2/M3/M4) |
| **Linux** | [`videx-linux-x86_64`](https://github.com/ws0x/Videx/releases/latest) | x86_64 |
| **Browser Extension** | [`videx-extension.zip`](https://github.com/ws0x/Videx/releases/latest) | Chrome / Edge (MV3) |

The standalone macOS release currently targets Apple Silicon only. Intel Macs can
use the cross-platform Python package below or build Videx from source; a native
Intel release binary is not currently published.

---

### Option 2: Automated One-Liner Installers

#### Windows (PowerShell)
```powershell
irm https://raw.githubusercontent.com/ws0x/Videx/main/install.ps1 | iex
```
*Installs Videx, configures PATH, sets up Windows Start Menu shortcuts, and verifies binary checksums.*

#### macOS & Linux (Bash/Zsh)
```bash
curl -fsSL https://raw.githubusercontent.com/ws0x/Videx/main/install.sh | bash
```

*For Linux background daemon autostart (systemd user unit):*
```bash
VIDEX_INSTALL_SERVICE=1 curl -fsSL https://raw.githubusercontent.com/ws0x/Videx/main/install.sh | bash
```

---

### Option 3: Python Package via PIP (Cross-Platform)

```bash
# Install from PyPI
pip install --upgrade videx-local

# Or install with Web Companion and Developer extras
pip install "videx-local[web,dev]"
```

*Requirements: Python 3.10+ and [FFmpeg](https://ffmpeg.org/) installed on system PATH.*

---

### Option 4: Browser Extension Installation (Chrome / Edge / Brave)

1. Download [`videx-extension.zip`](https://github.com/ws0x/Videx/releases/latest) from Releases and unzip it.
2. Open your browser and navigate to `chrome://extensions` or `edge://extensions`.
3. Enable **Developer mode** (toggle in the top-right corner).
4. Click **Load unpacked** and select the unzipped `videx-extension` folder.
5. Pin Videx to your extension bar. In the first beta, the authenticated course workflow is limited to enrolled Udemy pages and connects to your local app.

---

## 🔄 User Flows: How to Use Videx

```mermaid
flowchart TD
    A([User Input / Action]) --> B{What do you want to download?}
    
    B -->|Single Video or Playlist| C[Option A: Universal CLI]
    B -->|Course with Modules| D[Option B: Course Studio]
    B -->|Browser Browsing| E[Option C: Browser Extension]
    B -->|Queue Many Jobs| F[Option D: Background Daemon]

    C --> G["Run: videx &lt;URL&gt;"]
    G --> H[Auto-routes format & saturates network with aria2c]

    D --> I["Run: videx app &rarr; 'Course Studio'"]
    I --> J[Explore syllabus DAG & check desired chapters &rarr; Download]

    E --> K[Click Videx Extension icon on an enrolled Udemy page]
    K --> L[One-click Handshake to Local Companion]

    F --> M["Run: videx add &lt;URL&gt;"]
    M --> N[Monitored in background via SQLite queue & SSE events]
```

### Flow 1: Universal CLI Flow (Fastest for Daily Media)
1. In your terminal, type `videx <URL>`:
   ```bash
   videx https://www.youtube.com/watch?v=2lAe1cqCOXo
   ```
2. Videx queries the source's available formats, displays clear resolution tiers, and downloads the selected audio/video pairing.

### Flow 2: Web Companion & Course Studio Flow
1. Launch the local companion: `videx app`.
2. Select the **"Course Studio"** tab.
3. Paste a course link from a provider listed in the [capability matrix](docs/PROVIDER-CAPABILITY-MATRIX.md).
4. Browse the interactive curriculum DAG tree. Uncheck any sections you don't need.
5. Click **"Download Selected Modules"**. Videx queues the chapters into the download engine and streams real-time progress bars.

### Flow 3: Browser Extension Authenticated Flow (Udemy beta)
1. Log into your account on Udemy in Chrome/Edge.
2. Open any enrolled course page and click the **Videx** extension icon.
3. Click **"Resolve This Udemy Course"**. The extension initiates a secure loopback handshake (`127.0.0.1:8765`).
4. The local companion receives the temporary session, loads the curriculum, and begins downloading your lectures with zero manual cookie exports required.

---

## 🎓 Course Studio & Curriculum Archival

Videx produces standardized, clean directory trees compatible with media servers like **Plex**, **Jellyfin**, and **Kodi**:

```text
📁 ~/Downloads/videx/Courses/
└── 📁 [Coursera] Deep Learning Specialization/
    ├── 📄 course_manifest.json          <-- Machine-readable export
    ├── 📄 tvshow.nfo                    <-- Plex/Jellyfin show metadata
    ├── 📁 Season 01 - Neural Networks and Deep Learning/
    │   ├── 📄 season.nfo
    │   ├── 🎬 S01E01 - Welcome to Deep Learning.mp4
    │   ├── 💬 S01E01 - Welcome to Deep Learning.en.vtt
    │   ├── 🎬 S01E02 - What is a Neural Network.mp4
    │   └── 💬 S01E02 - What is a Neural Network.en.vtt
    └── 📁 Season 02 - Improving Deep Neural Networks/
        └── ...
```

### Supported Educational Providers
* **Coursera**: Adapter implemented; authorized media fixture and output validation remain launch gates.
* **edX / Open edX**: Adapter implemented; authorized media fixture and output validation remain launch gates.
* **MIT OpenCourseWare (OCW)**: Public curriculum trees and media where permitted; fixture validation remains part of release evidence.
* **Udemy**: Authenticated course listing, curriculum resolution, multi-quality streams, and instructor subtitles where the authorized page exposes permitted media; full output proof remains a release gate.

---

## 💻 CLI Command Suite

```bash
# --- Diagnostics & Health ---
videx doctor                   # Run system diagnostics (FFmpeg, aria2c, network, disk)
videx doctor --fix             # Automatically install missing dependencies
videx support --json           # Emit a redacted support bundle and safe recovery commands
videx support --json --output support.json  # Save it to an existing directory
videx upgrade                  # Self-upgrade Videx binary in-place
videx update-engine            # Upgrade underlying extraction engine

# --- Single Downloads ---
videx <URL>                    # Universal interactive downloader
videx <URL> -q 1080            # Download in 1080p
videx <URL> --audio -f mp3     # Extract high-bitrate MP3
videx formats <URL>            # List all available video/audio streams

# --- Course Commands ---
videx course list-providers    # List supported platforms and auth capabilities
videx course tree <URL>        # Print curriculum hierarchy DAG
videx course get <URL>         # Download all modules
videx course get <URL> --sections "1,3,4"  # Download selected modules
videx course get <URL> --items "item_10,item_11"  # Download selected curriculum items
videx course verify <ARCHIVE>  # Check files, SHA-256 digests, partials, and media validity
videx course diff <ARCHIVE> --tree-file <REFRESHED_TREE_JSON>  # Review added, removed, and changed items without writing files
videx course repair <ARCHIVE>  # Retry missing assets, then verify again (auth may be required)

# --- Daemon & Queue Management ---
videx daemon start             # Start background download worker
videx daemon status            # Check daemon health and active worker count
videx add <URL> -q 1080        # Add job to daemon queue
videx jobs                     # View active and completed jobs
videx cancel <job_id>          # Cancel a running job
videx daemon stop              # Gracefully shut down daemon

# --- Shell Auto-Completions ---
videx completion bash > /etc/bash_completion.d/videx
videx completion zsh > "${fpath[1]}/_videx"
videx completion fish > ~/.config/fish/completions/videx.fish
videx completion powershell >> $PROFILE
```

---

## 🔒 Security & Privacy Invariants

1. **No External Servers**: Videx has no central analytics, telemetry, user tracking, or cloud infrastructure.
2. **Ephemeral In-Memory Tokens**: When authenticating through the browser extension, authentication cookies exist only in RAM with a 120-second TTL and are immediately purged. Optional local `cookies.txt` uploads are a separate, user-selected fallback and are removed after their job or bounded orphan cleanup.
3. **Safe Manifest Sanitization**: Exported metadata (`course_manifest.json`, `.nfo` files) always passes through `manifest_safe_url()` to strip sensitive tokens and query parameters.
4. **Local Loopback Isolation**: The local companion API binds strictly to `127.0.0.1` and enforces CORS origin whitelisting against browser extensions.

---

## 🛠️ Development & Contributing

Videx is written in Python 3.10+ (CLI & Backend) and TypeScript / Tailwind / Vite (Web Companion & Extension).

```bash
# 1. Clone repository
git clone https://github.com/ws0x/Videx.git
cd Videx

# 2. Setup virtual environment
python -m venv .venv
# On Windows: .venv\Scripts\activate
# On POSIX:   source .venv/bin/activate

# 3. Install development dependencies
pip install -e ".[dev,web]"

# 4. Run test suite & coverage (must pass >= 80% coverage)
pytest tests/ --cov=videx --cov-report=term-missing

# 5. Build WebUI & Browser Extension
python scripts/package_product.py
```

---

## 📄 License & Legal Notice

Distributed under the **MIT License**. See [`LICENSE`](LICENSE) for details.

*Disclaimer: Videx is an educational and archival tool designed to download and organize content you have explicit rights to access. Videx does not bypass DRM encryption, circumvent access-control protections, or crack paywalled media.*
