Metadata-Version: 2.4
Name: udown
Version: 0.0.2
Summary: A fast YouTube video downloader with parallel processing
Author-email: Dipanjal Maitra <dipanjalmaitra@gmail.com>
Maintainer-email: Dipanjal Maitra <dipanjalmaitra@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/dipanjal/udown
Project-URL: Documentation, https://github.com/dipanjal/udown#readme
Project-URL: Repository, https://github.com/dipanjal/udown
Project-URL: Bug Tracker, https://github.com/dipanjal/udown/issues
Keywords: youtube,download,video,audio,parallel,processing
Classifier: Development Status :: 4 - Beta
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
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pytubefix==9.4.1
Provides-Extra: dev
Requires-Dist: pytest~=7.1.2; extra == "dev"
Requires-Dist: pytest-cov~=4.0.0; extra == "dev"
Requires-Dist: black~=24.3.0; extra == "dev"
Requires-Dist: pylint~=3.1.0; extra == "dev"
Requires-Dist: mypy~=1.9.0; extra == "dev"
Requires-Dist: build~=1.0.0; extra == "dev"
Requires-Dist: twine~=6.0.0; extra == "dev"
Requires-Dist: isort~=5.0.0; extra == "dev"
Dynamic: license-file

# UDown

A fast YouTube video downloader with parallel processing capabilities. Downloads audio and video streams simultaneously for optimal performance.

[![codecov](https://codecov.io/gh/dipanjal/udown/branch/main/graph/badge.svg)](https://codecov.io/gh/dipanjal/udown)

## Features

- ⚡ **Parallel Processing**: Downloads audio and video streams simultaneously
- 📊 **Performance Profiling**: Detailed timing reports for download operations
- 🎯 **High Quality**: Downloads best available audio and video streams
- 📝 **Caption Support**: Optional subtitle/caption downloads
- 🔧 **FFmpeg Integration**: Automatic audio-video merging
- 🖥️ **Cross-Platform**: Works on Windows, macOS, and Linux

## Installation

### From PyPI (Recommended)

```bash
pip install udown
```

### From Source

```bash
git clone https://github.com/dipanjal/udown.git
cd udown
pip install -e .
```

## Prerequisites

- **Python 3.8+**
- **FFmpeg**: Required for audio-video merging

### Installing FFmpeg

#### macOS
```bash
brew install ffmpeg
```

#### Ubuntu/Debian
```bash
sudo apt update
sudo apt install ffmpeg
```

#### Windows
Download from [FFmpeg official website](https://ffmpeg.org/download.html) or install via Chocolatey:
```bash
choco install ffmpeg
```

## Usage

### Basic Usage

```bash
udown -o ~/Downloads [youtube_url]
```

### Advanced Usage

```bash
# Download to custom directory
udown -o ~/Downloads [youtube_url]

# Download with captions
udown -c -o ~/Downloads [youtube_url]

# Enable debug mode with detailed timing
udown -d -o ~/Downloads [youtube_url]

# Combine options
udown -o ~/Videos -c -d [youtube_url]
```

### Command Line Options

| Option | Description |
|--------|-------------|
| `-o, --output` | Output directory (default: `./downloads`) |
| `-c, --caption` | Download captions/subtitles if available |
| `-d, --debug` | Enable debug mode with detailed timing |
| `--version` | Show version information |
| `-h, --help` | Show help message |

### Examples

```bash
# Download a video
udown -o ~/Downloads https://www.youtube.com/watch?v=dQw4w9WgXcQ

# Download with captions to Downloads folder
udown -c -o ~/Downloads https://www.youtube.com/watch?v=dQw4w9WgXcQ

# Debug mode to see performance metrics
udown -d -o ~/Downloads https://www.youtube.com/watch?v=dQw4w9WgXcQ
```

## Performance

The parallel processing approach provides significant time savings:

- **Sequential Download**: Audio + Video + Merge = Total Time
- **Parallel Download**: Max(Audio, Video) + Merge = Reduced Time

### Sample Output

```
Downloading: Example Video Title
Downloading Audio File
Downloading Video File
Video downloaded successfully to: ./downloads/Example Video Title.mp4

==================================================
DOWNLOAD PERFORMANCE REPORT
==================================================
Audio Took: 12.34 seconds
Video Took: 15.67 seconds
Merging Took: 2.45 seconds
Expected Duration: 30.46 seconds
Total Process Time: 18.23 seconds
==================================================
Time Saved: 12.23 seconds
==================================================
```

## Development

### Setup Development Environment

```bash
git clone https://github.com/dipanjal/udown.git
cd udown
make install
```

### Running Tests

```bash
pytest
```

### Code Formatting

```bash
black ytdl/
```

## Architecture

```
udown/
├── ytdl/
│   ├── __init__.py      # Package initialization
│   ├── cli.py           # Command-line interface
│   ├── downloader.py    # Core download logic
│   ├── profiler.py      # Performance timing
│   └── utils.py         # Utility functions
├── setup.py             # Package setup
├── pyproject.toml       # Modern packaging config
└── README.md           # This file
```

## How It Works

1. **URL Validation**: Validates YouTube URL format
2. **Stream Analysis**: Identifies best audio and video streams
3. **Parallel Downloads**: Downloads audio and video simultaneously
4. **FFmpeg Merge**: Combines streams into final video file
5. **Performance Profiling**: Tracks timing for optimization

## Contributing

1. Fork the repository
2. Create a 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

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- [pytubefix](https://github.com/pytubefix/pytubefix) - YouTube data extraction
- [FFmpeg](https://ffmpeg.org/) - Audio/video processing

## Support

- 📧 **Email**: dipanjalmaitra@gmail.com
- 🐛 **Issues**: [GitHub Issues](https://github.com/dipanjalmaitra/udown/issues)
- 📖 **Documentation**: [GitHub Wiki](https://github.com/dipanjalmaitra/udown/wiki)
