# YouTube Downloader

> Powered by yt-dlp • Cross-platform • Python 3.8+

**Version 1.0**

---

## Overview

This package provides two Python scripts that together let you download YouTube videos and audio to your computer with a simple interactive menu. No programming knowledge is required to use them.

| File | Purpose |
|------|---------|
| `yt_downloader.py` | Main script — interactive downloader with quality selection |
| `install_dependencies.py` | One-time setup — installs yt-dlp and ffmpeg automatically |
| `README.md` | This document |

---

## System Requirements

| Requirement | Details |
|-------------|---------|
| Python | Version 3.8 or newer (`python --version` to check) |
| pip | Included with Python 3.4+; upgraded automatically by installer |
| yt-dlp | Installed automatically by `install_dependencies.py` |
| ffmpeg | Installed automatically by `install_dependencies.py` (optional but strongly recommended) |
| Internet | Required for downloading videos |
| Disk space | Varies by video length and quality — allow at least 500 MB free |

> **Note:** ffmpeg is optional but required for 1080p/4K quality and MP3 audio conversion. Without it the downloader falls back to pre-muxed formats (typically 720p max).

---

## Quick Start

### Step 1 — Run the installer (once only)

Open a terminal or command prompt in the folder containing the scripts, then run:

```bash
python install_dependencies.py
```

The installer will automatically detect your operating system and install everything needed. You should see green checkmarks confirming success.

### Step 2 — Download a video

```bash
python yt_downloader.py
```

Follow the on-screen prompts:

- Paste the YouTube URL and press Enter
- Choose an action: download video, download audio, or list formats
- Select a quality (if downloading video)
- Choose a save folder (default is `./downloads` in the same directory)

---

## Installer — `install_dependencies.py`

Run this script once before using the downloader. It is safe to run again at any time; it will upgrade existing installations.

### What it installs

- **pip** — upgraded to the latest version to avoid dependency resolver issues
- **yt-dlp** — the core download engine (kept up to date)
- **ffmpeg** — the media processing library used for merging video/audio streams and converting to MP3

### Platform support

| Platform | ffmpeg install method |
|----------|-----------------------|
| Windows | winget → Chocolatey → Scoop (uses whichever is found first) |
| macOS | Homebrew (installs Homebrew automatically if not present) |
| Linux — Debian / Ubuntu | apt-get |
| Linux — Fedora / RHEL | dnf + RPM Fusion repository |
| Linux — Arch Linux | pacman |

### After the installer runs

A verification step checks both tools and reports their detected versions. If ffmpeg shows a warning instead of a checkmark, try opening a new terminal window and running the installer again — PATH changes sometimes require a terminal restart.

---

## Downloader — `yt_downloader.py`

### Startup check

When launched the script immediately checks for ffmpeg and shows its status:

- ✅ **Green checkmark** — full quality available including 1080p, 4K, and MP3 audio
- ⚠️ **Warning** — ffmpeg not found; quality limited to ~720p and audio saves as `.m4a`

### Menu options

| Option | Description |
|--------|-------------|
| 1 — Download video | Downloads as MP4. Prompts for quality selection (see below). |
| 2 — Download audio only | Extracts audio. Saves as MP3 (with ffmpeg) or `.m4a` (without). |
| 3 — List available formats | Prints every available format ID, extension, resolution, and FPS for the given URL. Useful for troubleshooting. |

### Quality options

| Quality | Behaviour |
|---------|-----------|
| best (default) | Highest available quality for the video |
| 1080p | Up to 1920 × 1080 — requires ffmpeg |
| 720p | Up to 1280 × 720 |
| 480p | Up to 854 × 480 |
| 360p | Up to 640 × 360 — smallest file size |

### Output folder

By default files are saved to a `downloads/` subfolder next to the script. You can type any absolute or relative path at the prompt, for example:

```
C:\Users\Alice\Videos       (Windows)
/home/alice/Videos          (macOS / Linux)
./my-downloads              (relative path, any OS)
```

### How quality selection works internally

YouTube streams high-quality video and audio as separate files. ffmpeg is used to merge them after download. When ffmpeg is not available the script automatically switches to pre-muxed single-file formats to avoid errors — this is why quality is capped at ~720p without ffmpeg.

---

## Troubleshooting

| Error / Symptom | Solution |
|-----------------|----------|
| `ffmpeg is not installed. Aborting due to --abort-on-error` | Run `install_dependencies.py`, then open a new terminal and try again. |
| `python: command not found` | Try `python3` instead. On Windows, ensure Python is added to PATH during installation. |
| `pip is not recognised` | Run: `python -m ensurepip --upgrade` |
| Download stops or gives HTTP 403 | Update yt-dlp: `pip install --upgrade yt-dlp` (YouTube changes its API regularly) |
| Age-restricted or private video fails | These videos require authentication. yt-dlp supports cookie-based login — see the [yt-dlp documentation](https://github.com/yt-dlp/yt-dlp). |
| 1080p not available after installing ffmpeg | Restart your terminal so the updated PATH takes effect, then try again. |
| Very slow download speed | Normal for large files. Progress is shown during download. Check your internet connection. |

---

## Keeping Things Up to Date

YouTube frequently changes its internal API. If downloads suddenly stop working, update yt-dlp:

```bash
pip install --upgrade yt-dlp
```

You can also re-run the installer at any time — it upgrades all components safely.

---

## Legal Notice

> This tool is intended for personal use only. Downloading copyrighted content without the rights holder's permission may violate YouTube's Terms of Service and applicable copyright law. Only download content you have the right to download — such as your own uploads, Creative Commons-licensed videos, or content explicitly made available for offline use.

---

## Quick Reference Card

| Task | Command |
|------|---------|
| First-time setup | `python install_dependencies.py` |
| Download a video | `python yt_downloader.py` |
| Update yt-dlp only | `pip install --upgrade yt-dlp` |
| Check ffmpeg version | `ffmpeg -version` |
| Check yt-dlp version | `yt-dlp --version` |