udown 0.0.2__py3-none-any.whl

udown-0.0.2.dist-info/METADATA

@@ -0,0 +1,234 @@
+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)

udown-0.0.2.dist-info/RECORD

@@ -0,0 +1,11 @@
+udown-0.0.2.dist-info/licenses/LICENSE,sha256=BNnWV5PsQHnuMltsEKuIuFsAHkR_ZUZWH3QAWVdenh0,1072
+ytdl/__init__.py,sha256=GGAGfModazmRoKb-I2Bauc5oY2FqjN0mrtR0m3_zsQw,297
+ytdl/cli.py,sha256=ExdVy-BVhu_VZKm3L2cAQn6oHFxJrTlhZZ0mJDZ2J0I,2864
+ytdl/downloader.py,sha256=ebZpMMqHraruKAT2LFBzdkMJ0HpBx6s9JvqnF6_T4PQ,4607
+ytdl/profiler.py,sha256=qekkm6SFob4e26pxpsG4SmLNqs7thTQNGRpfeK87IH4,2081
+ytdl/utils.py,sha256=-2Y_89n_RhTWfACAVR-_Dtyjpdq-5Px5J5xii-rPGt4,1188
+udown-0.0.2.dist-info/METADATA,sha256=yh7e48w7gFO2YWzuWVTynTd6DjVLpz5A5zG9O4zbKZY,6442
+udown-0.0.2.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+udown-0.0.2.dist-info/entry_points.txt,sha256=JogR0ArrJoCDi1JC-U1SzjWmVX-8cAqHKfrRBfNxiAU,40
+udown-0.0.2.dist-info/top_level.txt,sha256=S8I8RsIAG6qsXrOdAVauYxr2PGVaG-k_0tAnY6gEEVA,5
+udown-0.0.2.dist-info/RECORD,,

udown-0.0.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

udown-0.0.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+udown = ytdl.cli:main

udown-0.0.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Dipanjal Maitra
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

udown-0.0.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+ytdl

ytdl/__init__.py

@@ -0,0 +1,11 @@
+"""
+YouTube Downloader with Parallel Processing
+A fast YouTube video downloader that downloads audio and video streams in parallel.
+"""
+
+from .downloader import Downloader
+from .profiler import Profiler
+from .utils import Utils
+
+__version__ = "1.0.0"
+__all__ = ["Downloader", "Profiler", "Utils"]

ytdl/cli.py

@@ -0,0 +1,98 @@
+"""
+YouTube Downloader CLI
+A command-line interface for downloading YouTube videos with parallel processing.
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+from ytdl.downloader import Downloader
+
+
+def create_parser() -> argparse.ArgumentParser:
+    """Create and configure the argument parser."""
+    parser = argparse.ArgumentParser(
+        description="Download YouTube videos with parallel processing",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+            Examples:
+              %(prog)s https://www.youtube.com/watch?v=dQw4w9WgXcQ
+              %(prog)s -o /path/to/downloads https://www.youtube.com/watch?v=dQw4w9WgXcQ
+              %(prog)s -c -d https://www.youtube.com/watch?v=dQw4w9WgXcQ
+        """,
+    )
+    parser.add_argument("url", help="YouTube video URL to download")
+    parser.add_argument(
+        "-o",
+        "--output",
+        dest="output_dir",
+        help="Output directory for downloaded files (default: ./downloads)",
+    )
+    parser.add_argument(
+        "-c",
+        "--caption",
+        action="store_true",
+        help="Download captions/subtitles if available",
+    )
+    parser.add_argument(
+        "-d",
+        "--debug",
+        action="store_true",
+        help="Enable debug mode with detailed timing information",
+    )
+    parser.add_argument("--version", action="version", version="%(prog)s 1.0.0")
+    return parser
+
+
+def validate_url(url: str) -> bool:
+    """Validate if the URL is a valid YouTube URL."""
+    youtube_domains = ["youtube.com", "www.youtube.com", "youtu.be", "m.youtube.com"]
+
+    url_lower = url.lower()
+    return any(domain in url_lower for domain in youtube_domains)
+
+
+def main() -> None:
+    """Main CLI entry point."""
+    parser = create_parser()
+    args = parser.parse_args()
+
+    # Validate URL
+    if not validate_url(args.url):
+        print("Error: Please provide a valid YouTube URL")
+        print("Supported formats:")
+        print("  - https://www.youtube.com/watch?v=VIDEO_ID")
+        print("  - https://youtu.be/VIDEO_ID")
+        print("  - https://m.youtube.com/watch?v=VIDEO_ID")
+        sys.exit(1)
+
+    # Set output directory
+    output_dir = args.output_dir if args.output_dir else "./downloads"
+
+    # Create output directory if it doesn't exist
+    output_path = Path(output_dir)
+    output_path.mkdir(parents=True, exist_ok=True)
+
+    try:
+        # Initialize downloader
+        downloader = Downloader(
+            url=args.url,
+            out_dir=str(output_path),
+            caption=args.caption,
+            debug=args.debug,
+        )
+
+        # Start download
+        downloader.start()
+
+    except KeyboardInterrupt:
+        print("\nDownload cancelled by user")
+        sys.exit(1)
+    except Exception as e:
+        print(f"Error: {str(e)}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

ytdl/downloader.py

@@ -0,0 +1,126 @@
+import concurrent.futures
+import os
+from pathlib import Path
+
+from pytubefix import YouTube  # type: ignore
+from pytubefix.cli import on_progress  # type: ignore
+
+from ytdl.profiler import Profiler
+from ytdl.utils import Utils
+
+ROOT_DIR = Path(__file__).parent.parent.resolve()
+DOWNLOAD_DIR = ROOT_DIR / "downloads"
+TEMP_DIR = ROOT_DIR / "temp"
+
+
+class Downloader:
+    def __init__(
+        self,
+        url: str,
+        out_dir: str = str(DOWNLOAD_DIR),
+        caption: bool = False,
+        debug: bool = False,
+    ):
+        self.url = url
+        self.out_dir = out_dir
+        self.caption = caption
+        self.debug = debug
+        self._pre_config()
+
+    def _pre_config(self) -> None:
+        self.yt = YouTube(self.url, on_progress_callback=on_progress)
+        self.title = Utils.sanitize_filename(self.yt.title)
+        self.profiler = Profiler(self.debug)
+
+        # Setting up temp files
+        self.temp_video_file: Path = TEMP_DIR / "temp.mp4"
+        self.temp_audio_file: Path = TEMP_DIR / "temp.m4a"
+
+        # Create out directory if not exists
+        TEMP_DIR.mkdir(exist_ok=True)
+        DOWNLOAD_DIR.mkdir(exist_ok=True)
+        if self.out_dir != str(DOWNLOAD_DIR):
+            Path(self.out_dir).mkdir(exist_ok=True)
+
+    def _cleanup_temps(self) -> None:
+        # Clean up temporary files
+        Utils.delete_file(self.temp_video_file)
+        Utils.delete_file(self.temp_audio_file)
+
+    def _merge_with_ffmpeg(self) -> str:
+        self.profiler.start_timer("merging")
+        out_file_path: str = os.path.join(self.out_dir, f"{self.title}.mp4")
+        Utils.merge_with_ffmpeg(
+            video_file=str(self.temp_video_file),
+            audio_file=str(self.temp_audio_file),
+            out_file=out_file_path,
+        )
+        self.profiler.end_timer("merging")
+        return out_file_path
+
+    def _download_audio_file(self, file_path: Path) -> None:
+        """Download the best audio stream."""
+        print("Downloading Audio File")
+        self.profiler.start_timer("audio")
+        self.yt.streams.filter(only_audio=True).order_by("abr").desc().first().download(
+            output_path=str(file_path.parent), filename=file_path.name
+        )
+        self.profiler.end_timer("audio")
+
+    def _download_video_file(self, file_path: Path) -> None:
+        """Download the best video stream."""
+        print("Downloading Video File")
+        self.profiler.start_timer("video")
+        self.yt.streams.filter(only_video=True, file_extension="mp4").order_by("resolution").desc().first().download(
+            output_path=str(file_path.parent), filename=file_path.name
+        )
+        self.profiler.end_timer("video")
+
+    def _download_caption_file(self) -> None:
+        caption = self.yt.captions.get("a.en", None)
+        if not caption:
+            print("No caption found")
+            return
+
+        out_file_path: str = os.path.join(self.out_dir, f"{self.title}.srt")
+        try:
+            self.profiler.start_timer("caption")
+            print("Downloading Caption File")
+            caption.save_captions(out_file_path)
+            self.profiler.end_timer("caption")
+        except Exception as e:
+            print("Unable to download caption file: ", str(e))
+            Utils.delete_file(out_file_path)
+
+    def _download(self) -> None:
+        with concurrent.futures.ThreadPoolExecutor() as executor:
+            # Submit video and audio download tasks
+            future_video = executor.submit(self._download_video_file, self.temp_video_file)
+            future_audio = executor.submit(self._download_audio_file, self.temp_audio_file)
+
+            # Submit caption download task if caption is requested
+            futures = [future_video, future_audio]
+            if self.caption:
+                future_caption = executor.submit(self._download_caption_file)
+                futures.append(future_caption)
+
+            # Wait for all downloads to complete
+            concurrent.futures.wait(futures)
+
+    def start(self) -> None:
+        """Download video and audio, then merge them with FFmpeg."""
+        print(f"Downloading: {self.title}")
+        self.profiler.start_overall_timer()
+
+        try:
+            self._cleanup_temps()
+            self._download()
+            out_file_path: str = self._merge_with_ffmpeg()
+            print(f"Video downloaded successfully to: {out_file_path}")
+        except Exception as e:
+            print(f"Video downloaded failed due to unknown error: {str(e)}")
+        finally:
+            self._cleanup_temps()
+
+        self.profiler.end_overall_timer()
+        self.profiler.print_report()

ytdl/profiler.py

@@ -0,0 +1,56 @@
+import time
+from typing import Optional
+
+
+class Profiler:
+    def __init__(self, debug: bool = False):
+        self.timings: dict[str, dict[str, float]] = {}
+        self.start_time: Optional[float] = None
+        self.debug = debug
+
+    def start_timer(self, name: str) -> None:
+        """Start timing a specific operation."""
+        self.timings[name] = {"start": time.time()}
+
+    def end_timer(self, name: str) -> None:
+        """End timing a specific operation and calculate duration."""
+        if name in self.timings:
+            self.timings[name]["end"] = time.time()
+            self.timings[name]["duration"] = self.timings[name]["end"] - self.timings[name]["start"]
+
+    def start_overall_timer(self) -> None:
+        """Start the overall process timer."""
+        self.start_time = time.time()
+
+    def end_overall_timer(self) -> None:
+        """End the overall process timer and calculate total duration."""
+        if self.start_time:
+            total_duration = time.time() - self.start_time
+            self.timings["total"] = {"duration": total_duration}
+
+    def print_report(self) -> None:
+        """Print a formatted timing report."""
+        sum_of_duration: float = 0.0
+        if self.debug:
+            print("\n" + "=" * 50)
+            print("DOWNLOAD PERFORMANCE REPORT")
+            print("=" * 50)
+
+            for name, timing in self.timings.items():
+                if name != "total":
+                    duration = timing.get("duration", 0)
+                    sum_of_duration += duration
+                    print(f"{name.capitalize()} Took: {duration:.2f} seconds")
+
+            print("=" * 50)
+
+        if "total" in self.timings:
+            if self.debug:
+                print(f"Expected Duration: {sum_of_duration:.2f} seconds")
+
+            actual_total_duration = self.timings["total"]["duration"]
+            print(f"Total Process Time: {actual_total_duration:.2f} seconds")
+
+            if self.debug:
+                print("=" * 50)
+                print(f"Time Saved: {(sum_of_duration - actual_total_duration):.2f} seconds")

ytdl/utils.py

@@ -0,0 +1,46 @@
+import os
+import re
+import subprocess
+from pathlib import Path
+from typing import Union
+
+
+class Utils:
+    @staticmethod
+    def sanitize_filename(name: str) -> str:
+        """Sanitize a string to be a valid filename."""
+        return re.sub(r'[\\/*?:"<>|]', "", name)
+
+    @staticmethod
+    def delete_file(file_path: Union[Path, str]) -> None:
+        if isinstance(file_path, str):
+            file_path = Path(file_path)
+
+        if file_path.exists():
+            os.remove(file_path)
+
+    @staticmethod
+    def merge_with_ffmpeg(video_file: str, audio_file: str, out_file: str, debug: bool = False) -> None:
+        """
+        Merge video and audio using ffmpeg via subprocess.
+        """
+        cmd = [
+            "ffmpeg",
+            "-y",  # Overwrite output file if it exists
+            "-i",
+            video_file,
+            "-i",
+            audio_file,
+            "-c:v",
+            "copy",
+            "-c:a",
+            "aac",
+            "-map",
+            "0:v:0",
+            "-map",
+            "1:a:0",
+            out_file,
+        ]
+        if debug:
+            print("Running ffmpeg command:", " ".join(cmd))
+        subprocess.run(cmd, check=True)