YouTube Downloader (Python)

Small cross-platform CLI script to download YouTube videos or audio using yt-dlp.

Features

• Works on macOS, Linux, and Windows
• Auto platform detection (bash + uname, fallback to Windows profile)
• Video download with target max quality (example: 720p, 1080p)
• Audio-only mode with MP3 conversion
• Auto-creates output directory if missing
• Compatibility profiles: auto, mac, windows, linux, universal

Requirements

• Python 3.10+
• ffmpeg (recommended; required for merge/conversion)
• Python package: yt-dlp

Install Python deps:

pip install -r requirements.txt

Install ffmpeg (examples):

• macOS (Homebrew): brew install ffmpeg
• Ubuntu/Debian: sudo apt install ffmpeg
• Windows (winget): winget install Gyan.FFmpeg

Quick Start

python3 youtube_downloader.py "https://www.youtube.com/watch?v=VIDEO_ID"

Output is saved in ./Download by default.

Usage

Download video (default max 1080p)

python3 youtube_downloader.py "https://www.youtube.com/watch?v=VIDEO_ID"

Download video with custom max quality

python3 youtube_downloader.py "https://www.youtube.com/watch?v=VIDEO_ID" --quality 720

Download audio only (MP3)

python3 youtube_downloader.py "https://www.youtube.com/watch?v=VIDEO_ID" --audio-only

Custom output directory

python3 youtube_downloader.py "https://www.youtube.com/watch?v=VIDEO_ID" --output-dir DownloadsScript

Force a compatibility profile

python3 youtube_downloader.py "https://www.youtube.com/watch?v=VIDEO_ID" --compat-mode mac
python3 youtube_downloader.py "https://www.youtube.com/watch?v=VIDEO_ID" --compat-mode windows
python3 youtube_downloader.py "https://www.youtube.com/watch?v=VIDEO_ID" --compat-mode linux
python3 youtube_downloader.py "https://www.youtube.com/watch?v=VIDEO_ID" --compat-mode universal

Platform Notes

• macOS: profile mac prefers avc1 + mp4a, usually best for QuickTime.
• Windows: profile windows prefers h264/avc1 + mp4a for broad player support.
• Linux: profile linux uses mp4 + m4a preference where possible.

Common Issues

• ffmpeg not found: install ffmpeg, then retry.
• Download skipped because file already exists: use another --output-dir.
• Some yt-dlp warnings about JS runtime can appear depending on extractor updates.

CI

GitHub Actions workflow is included at:

• .github/workflows/ci.yml

It runs:

• syntax compile check (py_compile)
• CLI smoke check (--help)
• on macOS, Linux, and Windows (Python 3.10/3.11/3.12)

Publishing Checklist

Before pushing public release:

1. Update CHANGELOG.md.
2. Verify local checks: python3 -m py_compile youtube_downloader.py and python3 youtube_downloader.py --help.
3. Ensure README.md and CLI options are aligned.
4. Commit with a clear message.
5. Tag a version (example: v1.0.0) after first release commit.

Contributing

See CONTRIBUTING.md.

Legal

Only download content if you have the right to do so and if local laws / platform terms allow it.

License

This project is licensed under the MIT License. See LICENSE.