Videx

A private, local-first download manager powered by yt-dlp. 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.

Install

Windows

Review and run install.ps1, or use this PowerShell command:

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:

videx doctor
videx web

Linux

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

For an optional user service:

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

Python

python -m pip install "videx-local[web]"

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

Browser app

Run:

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

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

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, SECURITY.md, PRIVACY.md, ROADMAP.md, and the architecture, API, and release guides.

License

MIT. See LICENSE.