███╗   ███╗ ██████╗ ██╗   ██╗██╗███████╗██╗  ██╗
████╗ ████║██╔═══██╗██║   ██║██║██╔════╝╚██╗██╔╝
██╔████╔██║██║   ██║██║   ██║██║█████╗   ╚███╔╝
██║╚██╔╝██║██║   ██║╚██╗ ██╔╝██║██╔══╝   ██╔██╗
██║ ╚═╝ ██║╚██████╔╝ ╚████╔╝ ██║███████╗██╔╝ ██╗
╚═╝     ╚═╝ ╚═════╝   ╚═══╝  ╚═╝╚══════╝╚═╝  ╚═╝

Terminal-native movie downloader. Search. Select. Download.

---

What is MovieX?

MovieX is a production-ready CLI tool that lets you search any movie or TV show via the TMDB API, browse results with ratings and overviews, then pull the best available quality through VidVault — all from your terminal.

  Search movie: Interstellar

  [  1]  Interstellar (2014)  ★★★★☆ 8.4
         A team of explorers travel through a wormhole in space...

  [  2]  Interstellar Wars (2016)
         ...

  Select [1-2]: 1

  + Selected: Interstellar
  Fetching sources from VidVault...

  Available qualities:
    1.  1080p  2.14 GB
    2.   720p  1.22 GB
    3.   480p  680.0 MB

  Quality: 1080p  2.14 GB
  Output: ./downloads/Interstellar (2014) - 1080p.mp4

  Interstellar (2014) - 1080p.mp4:  47%|████████░░░░░░░  | 1.02G/2.14G [01:23<01:34, 11.8MB/s]

---

Features

Feature	Detail
TMDB Search	Top-10 results with title, year, TMDb rating, and overview
TV Show Support	Search series and target specific seasons/episodes
Smart Quality Selection	Preferred → fallback → highest available
Resume Downloads	HTTP Range requests pick up interrupted downloads
Large File Streaming	Chunked streaming handles 8 GB+ files with no memory issues
Progress Bar	Real-time speed, ETA, and transfer size via tqdm
Retry with Back-off	Configurable retries on every API call and download
Auto Token Refresh	Re-fetches VidVault token on 401 and retries automatically
Clean Filenames	Media-server-friendly format: Title (Year) - 1080p.mp4
Atomic Writes	Streams to .part, renames on success — no corrupt files
No Hardcoded Secrets	Everything via .env / environment variables

---

Quick Start

1. Clone

git clone https://github.com/Win1817/moviex.git
cd moviex

2. Install dependencies

pip install -r requirements.txt

3. Configure

cp .env.example .env

Open .env and set your TMDB API key (free at themoviedb.org/settings/api):

TMDB_API_KEY=your_key_here

4. Run

python main.py

---

Usage

Interactive mode

python main.py

Prompts for a title, displays results, lets you pick, then downloads.

CLI flags

python main.py [OPTIONS]

Flag	Short	Description
--query TITLE	-q	Movie / show title to search
--auto	-a	Auto-select the first result
--tv		Search TV shows instead of movies
--season N	-s	Season number (TV mode)
--episode N	-e	Episode number (TV mode)
--quality RES		Override preferred resolution (e.g. 720, 1080, 2160)
--output DIR	-o	Set download directory (skips the interactive directory prompt)
--skip-existing		Skip if the output file already exists
--verbose	-v	Enable DEBUG logging
--version		Show version and exit

Examples

# Search and auto-download best match in preferred quality
python main.py --query "Oppenheimer" --auto

# Download a specific TV episode
python main.py --tv --query "The Bear" --season 2 --episode 1 --auto

# Force 4K, save to custom dir
python main.py --query "Dune" --quality 2160 --output /media/movies

# Batch-friendly: skip if already downloaded
python main.py --query "Blade Runner 2049" --auto --skip-existing

# Verbose debug output
python main.py --query "Tenet" --verbose

---

Project Structure

moviex/
├── main.py          # CLI entrypoint — argument parsing, user interaction, core flow
├── config.py        # Environment variables, constants, startup validation
├── tmdb.py          # TMDB API client — movie + TV show search
├── vidvault.py      # VidVault client — token management, download-proxy
├── selector.py      # Quality-selection logic
├── downloader.py    # Streaming downloader — resume, progress bar, atomic write
├── utils.py         # Logging setup, retry decorator, filename sanitisation
├── requirements.txt
└── .env.example

---

Configuration Reference

All settings are loaded from .env. No secrets are ever hardcoded.

Variable	Default	Description
TMDB_API_KEY	(required)	Your TMDB v3 API key
TMDB_API	https://api.themoviedb.org/3	TMDB base URL
VIDVAULT_API	https://vidvault.ru/api	VidVault base URL
PREFERRED_QUALITY	1080	Desired resolution in p
FALLBACK_QUALITY	720	Fallback if preferred unavailable
OUTPUT_DIR	./downloads	Download destination directory
MAX_RETRIES	3	Retry attempts for API calls and downloads
TIMEOUT	30	HTTP request timeout in seconds
CHUNK_SIZE	8192	Stream chunk size in bytes
LOG_LEVEL	INFO	DEBUG / INFO / WARNING / ERROR

---

Output Filename Format

{Title} ({Year}) - {Resolution}p.mp4

Examples:

• Oppenheimer (2023) - 1080p.mp4
• The Bear (2022) - 720p.mp4
• Dune Part Two (2024) - 2160p.mp4

Filenames are automatically sanitised — characters illegal on Windows, macOS, and Linux are stripped.

---

Architecture

MovieX follows strict separation of concerns. Each module has one job:

main.py
  |-- config.py          load env, validate
  |-- tmdb.py            search TMDB
  |-- vidvault.py        fetch token + download sources
  |-- selector.py        pick best quality
  |-- downloader.py      stream to disk
  |-- utils.py           retry, logging, filenames

The with_retries decorator in utils.py wraps any function with configurable retries and exponential back-off — applied uniformly to all API calls and the download function.

---

Requirements

• Python 3.10+
• requests — HTTP client
• python-dotenv — .env loading
• tqdm — progress bar

pip install -r requirements.txt

---

License

MIT — see LICENSE.

---

_{Built with Python · Powered by TMDB · MovieX v1.0.0}