ytd-wrap

Download videos from social media platforms and direct stream URLs — a friendly wrapper around yt-dlp.

Maintainer: Shyam Darshanam (Shyam-Dev18)

---

Features

• Arrow-key format selection — pick resolution and codec interactively
• Smart container selection — mp4 for H.264/AAC, mkv for everything else
• Rich terminal output — progress bars, tables, and coloured panels
• One-command doctor — verifies all dependencies in one shot
• Non-blocking update checks — notified of new versions once per day
• Graceful error handling — actionable hints for age-restriction, geo-blocks, and missing ffmpeg

---

Prerequisites

Python 3.11 or newer

Download from https://python.org/downloads/.

ffmpeg

ffmpeg must be on your system PATH. Pick the instructions for your OS:

macOS (Homebrew)

brew install ffmpeg

Windows (winget)

winget install --id Gyan.FFmpeg -e

Windows (Chocolatey)

choco install ffmpeg

Debian / Ubuntu

sudo apt update && sudo apt install ffmpeg

Fedora / RHEL

sudo dnf install ffmpeg

Verify the installation:

ffmpeg -version

---

Installation

pip install ytd-wrap

Or for development:

git clone https://github.com/example/ytd-wrap.git
cd ytd-wrap
pip install -e ".[dev]"

---

Usage

Download a social media video

ytd-wrap "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

The tool will:

1. Fetch available formats and display them in a table
2. Let you pick resolution/quality with arrow keys
3. Download with a live progress bar
4. Report the saved file path

Download a direct stream / m3u8

ytd-wrap "https://example.com/stream/video.m3u8"
ytd-wrap "https://example.com/video.mp4"

Direct URLs skip format selection and download with the best available quality automatically.

Show version

ytd-wrap --version

Check environment health

ytd-wrap doctor

Checks:

• Python version (3.11+ required)
• yt-dlp installed and importable
• ffmpeg found on PATH

Shows OS-specific install hints if anything is missing.

---

Supported sites

ytd-wrap uses yt-dlp under the hood, which supports 1 000+ sites including:

Platform	Notes
YouTube	Full format selection, age-gated content with cookies
Twitter / X	Videos from tweets
Instagram	Reels, posts, stories
TikTok	Public videos
Twitch	VODs and clips
Vimeo	Public videos
Direct URLs	.m3u8, .mp4, .mkv, .webm, .ts streams

---

Output format logic

Video codec	Audio codec	Container
h264	aac	.mp4
h264	mp4a	.mp4
vp9	any	.webm
anything else	anything	.mkv

Files are saved to ~/Downloads/ (falls back to ~/ if Downloads does not exist).

---

Troubleshooting

ERROR: Sign in to confirm your age

This video is age-restricted. Sign in to YouTube in your browser, then pass your browser cookies to yt-dlp directly:

yt-dlp --cookies-from-browser chrome "https://..."

ERROR: The uploader has not made this video available in your country

The content is geo-blocked. Use a VPN to access it from a supported region.

ERROR: ffmpeg is not installed

Install ffmpeg (see Prerequisites) and ensure it is on your system PATH.

postprocessing: error

ffmpeg found an incompatible stream. Try selecting a different format or use ytd-wrap doctor to confirm ffmpeg is working.

ERROR: This video is available to this channel's members

Members-only content requires a session cookie from a subscribed account.

Download starts but no file appears

Check ~/.ytd-wrap/logs/ytd-wrap.log for details.

---

License

MIT — see LICENSE for details.