Metadata-Version: 2.4
Name: snagvid
Version: 0.1.0
Summary: Download videos from YouTube, X/Twitter, Instagram, Facebook, or almost any website straight from your terminal.
Author: Waqas
License-Expression: MIT
Project-URL: Homepage, https://github.com/WaqasAhmad313/snagvid
Project-URL: Repository, https://github.com/WaqasAhmad313/snagvid
Project-URL: Issues, https://github.com/WaqasAhmad313/snagvid/issues
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Video
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: yt-dlp>=2024.1.1
Requires-Dist: click>=8.1
Requires-Dist: questionary>=2.0
Requires-Dist: rich>=13.0
Dynamic: license-file

# snagvid (`vdl`)

Download videos from YouTube, X/Twitter, Instagram, Facebook, or almost any website — straight from your terminal, no browser extensions, no sketchy websites.

[![PyPI version](https://img.shields.io/pypi/v/snagvid.svg)](https://pypi.org/project/snagvid/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)

![demo](docs/demo.gif)

## Features

- 🧙 **Interactive CLI Wizard**: Simply type `vdl` to get guided prompts for URL, resolution, and output folder.
- 📊 **Smart Resolution & Size Detection**: Shows available resolutions with accurate combined video + audio download size estimates.
- 🎵 **Audio Extraction**: Easily extract high-quality audio tracks (e.g. MP3) directly.
- 🎨 **Clean Live Progress**: Real-time progress display with speed, ETA, and spinner animations powered by `rich`.
- 🌐 **1800+ Supported Sites**: Powered by `yt-dlp` for unmatched platform compatibility.
- ⚡ **Scripting Ready**: Pass URLs and flags directly (`vdl "<url>" -q 720p`) for automation.
- 🛡️ **Long Title Protection**: Automatic title truncation and ID tagging to prevent filesystem errors on long post captions.

## Prerequisites

- **Python**: 3.9 or higher
- **FFmpeg**: Required for stream merging and audio extraction.
  - **Linux**: `sudo apt install ffmpeg` / `sudo pacman -S ffmpeg`
  - **macOS**: `brew install ffmpeg`

## Installation

```bash
pip install snagvid
# or with pipx for isolated global installation:
pipx install snagvid
```

### Local Development Install

```bash
git clone https://github.com/WaqasAhmad313/snagvid.git
cd snagvid
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
```

## Usage

### Interactive Mode (Recommended)

Run `vdl` with no arguments to start the interactive wizard:

```bash
vdl
```

### Direct / Scripted Usage

Pass arguments directly to bypass the interactive prompts:

```bash
# Direct download best quality
vdl "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

# Download audio-only (MP3)
vdl "https://www.youtube.com/watch?v=dQw4w9WgXcQ" --audio

# Download specific quality to custom directory
vdl "https://www.youtube.com/watch?v=dQw4w9WgXcQ" -q 720p -o ~/Videos
```

### Configuration (`~/.vdlrc`)

You can save your default preferences in `~/.vdlrc` (INI format):

```ini
[defaults]
output       = ~/Videos
quality      = 1080p
audio_format = mp3
retries      = 5
```

## Supported Sites

`vdl` inherits complete extractor support from `yt-dlp`, covering 1800+ websites including YouTube, X/Twitter, Instagram, Facebook, TikTok, Twitch, Reddit, Vimeo, and SoundCloud.

For a full list of supported extractors, see the [yt-dlp supported sites documentation](https://github.com/yt-dlp/yt-dlp/blob/master/supported_sites.md).

## Responsible Use

This tool is intended for downloading content you own, have explicit permission to use, or that is otherwise legally accessible to you — e.g. personal backups, offline access to your own posts, content licensed for reuse. Respect the terms of service of the platform you're downloading from and applicable copyright law. The maintainers are not responsible for misuse.

## Contributing

Contributions are welcome!

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

Distributed under the MIT License. See [LICENSE](LICENSE) for details.
