Metadata-Version: 2.4
Name: vidsrc-dlp
Version: 0.1.0
Summary: CLI to search TMDB, resolve VidSrc streams, and download via yt-dlp
Author: Jeevan
License-Expression: MIT
Project-URL: Homepage, https://github.com/jeevan/vidsrc-dlp
Project-URL: Source, https://github.com/jeevan/vidsrc-dlp
Project-URL: BugTracker, https://github.com/jeevan/vidsrc-dlp/issues
Keywords: vidsrc,tmdb,yt-dlp,video,downloader
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: End Users/Desktop
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
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: yt-dlp>=2024.0.0

# vidsrc-dlp

Search TMDB, resolve a playable HLS stream via VidSrc's 4-hop chain, and download via yt-dlp.

## Install

```bash
pip install vidsrc-dlp
cp .env.example .env  # add your TMDB_API_KEY
```

Or for local development:

```bash
git clone https://github.com/jeevan/vidsrc-dlp
cd vidsrc-dlp
python -m venv .venv && source .venv/bin/activate
pip install -e .
cp .env.example .env  # add your TMDB_API_KEY
```

## Usage

```bash
# Movies
moviefinder "Inception"
moviefinder "The Matrix" --year 1999
moviefinder "Interstellar" --quality 1080p --no-confirm --verbose

# TV Shows
moviefinder "Breaking Bad" --type tv --season 1 --episode 1
moviefinder "Severance" --type tv --season 2 --episode 5

# Test with main.py (no install needed)
python main.py "Inception"
```

## Output paths

Configure in `.env` or override via CLI:

```
MOVIES_DIR=./downloads/movies
TV_DIR=./downloads/tv
```

```bash
moviefinder "Inception" --movies-dir "/Volumes/Media/Movies"
moviefinder "Breaking Bad" --type tv --season 1 --episode 1 --tv-dir "/Volumes/Media/TV"
```

## Naming convention

```
Movies:  {MOVIES_DIR}/Inception (2010)/Inception (2010).mp4
TV:      {TV_DIR}/Breaking Bad/Season 01/Breaking Bad - S01E01 - Pilot.mp4
```

## Architecture

1. **TMDB** — search API for movie/TV metadata
2. **VidSrc Resolver** — `requests`-only 4-hop chain to extract an HLS URL
3. **Downloader** — `yt-dlp` + ffmpeg to download and transcode to MP4

## How the resolver works

```
vidsrc.to/embed/{movie|tv}/{tmdb_id}[/{season}/{episode}]
  → vsembed.ru iframe (parse src attr)
    → cloudorchestranova.com/rcp/{hash} (parse prorcp hash)
      → cloudorchestranova.com/prorcp/{hash} (m3u8 URLs with __TOKEN__ placeholders)
        → generate.php endpoints (JWT tokens)
          → final m3u8 URL
```

## Adding a new stream provider

Implement `StreamProvider` from `moviefinder.utils`.

## Acknowledgements

- **[MaheshSharan/vidsrc](https://github.com/MaheshSharan/vidsrc)** — The request-based 4-hop resolution chain was reverse-engineered from this open-source PHP scraper. Critical reference for the VidSrc token flow.
- **[TMDB](https://www.themoviedb.org/)** — Movie and TV metadata API. All search, detail, episode info sourced from their free tier.
- **[yt-dlp](https://github.com/yt-dlp/yt-dlp)** — The download engine. Handles HLS fragment fetching, decryption, and ffmpeg transcoding.
- **[requests](https://github.com/psf/requests)** — HTTP library for the resolver chain.
- **[python-dotenv](https://github.com/theskumar/python-dotenv)** — Environment variable loading from `.env`.
