yt-dlp-proxy/README.md

# yt-dlp HLS Proxy

A simple Flask proxy server that uses yt-dlp to fetch HLS streams and serves them through a web player.

## Features

- HLS stream proxying via yt-dlp
- In-memory caching (365 days TTL by default)
- URL validation with allowed domains
- HTML5 video player with hls.js
- Configurable via environment variables
- Full metadata display (title, description, views, likes, tags, etc.)

## Quick Start

```bash
pip install -r requirements.txt
python app.py
```

Visit http://localhost:5000 and enter a video URL.

## Configuration

| Variable | Default | Description |
|----------|---------|-------------|
| PORT | 5000 | Server port |
| LOG_LEVEL | INFO | Logging level |
| CACHE_TTL | 31536000 | Cache TTL in seconds (365 days) |
| SOCKET_TIMEOUT | 30 | Socket timeout for requests |
| VALIDATION_ENABLED | true | Enable URL validation |
| ALLOWED_DOMAINS | youtube.com,youtu.be,pornhub.com,xvideos.com | Allowed video domains |
| ALLOW_LOCAL | true | Allow localhost/127.0.0.1 URLs (for testing) |

## Routes

- `/` - Home page with video URL input
- `/player?url=VIDEO_URL` - Video player page with full metadata
- `/hls/<encoded_url>--index.m3u8` - HLS main playlist
- `/hls/<encoded_url>--<segment>.ts` - HLS segment

## Connecting External Player

### URL Format

The proxy uses this format: `/hls/<encoded_video_url>--<filename>`

Example for PornHub:
```
/hls/https%3A%2F%2Frt.pornhub.com%2Fview_video.php%3Fviewkey%3D69c13273df690--index.m3u8
```

### Using with yt-dlp (as browser substitute)

```bash
# Get playlist URL via proxy
yt-dlp --hls-use-mpegts --no-download --print url \
  "http://localhost:5000/hls/https%3A%2F%2Frt.pornhub.com%2Fview_video.php%3Fviewkey%3D69c13273df690--index.m3u8"
```

### Using with VLC

1. Open Network Stream (Ctrl+N)
2. Enter: `http://localhost:5000/hls/<encoded_url>--index.m3u8`

### Using with mpv

```bash
mpv "http://localhost:5000/hls/https%3A%2F%2Frt.pornhub.com%2Fview_video.php%3Fviewkey%3D69c13273df690--index.m3u8"
```

### Using with any HLS-compatible player

Most players accept the m3u8 URL directly:

```
http://localhost:5000/hls/<encoded_video_url>--index.m3u8
```

Where `<encoded_video_url>` is the URL-encoded original video URL.

Example - full URL:
```
http://localhost:5000/hls/https%3A%2F%2Frt.pornhub.com%2Fview_video.php%3Fviewkey%3D69c13273df690--index.m3u8
```

### Python example (using requests + hlsjs)

```python
import requests

video_url = "https://rt.pornhub.com/view_video.php?viewkey=69c13273df690"
from urllib.parse import quote
encoded = quote(video_url, safe="")
hls_url = f"http://localhost:5000/hls/{encoded}--index.m3u8"

response = requests.get(hls_url)
print(response.text)  # Contains rewritten segment URLs
```

## Running with Gunicorn

```bash
gunicorn -w 4 -b 0.0.0.0:5000 app:app
```

## Testing

```bash
pytest tests/test_proxy.py -v
```

## Supported Sites

- PornHub (primary - HLS)
- YouTube (direct URL fallback, no HLS)
- Any site supported by yt-dlp

## License

MIT