Metadata-Version: 2.4
Name: videx-local
Version: 1.0.7
Summary: A private, local-first download manager powered by yt-dlp.
Author: videx contributors
License-Expression: MIT
Project-URL: Homepage, https://videx-app.vercel.app/
Project-URL: Repository, https://github.com/ws0x/Videx
Project-URL: Issues, https://github.com/ws0x/Videx/issues
Keywords: yt-dlp,youtube,downloader,cli,tui,ffmpeg,video,playlist
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>=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

# Videx

> A private local video and audio download manager. Use it from your terminal or browser while your media and credentials stay on your machine.

Videx is a free, MIT-licensed local download manager for video, audio, playlists, and subtitles. It provides a guided CLI, scriptable commands, a persistent download queue, and a browser app connected to a companion running only on your computer. Videx uses yt-dlp and FFmpeg as local engine dependencies.

## Why Videx

- Local by design. Downloads, URLs, cookies, history, and media never pass through a Videx server.
- Friendly defaults. Paste a URL and choose a quality without learning yt-dlp flags.
- Powerful when needed. Playlists, audio extraction, subtitles, clips, SponsorBlock, retries, presets, and batch jobs remain available.
- One engine. The CLI and browser use the same validated plans and SQLite queue.
- No account, subscription, cloud storage, analytics, or advertisements.

Videx supports many compatible sources through its local engine. Compatibility can change as source sites change. DRM-protected material, bypassing access restrictions, and unauthorized copying are not supported.

Use Videx only for media you own or are authorized to save. Videx does not grant rights to third-party content or override a platform's terms.

## Start in three steps

1. Install Videx for your computer.
2. Run `videx web`.
3. Paste a URL, preview it, and queue the authorized media locally.

The browser interface is hosted at [videx-app.vercel.app](https://videx-app.vercel.app/). Read the [install guide](https://videx-app.vercel.app/download.html), [privacy statement](https://videx-app.vercel.app/privacy.html), [compatibility guidance](https://videx-app.vercel.app/compatibility.html), and [troubleshooting guide](https://videx-app.vercel.app/troubleshooting.html).

## Install

### Windows

Review and run [install.ps1](install.ps1), or use this PowerShell command:

```powershell
irm https://raw.githubusercontent.com/ws0x/Videx/main/install.ps1 | iex
```

The release binary is currently unsigned, so Windows SmartScreen may show a warning. Every release includes a SHA-256 checksum, and the installer verifies it before installation.

Install FFmpeg when prompted, then open a new terminal:

```powershell
videx doctor
videx web
```

### Linux

```bash
curl -fsSL https://raw.githubusercontent.com/ws0x/Videx/main/install.sh | bash
videx doctor
videx web
```

For an optional user service:

```bash
VIDEX_INSTALL_SERVICE=1 curl -fsSL https://raw.githubusercontent.com/ws0x/Videx/main/install.sh | bash
```

### Python

```bash
python -m pip install videx-local
```

Python 3.10 or newer is required. FFmpeg is required for merging streams, conversion, thumbnails, and subtitle embedding. aria2c is optional.

## Browser app

Run:

```bash
videx web
```

Videx starts an authenticated companion on `127.0.0.1:8765` and opens the static app hosted on Vercel. The connection token is placed in the URL fragment, which browsers do not send to the web host. The app talks directly to the loopback companion.

Chrome may ask for Local Network Access permission. This permission only allows the static page to reach the Videx companion on your computer. If a browser or policy blocks that connection, run `videx web --local` to open the identical PWA directly from the companion.

The companion refuses non-loopback binding. Requests require a local bearer token and an approved web origin. Set `VIDEX_WEB_ORIGINS` to a comma-separated list when developing a fork.

The browser app supports:

- URL preview and available quality discovery
- Video and audio downloads
- Playlist, subtitle, clip, SponsorBlock, retry, and archive controls
- Live queue progress
- Cancellation, retry, removal, and opening output folders
- Exact output-file downloads
- Offline app-shell caching

## CLI examples

```bash
videx
videx https://example.com/video -q 1080
videx https://example.com/video --audio -f mp3
videx add https://example.com/video -q 720
videx jobs --json
videx job JOB_ID --json
videx cancel JOB_ID
videx formats https://example.com/video
videx daemon start
videx doctor --json
videx update
```

Run `videx --help` or `videx <command> --help` for the complete option list.

## Configuration and local data

Configuration precedence is CLI flags, environment variables, config file, then defaults.

- Config: `~/.config/videx/config.toml`
- Data and queue: `~/.local/share/videx`
- Default downloads: `~/Downloads/videx`

Override these with `VIDEX_CONFIG_DIR`, `VIDEX_DATA_DIR`, and `VIDEX_OUTPUT_DIR`.

Videx checks GitHub Releases at most once every 24 hours when interactive mode starts. It only displays a notice. It never installs an update without approval. Set `VIDEX_NO_UPDATE_CHECK=1` to disable this request.

## Development

```bash
python -m venv .venv
# Windows: .venv\Scripts\activate
# Linux: source .venv/bin/activate
pip install -e ".[dev,web]"
pytest
ruff check videx tests
mypy videx

cd webui
npm ci
npm run build
```

Required tests never contact media websites. Network extractors are mocked or served by local fixtures.

See [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md), [PRIVACY.md](PRIVACY.md), [ROADMAP.md](ROADMAP.md), and the [architecture](docs/ARCHITECTURE.md), [API](docs/API.md), and [release](docs/RELEASING.md) guides.

## License

MIT. See [LICENSE](LICENSE).
