Metadata-Version: 2.4
Name: ytpro
Version: 1.0.1
Summary: A professional, modular command-line YouTube downloader with dynamic format detection.
Author: YTPro Developers
License: MIT
Keywords: youtube,downloader,cli,yt-dlp,ffmpeg,rich,media
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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: yt-dlp>=2024.8.0
Requires-Dist: rich>=13.0.0
Requires-Dist: questionary>=2.0.0
Requires-Dist: tomlkit>=0.12.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Dynamic: license-file

# YTPro - Professional YouTube Media Downloader CLI

```text
╔══════════════════════════════════════════════════════╗
║              YOUTUBE DOWNLOADER PRO                  ║
║                  CLI Edition                         ║
╚══════════════════════════════════════════════════════╝
```

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python: 3.10+](https://img.shields.io/badge/Python-3.10+-brightgreen.svg)](https://www.python.org/)
[![Code Style: Clean](https://img.shields.io/badge/Style-Modular-purple.svg)]()

**YTPro** is a modular, production-grade command-line YouTube downloader application engineered for reliability and visual clarity. Inspired by tools such as `yt-dlp` and `ffmpeg`, YTPro features genuine dynamic quality detection (supporting up to 8K), zero-re-encoding stream merging, lossless/lossy audio extraction and transcoding, rich terminal aesthetics, resume support, and friendly error diagnostics.

---

## Key Features

- **Genuine Dynamic Format Detection**: Inspects the real formats returned by YouTube. No fake 4K or 8K options are ever shown if the video does not provide them.
- **8K / 4K / High-Framerate / HDR Support**: Fully detects and downloads 4320p (8K), 2160p (4K), 1440p, 1080p, 720p, 60 FPS, and HDR streams when available.
- **Smart Stream Merging**: Downloads separate highest-quality video and compatible audio streams and muxes them into MKV or MP4 containers without re-encoding via FFmpeg.
- **Dedicated Audio Extraction & Transcoding**: Extract audio directly or transcode cleanly to **MP3** (320 kbps), **M4A** (AAC), **WAV**, or **FLAC**.
- **Video-Only Mode**: Download raw video streams without audio tracks.
- **Professional Terminal Interface**: Built with **Rich** and **Questionary** featuring stylized headers, status spinners, custom two-stage progress bars (`[1/2] Video`, `[2/2] Audio`), transfer speeds, ETA, and summary panels.
- **Resume & Overwrite Handling**: Automatically detects existing files and `.part` downloads, with interactive prompts to Resume, Overwrite, Rename, or Restart.
- **Pre-Download Safety Checks**: Verifies free disk space and FFmpeg availability before downloading large files. Warns users before starting very large downloads (> 5 GB).
- **Persistent Configuration**: Store custom defaults in `~/.ytpro/config.toml` (output directory, preferred qualities, audio transcode targets).
- **Zero Raw Tracebacks**: User-facing exceptions provide clear **Error**, **Reason / Cause**, and **Suggested Solution** messages (run with `--debug` for full technical logs).
- **Fully Scriptable**: Operates interactively or through direct command-line arguments in automation scripts.

---

## Previous Workflow vs. Current Professional UI

| Capability | Previous Standard Downloaders | YTPro Current Experience |
| :--- | :--- | :--- |
| **Quality Detection** | Hardcoded static choices (often shows 4K/8K options that fail or don't exist) | **Real Dynamic Discovery**: Only displays resolutions and formats actually returned by YouTube for that specific video |
| **High Resolution** | Often limited to progressive 720p/360p | **Full 8K / 4K / 1440p / 60 FPS / HDR** stream download and remuxing |
| **Stream Merging** | Separate streams downloaded without audio or re-encoded with quality loss | **Lossless Stream Copy**: Video & audio muxed seamlessly into MP4/MKV with zero re-encoding |
| **Terminal UI** | Plain text / cluttered terminal logs | **Rich Terminal UI**: Styled ASCII banners, formatted tables, and interactive menus |
| **Progress Feedback** | Simple percentages or messy unbuffered output | **Multi-Stage Progress Bars**: `[1/2] Video`, `[2/2] Audio`, transfer speeds, ETA, and merge status |
| **Audio Extraction** | Requires manual external ffmpeg commands | **Built-in Transcoding**: One-click extraction to MP3 (320 kbps), M4A, WAV, or FLAC |
| **Error Handling** | Raw multi-line Python tracebacks on failure | **Clean Diagnostic Panels**: Displays clear Error, Reason/Cause, and Suggested Solution |

### Live Format Inspection Table

```text
         Available Video Qualities (Dynamic Detection)          
┌────────────┬───────┬─────┬─────┬─────────────────┬───────────┐
│ Resolution │ Codec │ FPS │ HDR │ Est. Total Size │ Format ID │
├────────────┼───────┼─────┼─────┼─────────────────┼───────────┤
│ 4320p      │ AV1   │  60 │  -  │        711.5 MB │ 571       │
│ 2160p      │ VP9   │  60 │  -  │        848.3 MB │ 628       │
│ 1440p      │ VP9   │  60 │  -  │        341.3 MB │ 623       │
│ 1080p      │ AVC1  │  60 │  -  │        164.2 MB │ 312       │
│ 720p       │ AVC1  │  60 │  -  │        95.54 MB │ 311       │
│ 480p       │ AVC1  │  30 │  -  │        44.22 MB │ 231       │
│ 360p       │ VP9   │  30 │  -  │        27.44 MB │ 605       │
│ 240p       │ VP9   │  30 │  -  │        16.76 MB │ 604       │
│ 144p       │ VP9   │  30 │  -  │        14.57 MB │ 603       │
└────────────┴───────┴─────┴─────┴─────────────────┴───────────┘

                Available Audio Streams                 
┌──────────┬───────┬───────────┬───────────┬───────────┐
│ Bitrate  │ Codec │ Container │ Est. Size │ Format ID │
├──────────┼───────┼───────────┼───────────┼───────────┤
│ 129 kbps │ Opus  │ WEBM      │   5.48 MB │ 251       │
│ 129 kbps │ AAC   │ M4A       │   5.50 MB │ 140       │
│ 48 kbps  │ AAC   │ M4A       │   2.07 MB │ 139       │
└──────────┴───────┴───────────┴───────────┴───────────┘
```

---

## Architecture

YTPro is built as a clean, modular Python application:

```text
ytpro/
├── __init__.py          # Package metadata and version info
├── cli.py               # CLI parser and command router (interactive & scripted)
├── config.py            # TOML configuration manager (~/.ytpro/config.toml)
├── downloader.py        # yt-dlp orchestration, FFmpeg hooks, and verification
├── errors.py            # Typed domain exceptions and clean Rich error renderer
├── extractor.py         # URL validation and YouTube format extraction
├── filesystem.py        # Filename sanitization, disk space checks, and path helpers
├── formatter.py         # Human-readable formatters (bytes, duration, speed, ETA)
├── metadata.py          # Strongly-typed dataclasses (VideoMetadata, StreamFormat, DownloadPlan)
├── progress.py          # Multi-stage Rich progress bar manager
├── quality.py           # Format categorization, ranking, and download plan construction
└── selector.py          # Interactive questionary menus and confirmation dialogues
```

---

## Installation

### Prerequisites
- Python 3.10 or higher
- FFmpeg installed and available on system `PATH`

### Step 1: Install FFmpeg

#### Windows
Using **Winget**:
```powershell
winget install Gyan.FFmpeg
```
Using **Chocolatey**:
```powershell
choco install ffmpeg
```

#### macOS
Using **Homebrew**:
```bash
brew install ffmpeg
```

#### Linux (Ubuntu/Debian)
```bash
sudo apt update && sudo apt install ffmpeg
```

Verify FFmpeg installation:
```bash
ffmpeg -version
```

### Step 2: Install YTPro

Install directly via `pip`:

```bash
pip install ytpro
```

Or via `pipx` (recommended for CLI applications):

```bash
pipx install ytpro
```

Verify that the CLI is accessible:
```bash
ytpro --version
ytpro --help
```

---

## Usage Guide

### 1. Interactive Mode

Simply run `ytpro` without arguments to launch the interactive interface:

```bash
ytpro
```

Or provide the URL directly to skip the URL prompt:

```bash
ytpro "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
```

Workflow:
1. Validates the YouTube URL.
2. Extracts and displays video title, channel, duration, and detected resolutions.
3. Prompts for mode: `Video + Audio`, `Audio only`, `Video only`.
4. Shows dynamically generated list of **actual** formats.
5. Displays pre-download confirmation panel.
6. Downloads with real-time multi-stage progress bars.
7. Verifies final file and prints completion summary.

---

### 2. List Available Formats (`--list-formats`)

Inspect real formats without downloading:

```bash
ytpro "https://www.youtube.com/watch?v=dQw4w9WgXcQ" --list-formats
```

Example output:
```text
         Available Video Qualities (Dynamic Detection)          
┌────────────┬───────┬─────┬─────┬─────────────────┬───────────┐
│ Resolution │ Codec │ FPS │ HDR │ Est. Total Size │ Format ID │
├────────────┼───────┼─────┼─────┼─────────────────┼───────────┤
│ 2160p      │ VP9   │  25 │  -  │        488.7 MB │ 625       │
│ 1440p      │ VP9   │  25 │  -  │        246.1 MB │ 620       │
│ 1080p      │ AVC1  │  25 │  -  │        122.3 MB │ 270       │
│ 720p       │ AVC1  │  25 │  -  │        34.97 MB │ 232       │
│ 480p       │ AVC1  │  25 │  -  │        25.18 MB │ 231       │
│ 360p       │ AVC1  │  25 │  -  │        18.78 MB │ 230       │
└────────────┴───────┴─────┴─────┴─────────────────┴───────────┘
```

---

### 3. Video + Audio Downloads (Specific Quality)

Download at a specific resolution (merged with best audio stream):

```bash
# Download 4K / 2160p
ytpro "https://www.youtube.com/watch?v=dQw4w9WgXcQ" --quality 2160p

# Download 1080p
ytpro "https://www.youtube.com/watch?v=dQw4w9WgXcQ" -q 1080p

# Download highest available resolution
ytpro "https://www.youtube.com/watch?v=dQw4w9WgXcQ" -q best
```

---

### 4. Audio-Only Downloads & Transcoding

Download the highest quality audio track or convert to standard formats:

```bash
# Download original audio container (Opus / AAC)
ytpro "https://www.youtube.com/watch?v=dQw4w9WgXcQ" --audio

# Convert to MP3 (320 kbps)
ytpro "https://www.youtube.com/watch?v=dQw4w9WgXcQ" --audio --format mp3

# Convert to Lossless FLAC
ytpro "https://www.youtube.com/watch?v=dQw4w9WgXcQ" --audio --format flac

# Convert to M4A or WAV
ytpro "https://www.youtube.com/watch?v=dQw4w9WgXcQ" --audio -f m4a
ytpro "https://www.youtube.com/watch?v=dQw4w9WgXcQ" --audio -f wav
```

---

### 5. Video-Only Downloads

Download video streams without an audio track:

```bash
ytpro "https://www.youtube.com/watch?v=dQw4w9WgXcQ" --video-only -q 2160p
```

---

### 6. Custom Output Directory

Specify a destination directory via `-o` or `--output`:

```bash
ytpro "https://www.youtube.com/watch?v=dQw4w9WgXcQ" -o ./my_videos
```

---

### 7. Metadata and Thumbnail Embedding

Embed tags (Title, Artist, Upload date, Description) and video thumbnails:

```bash
ytpro "https://www.youtube.com/watch?v=dQw4w9WgXcQ" --metadata --thumbnail
```

---

### 8. Debug Mode

For troubleshooting or bug reporting, enable `--debug` to output full stack traces and verbose extractor logs:

```bash
ytpro "https://www.youtube.com/watch?v=dQw4w9WgXcQ" --debug
```

---

## Configuration (`~/.ytpro/config.toml`)

On first launch, YTPro automatically creates a configuration file at:
- **Windows**: `C:\Users\<User>\.ytpro\config.toml`
- **Linux/macOS**: `~/.ytpro/config.toml`

Default configuration settings:

```toml
# Directory where downloaded media is saved
output_directory = "~/Downloads"

# Default mode: "video_audio", "audio_only", or "video_only"
default_mode = "video_audio"

# Default quality preference: "best", "4320p", "2160p", "1440p", "1080p", "720p"
default_quality = "best"

# Default audio conversion format for audio mode: "original", "mp3", "m4a", "wav", "flac"
default_audio_format = "original"

# Automatically overwrite existing files without prompting (true/false)
overwrite = false

# Embed metadata tags (Title, Artist, Upload Date, Description) into output file
embed_metadata = true

# Embed video thumbnail cover art into output file
embed_thumbnail = false
```

CLI flags always override configuration values.

---

## Testing

YTPro includes an automated test suite with unit tests covering URL validation, format parsing, quality sorting, filesystem sanitization, configuration management, and error presentation.

Run all tests with `pytest`:

```bash
pytest tests/ -v
```

---

## Legal & Safety Notice

YTPro is designed for educational, personal archival, and development purposes.

- Only download content you are authorized to download, content licensed under Creative Commons, or public domain material.
- YTPro **does not** circumvent Digital Rights Management (DRM), defeat access controls, bypass paywalls, or collect account credentials.
- Users are responsible for complying with YouTube's Terms of Service and applicable local copyright laws.

---

## License

Released under the [MIT License](LICENSE). Copyright (c) 2026 YTPro Developers.
