Metadata-Version: 2.4
Name: media-dlp
Version: 1.4.0
Summary: Automated media downloader using browser automation + yt-dlp. Supports streaming sites via TMDB-based source chaining.
Author-email: Jeevan <jeevan@users.noreply.github.com>
License: MIT
Project-URL: Homepage, https://github.com/jeevan/media-dlp
Project-URL: Repository, https://github.com/jeevan/media-dlp
Project-URL: Issues, https://github.com/jeevan/media-dlp/issues
Keywords: download,video,hls,streaming,tmdb,playwright,yt-dlp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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
License-File: LICENSE
Requires-Dist: playwright>=1.40.0
Requires-Dist: yt-dlp>=2023.0.0
Requires-Dist: requests>=2.31.0
Dynamic: license-file

# media-dlp

Automated media downloader that uses **Playwright** (browser automation) to load streaming sites, detect video streams via network interception, and download them with **yt-dlp**.

## Why?

Streaming sites load video players that fetch HLS/DASH manifests from CDNs.  `media-dlp`:
1. Opens the site in a real Firefox window (cookies, referrer, fingerprint – the whole deal)
2. Watches all network traffic to find the video stream URL
3. Hands that URL to yt-dlp for the actual download (progress bars, resume support, quality selection)

No sneaky DOM scraping, no brittle CSS selectors against popups – just raw network-level video detection.

## Features

- **Network-level detection** – catches HLS, MP4, DASH, WebM streams
- **TMDB integration** – provide a TMDB movie ID instead of a full URL
- **Source chaining** – tries multiple providers (mapple → cineby → …)
- **yt-dlp download** – progress output, quality selection, resume
- **Tab muting** – no audio from the automated browser window
- **CLI + Python API** – use from the terminal or import as a library
- **Browser cookies** – passes session cookies to yt-dlp for authenticated streams

## Installation

```bash
pip install media-dlp
```

You also need the Playwright Firefox browser:

```bash
playwright install firefox
```

### TMDB API Key (for ``--tmdb-id``)

Set the environment variable:

```bash
export TMDB_API_KEY="your_key_here"
```

Get a free key at [themoviedb.org/settings/api](https://www.themoviedb.org/settings/api).

---

## CLI Usage

```bash
media-dlp --url https://mapple.club/watch/movie/1034716

media-dlp --tmdb-id 1034716 --quality 1080p --output ~/Movies

media-dlp --tmdb-id 1034716 --providers mapple,cineby --filename "Dune 2"
```

### Options

| Argument | Short | Default | Description |
|----------|-------|---------|-------------|
| `--url` | `-u` | – | Direct movie page URL |
| `--tmdb-id` | `--tmdb` | – | TMDB movie ID |
| `--quality` | `-q` | `1080p` | `best`, `2160p`, `1080p`, `720p`, … |
| `--output` | `-o` | `./downloads` | Download directory |
| `--filename` | `-f` | auto | Custom output filename |
| `--providers` | – | `mapple,cineby` | Comma-separated source providers to try |
| `--timeout` | `-t` | `600` | Max seconds for the operation |
| `--mute` / `--no-mute` | – | `True` | Mute browser tab |
| `--verbose` | `-v` | – | Detailed logs |

---

## Python API

```python
from media_dlp import download_movie, list_providers

# List available source providers
print(list_providers())

# Download by URL
result = download_movie(
    url="https://mapple.club/watch/movie/1034716",
    quality="1080p",
    output_dir="./movies",
    mute=True,
    verbose=True,
)
print(result)  # e.g. ./movies/movie_12345.mp4

# Download by TMDB ID
result = download_movie(
    tmdb_id=1034716,
    quality="best",
    providers="mapple,cineby",
    filename="Dune Part Two",
)
```

---

## How It Works

```
┌─────────────────────────────────────────────────────┐
│  1. Playwright launches Firefox (persistent profile)│
│  2. Navigate to movie URL / resolve via TMDB        │
│  3. Click play button if needed                     │
│  4. Intercept ALL network requests/responses        │
│  5. Filter for HLS manifests, MP4 URLs, DASH MPDs   │
│  6. Pick best matching quality                      │
│  7. Spawn yt-dlp with: detected URL, cookies,       │
│     referrer, user-agent, origin headers             │
│  8. Stream progress to console                      │
│  9. File appears in output directory                │
└─────────────────────────────────────────────────────┘
```

The detection works at the **network level**, not the DOM level.  This means it doesn't matter how the video player constructs its URLs – if a HTTP response carries video content, `media-dlp` sees it.

### Source Providers

Providers are configured in `media_dlp/sources.py`.  Each maps a TMDB ID to a streaming-site URL:

| Provider | URL pattern | Priority |
|----------|-------------|----------|
| `mapple` | `https://mapple.club/watch/movie/{tmdb_id}` | 1 |
| `cineby` | `https://cineby.at/movie/{tmdb_id}` | 2 |

When you pass `--providers mapple,cineby`, it tries mapple first; if that fails to produce a video it moves to cineby (future enhancement – currently it takes the first working URL).

---

## Development

```bash
git clone https://github.com/jeevan/media-dlp
cd media-dlp
pip install -e .
playwright install firefox
```

### Testing

```bash
media-dlp --url https://mapple.club/watch/movie/1034716 --verbose
```

---

## FAQ

**Q: Does this work with DRM-protected content?**  
A: No.  Widevine-level DRM cannot be bypassed.  The tool relies on plain HLS/DASH/HTTP streams.

**Q: The download is slow**  
A: Increase the `--timeout` value.  Feature-length movies can take 10-30 minutes.

**Q: Can I run this headless?**  
A: Not currently – most streaming sites require a visible browser to serve video.

**Q: The browser opens but no video is detected**  
A: Run with `--verbose` to see network traffic.  The video player may need manual interaction (e.g. a "Play" click) which the tool attempts automatically via several common CSS selectors.

---
