Metadata-Version: 2.4
Name: videx-local
Version: 1.0.9
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 interface bundled with the local app. 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 app`.
3. Paste a URL, preview it, and queue the authorized media locally.

The public website at [videx-app.vercel.app](https://videx-app.vercel.app/) provides 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). The installed Videx app provides the actual interface.

## 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 app
```

### Linux

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

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 app
```

Videx starts a local service on `127.0.0.1:8765` and opens the interface bundled with Videx. The local app uses a secure session cookie and same-origin requests, so the public website is not part of the download path.

`videx web` remains a compatibility alias for `videx app`. Developers who need the older hosted PWA flow can run `videx web --hosted` explicitly.

The local service refuses non-loopback binding. The Vercel site provides documentation and downloads only.

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).
