ytconvert-cli 1.0.0__py3-none-any.whl

ytconvert/__init__.py

@@ -0,0 +1,27 @@
+"""
+ytconvert-cli: A YouTube video converter CLI tool.
+
+Convert YouTube videos to MP3 or MP4 using yt-dlp.
+"""
+
+__version__ = "1.0.0"
+__author__ = "ytconvert-cli"
+
+from ytconvert.converter import YouTubeConverter
+from ytconvert.exceptions import (
+    YTConvertError,
+    InvalidURLError,
+    DownloadError,
+    FormatUnavailableError,
+    UnexpectedError,
+)
+
+__all__ = [
+    "YouTubeConverter",
+    "YTConvertError",
+    "InvalidURLError",
+    "DownloadError",
+    "FormatUnavailableError",
+    "UnexpectedError",
+    "__version__",
+]

ytconvert/cli.py

@@ -0,0 +1,146 @@
+"""
+CLI entry point for ytconvert-cli.
+"""
+
+import sys
+from pathlib import Path
+from typing import Optional
+
+import typer
+from typing_extensions import Annotated
+
+from ytconvert import __version__
+from ytconvert.converter import YouTubeConverter
+from ytconvert.exceptions import (
+    ExitCode,
+    InvalidURLError,
+    DownloadError,
+    FormatUnavailableError,
+    YTConvertError,
+)
+from ytconvert.utils import (
+    print_error,
+    print_info,
+    print_success,
+    setup_logging,
+)
+from ytconvert.validators import VALID_FORMATS, VALID_QUALITIES
+
+
+def version_callback(value: bool) -> None:
+    if value:
+        print(f"ytconvert-cli version {__version__}")
+        raise typer.Exit()
+
+
+def main(
+    url: Annotated[
+        str,
+        typer.Argument(help="YouTube video URL to convert"),
+    ],
+    format: Annotated[
+        str,
+        typer.Option("--format", "-f", help="Output format: mp3 or mp4"),
+    ] = "mp3",
+    quality: Annotated[
+        str,
+        typer.Option("--quality", "-q", help="Video quality for MP4 (360p, 720p, 1080p, best)"),
+    ] = "best",
+    output: Annotated[
+        Optional[Path],
+        typer.Option("--output", "-o", help="Output directory"),
+    ] = None,
+    verbose: Annotated[
+        bool,
+        typer.Option("--verbose", "-v", help="Enable verbose output"),
+    ] = False,
+    info_only: Annotated[
+        bool,
+        typer.Option("--info", "-i", help="Only show video info, don't download"),
+    ] = False,
+    version: Annotated[
+        Optional[bool],
+        typer.Option("--version", "-V", help="Show version", callback=version_callback, is_eager=True),
+    ] = None,
+) -> None:
+    """Convert YouTube videos to MP3 or MP4 format."""
+    setup_logging(verbose=verbose)
+    
+    if info_only:
+        try:
+            converter = YouTubeConverter(verbose=verbose)
+            info = converter.get_video_info(url)
+            print()
+            print_info(f"Title: {info.get('title', 'Unknown')}")
+            duration = info.get('duration', 0) or 0
+            print_info(f"Duration: {int(duration) // 60}:{int(duration) % 60:02d}")
+            print_info(f"Uploader: {info.get('uploader', 'Unknown')}")
+            views = info.get('view_count', 0) or 0
+            print_info(f"Views: {views:,}")
+            sys.exit(ExitCode.SUCCESS)
+        except YTConvertError as e:
+            print_error(str(e))
+            sys.exit(e.exit_code)
+        except SystemExit:
+            raise
+        except Exception as e:
+            print_error(f"Unexpected error: {e}")
+            raise typer.Exit(code=ExitCode.UNEXPECTED_ERROR)
+    
+    format_lower = format.lower()
+    if format_lower not in VALID_FORMATS:
+        print_error(f"Invalid format '{format}'. Must be: {', '.join(VALID_FORMATS)}")
+        raise typer.Exit(code=ExitCode.INVALID_URL)
+    
+    quality_lower = quality.lower()
+    if format_lower == "mp4" and quality_lower not in VALID_QUALITIES:
+        print_error(f"Invalid quality '{quality}'. Must be: {', '.join(VALID_QUALITIES)}")
+        raise typer.Exit(code=ExitCode.FORMAT_UNAVAILABLE)
+    
+    output_dir = output if output else Path.cwd()
+    
+    print_info(f"URL: {url}")
+    print_info(f"Format: {format_lower.upper()}")
+    if format_lower == "mp4":
+        print_info(f"Quality: {quality_lower}")
+    print_info(f"Output: {output_dir}")
+    print()
+    
+    try:
+        converter = YouTubeConverter(output_dir=output_dir, verbose=verbose)
+        output_path = converter.convert(url=url, format_type=format_lower, quality=quality_lower)
+        print()
+        print_success("Conversion completed successfully!")
+        print_success(f"Output file: {output_path}")
+        sys.exit(ExitCode.SUCCESS)
+    except InvalidURLError as e:
+        print_error(str(e))
+        sys.exit(ExitCode.INVALID_URL)
+    except DownloadError as e:
+        print_error(str(e))
+        sys.exit(ExitCode.DOWNLOAD_FAILURE)
+    except FormatUnavailableError as e:
+        print_error(str(e))
+        sys.exit(ExitCode.FORMAT_UNAVAILABLE)
+    except YTConvertError as e:
+        print_error(str(e))
+        sys.exit(e.exit_code)
+    except KeyboardInterrupt:
+        print_error("Operation cancelled by user")
+        sys.exit(ExitCode.UNEXPECTED_ERROR)
+    except SystemExit:
+        raise
+    except Exception as e:
+        print_error(f"Unexpected error: {e}")
+        if verbose:
+            import traceback
+            traceback.print_exc()
+        sys.exit(ExitCode.UNEXPECTED_ERROR)
+
+
+def cli() -> None:
+    typer.run(main)
+
+
+if __name__ == "__main__":
+    cli()

ytconvert/converter.py

@@ -0,0 +1,355 @@
+"""
+YouTube video converter using yt-dlp.
+
+This module provides the core conversion functionality for downloading
+YouTube videos and converting them to MP3 or MP4 format.
+"""
+
+import os
+from pathlib import Path
+from typing import Any, Callable
+
+import imageio_ffmpeg
+import yt_dlp
+
+from ytconvert.exceptions import (
+    DownloadError,
+    FormatUnavailableError,
+    InvalidURLError,
+    UnexpectedError,
+)
+from ytconvert.utils import (
+    ensure_directory,
+    format_duration,
+    format_filesize,
+    get_logger,
+    get_quality_height,
+    print_info,
+    print_progress,
+    print_success,
+    sanitize_filename,
+)
+from ytconvert.validators import extract_video_id, validate_youtube_url
+
+
+class ProgressHook:
+    """Progress hook for yt-dlp to display download progress."""
+    
+    def __init__(self, callback: Callable[[dict[str, Any]], None] | None = None):
+        self.callback = callback
+        self._last_percent = -1
+    
+    def __call__(self, d: dict[str, Any]) -> None:
+        """Handle progress updates from yt-dlp."""
+        status = d.get("status")
+        
+        if status == "downloading":
+            total = d.get("total_bytes") or d.get("total_bytes_estimate", 0)
+            downloaded = d.get("downloaded_bytes", 0)
+            
+            if total > 0:
+                percent = int((downloaded / total) * 100)
+                # Only print on significant changes to reduce noise
+                if percent != self._last_percent and percent % 10 == 0:
+                    speed = d.get("speed", 0)
+                    speed_str = f"{format_filesize(speed)}/s" if speed else "-- KB/s"
+                    eta = d.get("eta", 0)
+                    eta_str = format_duration(eta) if eta else "--:--"
+                    
+                    print_progress(
+                        f"Downloading: {percent}% | "
+                        f"Speed: {speed_str} | "
+                        f"ETA: {eta_str}"
+                    )
+                    self._last_percent = percent
+        
+        elif status == "finished":
+            filename = d.get("filename", "Unknown")
+            print_success(f"Download complete: {Path(filename).name}")
+        
+        elif status == "error":
+            get_logger().error("Download encountered an error")
+        
+        if self.callback:
+            self.callback(d)
+
+
+class YouTubeConverter:
+    """
+    YouTube video converter using yt-dlp.
+    
+    Provides methods to download and convert YouTube videos to MP3 or MP4 format.
+    """
+    
+    def __init__(
+        self,
+        output_dir: str | Path = ".",
+        verbose: bool = False,
+        progress_callback: Callable[[dict[str, Any]], None] | None = None,
+    ):
+        """
+        Initialize the YouTube converter.
+        
+        Args:
+            output_dir: Directory where converted files will be saved
+            verbose: If True, enable verbose logging
+            progress_callback: Optional callback for progress updates
+        """
+        self.output_dir = ensure_directory(Path(output_dir))
+        self.verbose = verbose
+        self.progress_callback = progress_callback
+        self.logger = get_logger()
+    
+    def _get_ffmpeg_path(self) -> str:
+        """Get the path to the bundled FFmpeg executable."""
+        return imageio_ffmpeg.get_ffmpeg_exe()
+    
+    def _get_base_options(self) -> dict[str, Any]:
+        """Get base yt-dlp options common to all downloads."""
+        return {
+            "outtmpl": str(self.output_dir / "%(title)s.%(ext)s"),
+            "restrictfilenames": False,
+            "noplaylist": True,
+            "quiet": not self.verbose,
+            "no_warnings": not self.verbose,
+            "progress_hooks": [ProgressHook(self.progress_callback)],
+            "retries": 3,
+            "fragment_retries": 3,
+            "ignoreerrors": False,
+            "nocheckcertificate": False,
+            "ffmpeg_location": self._get_ffmpeg_path(),
+        }
+    
+    def _get_mp3_options(self) -> dict[str, Any]:
+        """Get yt-dlp options for MP3 conversion."""
+        options = self._get_base_options()
+        options.update({
+            "format": "bestaudio/best",
+            "postprocessors": [{
+                "key": "FFmpegExtractAudio",
+                "preferredcodec": "mp3",
+                "preferredquality": "192",
+            }],
+            "outtmpl": str(self.output_dir / "%(title)s.%(ext)s"),
+        })
+        return options
+    
+    def _get_mp4_options(self, quality: str = "best") -> dict[str, Any]:
+        """
+        Get yt-dlp options for MP4 download.
+        
+        Args:
+            quality: Video quality (e.g., "720p", "1080p", "best")
+        """
+        options = self._get_base_options()
+        
+        height = get_quality_height(quality)
+        
+        if height:
+            # Request specific quality with fallback
+            format_str = (
+                f"bestvideo[height<={height}][ext=mp4]+bestaudio[ext=m4a]/best[height<={height}][ext=mp4]/"
+                f"bestvideo[height<={height}]+bestaudio/best[height<={height}]/best"
+            )
+        else:
+            # Best quality available
+            format_str = "bestvideo[ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]/bestvideo+bestaudio/best"
+        
+        options.update({
+            "format": format_str,
+            "merge_output_format": "mp4",
+            "postprocessors": [{
+                "key": "FFmpegVideoConvertor",
+                "preferedformat": "mp4",
+            }],
+        })
+        return options
+    
+    def get_video_info(self, url: str) -> dict[str, Any]:
+        """
+        Get information about a YouTube video without downloading.
+        
+        Args:
+            url: YouTube video URL
+            
+        Returns:
+            Dictionary containing video metadata
+            
+        Raises:
+            InvalidURLError: If the URL is invalid
+            DownloadError: If video info cannot be retrieved
+        """
+        url = validate_youtube_url(url)
+        
+        options = {
+            "quiet": True,
+            "no_warnings": True,
+            "extract_flat": False,
+        }
+        
+        try:
+            with yt_dlp.YoutubeDL(options) as ydl:
+                info = ydl.extract_info(url, download=False)
+                
+                if not info:
+                    raise DownloadError("Failed to retrieve video information")
+                
+                return {
+                    "id": info.get("id"),
+                    "title": info.get("title"),
+                    "duration": info.get("duration"),
+                    "description": info.get("description"),
+                    "thumbnail": info.get("thumbnail"),
+                    "uploader": info.get("uploader"),
+                    "view_count": info.get("view_count"),
+                    "like_count": info.get("like_count"),
+                    "formats": [
+                        {
+                            "format_id": f.get("format_id"),
+                            "ext": f.get("ext"),
+                            "resolution": f.get("resolution"),
+                            "filesize": f.get("filesize"),
+                        }
+                        for f in info.get("formats", [])
+                    ],
+                }
+        
+        except yt_dlp.utils.DownloadError as e:
+            error_msg = str(e)
+            if "Video unavailable" in error_msg or "Private video" in error_msg:
+                raise DownloadError(f"Video is unavailable or private: {error_msg}")
+            raise DownloadError(f"Failed to get video info: {error_msg}")
+        except Exception as e:
+            raise UnexpectedError(f"Unexpected error getting video info: {e}")
+    
+    def convert_to_mp3(self, url: str) -> Path:
+        """
+        Download and convert a YouTube video to MP3.
+        
+        Args:
+            url: YouTube video URL
+            
+        Returns:
+            Path to the converted MP3 file
+            
+        Raises:
+            InvalidURLError: If the URL is invalid
+            DownloadError: If download fails
+            FormatUnavailableError: If MP3 conversion fails
+        """
+        url = validate_youtube_url(url)
+        
+        print_info("Starting MP3 conversion...")
+        self.logger.info(f"Converting to MP3: {url}")
+        
+        options = self._get_mp3_options()
+        
+        try:
+            with yt_dlp.YoutubeDL(options) as ydl:
+                info = ydl.extract_info(url, download=True)
+                
+                if not info:
+                    raise DownloadError("Failed to download video")
+                
+                # Determine output filename
+                title = sanitize_filename(info.get("title", "video"))
+                output_path = self.output_dir / f"{title}.mp3"
+                
+                # yt-dlp might use a different filename, try to find it
+                if not output_path.exists():
+                    # Look for any recently created mp3 file
+                    mp3_files = list(self.output_dir.glob("*.mp3"))
+                    if mp3_files:
+                        # Get the most recently modified mp3 file
+                        output_path = max(mp3_files, key=lambda p: p.stat().st_mtime)
+                
+                print_success(f"Successfully converted to MP3: {output_path.name}")
+                return output_path
+        
+        except yt_dlp.utils.DownloadError as e:
+            error_msg = str(e)
+            if "format" in error_msg.lower():
+                raise FormatUnavailableError(f"Audio format unavailable: {error_msg}")
+            raise DownloadError(f"Download failed: {error_msg}")
+        except Exception as e:
+            if isinstance(e, (InvalidURLError, DownloadError, FormatUnavailableError)):
+                raise
+            raise UnexpectedError(f"Unexpected error during MP3 conversion: {e}")
+    
+    def convert_to_mp4(self, url: str, quality: str = "best") -> Path:
+        """
+        Download a YouTube video as MP4.
+        
+        Args:
+            url: YouTube video URL
+            quality: Video quality (e.g., "720p", "1080p", "best")
+            
+        Returns:
+            Path to the downloaded MP4 file
+            
+        Raises:
+            InvalidURLError: If the URL is invalid
+            DownloadError: If download fails
+            FormatUnavailableError: If requested quality is unavailable
+        """
+        url = validate_youtube_url(url)
+        
+        print_info(f"Starting MP4 download (quality: {quality})...")
+        self.logger.info(f"Converting to MP4 with quality '{quality}': {url}")
+        
+        options = self._get_mp4_options(quality)
+        
+        try:
+            with yt_dlp.YoutubeDL(options) as ydl:
+                info = ydl.extract_info(url, download=True)
+                
+                if not info:
+                    raise DownloadError("Failed to download video")
+                
+                # Determine output filename
+                title = sanitize_filename(info.get("title", "video"))
+                output_path = self.output_dir / f"{title}.mp4"
+                
+                # yt-dlp might use a different filename, try to find it
+                if not output_path.exists():
+                    # Look for any recently created mp4 file
+                    mp4_files = list(self.output_dir.glob("*.mp4"))
+                    if mp4_files:
+                        # Get the most recently modified mp4 file
+                        output_path = max(mp4_files, key=lambda p: p.stat().st_mtime)
+                
+                print_success(f"Successfully downloaded MP4: {output_path.name}")
+                return output_path
+        
+        except yt_dlp.utils.DownloadError as e:
+            error_msg = str(e)
+            if "format" in error_msg.lower() or "quality" in error_msg.lower():
+                raise FormatUnavailableError(
+                    f"Requested quality '{quality}' unavailable: {error_msg}"
+                )
+            raise DownloadError(f"Download failed: {error_msg}")
+        except Exception as e:
+            if isinstance(e, (InvalidURLError, DownloadError, FormatUnavailableError)):
+                raise
+            raise UnexpectedError(f"Unexpected error during MP4 download: {e}")
+    
+    def convert(self, url: str, format_type: str, quality: str = "best") -> Path:
+        """
+        Convert a YouTube video to the specified format.
+        
+        Args:
+            url: YouTube video URL
+            format_type: Output format ("mp3" or "mp4")
+            quality: Video quality for MP4 (ignored for MP3)
+            
+        Returns:
+            Path to the converted file
+        """
+        format_type = format_type.lower()
+        
+        if format_type == "mp3":
+            return self.convert_to_mp3(url)
+        elif format_type == "mp4":
+            return self.convert_to_mp4(url, quality)
+        else:
+            raise ValueError(f"Unsupported format: {format_type}")

ytconvert/exceptions.py

@@ -0,0 +1,69 @@
+"""
+Custom exceptions for ytconvert-cli.
+
+Exit codes:
+    0 = success
+    1 = invalid URL
+    2 = download failure
+    3 = format/quality unavailable
+    4 = unexpected error
+"""
+
+from enum import IntEnum
+
+
+class ExitCode(IntEnum):
+    """Exit codes for the CLI application."""
+    
+    SUCCESS = 0
+    INVALID_URL = 1
+    DOWNLOAD_FAILURE = 2
+    FORMAT_UNAVAILABLE = 3
+    UNEXPECTED_ERROR = 4
+
+
+class YTConvertError(Exception):
+    """Base exception for ytconvert-cli errors."""
+    
+    exit_code: int = ExitCode.UNEXPECTED_ERROR
+    
+    def __init__(self, message: str, exit_code: int | None = None):
+        super().__init__(message)
+        if exit_code is not None:
+            self.exit_code = exit_code
+
+
+class InvalidURLError(YTConvertError):
+    """Raised when the provided URL is not a valid YouTube URL."""
+    
+    exit_code = ExitCode.INVALID_URL
+    
+    def __init__(self, message: str = "Invalid YouTube URL provided"):
+        super().__init__(message, self.exit_code)
+
+
+class DownloadError(YTConvertError):
+    """Raised when the download process fails."""
+    
+    exit_code = ExitCode.DOWNLOAD_FAILURE
+    
+    def __init__(self, message: str = "Failed to download video"):
+        super().__init__(message, self.exit_code)
+
+
+class FormatUnavailableError(YTConvertError):
+    """Raised when the requested format or quality is not available."""
+    
+    exit_code = ExitCode.FORMAT_UNAVAILABLE
+    
+    def __init__(self, message: str = "Requested format or quality unavailable"):
+        super().__init__(message, self.exit_code)
+
+
+class UnexpectedError(YTConvertError):
+    """Raised when an unexpected error occurs."""
+    
+    exit_code = ExitCode.UNEXPECTED_ERROR
+    
+    def __init__(self, message: str = "An unexpected error occurred"):
+        super().__init__(message, self.exit_code)

ytconvert/utils.py

@@ -0,0 +1,186 @@
+"""
+Utility functions for ytconvert-cli.
+"""
+
+import logging
+import sys
+from pathlib import Path
+from typing import Any
+
+# ANSI color codes for terminal output
+class Colors:
+    """ANSI color codes for terminal styling."""
+    
+    RESET = "\033[0m"
+    BOLD = "\033[1m"
+    RED = "\033[91m"
+    GREEN = "\033[92m"
+    YELLOW = "\033[93m"
+    BLUE = "\033[94m"
+    MAGENTA = "\033[95m"
+    CYAN = "\033[96m"
+
+
+def setup_logging(verbose: bool = False) -> logging.Logger:
+    """
+    Set up logging for the CLI application.
+    
+    Args:
+        verbose: If True, set log level to DEBUG; otherwise INFO
+        
+    Returns:
+        Configured logger instance
+    """
+    logger = logging.getLogger("ytconvert")
+    logger.setLevel(logging.DEBUG if verbose else logging.INFO)
+    
+    # Remove existing handlers
+    logger.handlers.clear()
+    
+    # Create console handler with formatting
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setLevel(logging.DEBUG if verbose else logging.INFO)
+    
+    formatter = logging.Formatter(
+        fmt="%(asctime)s - %(levelname)s - %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S"
+    )
+    handler.setFormatter(formatter)
+    logger.addHandler(handler)
+    
+    return logger
+
+
+def get_logger() -> logging.Logger:
+    """Get the ytconvert logger instance."""
+    return logging.getLogger("ytconvert")
+
+
+def print_success(message: str) -> None:
+    """Print a success message in green."""
+    print(f"{Colors.GREEN}✓ {message}{Colors.RESET}")
+
+
+def print_error(message: str) -> None:
+    """Print an error message in red."""
+    print(f"{Colors.RED}✗ {message}{Colors.RESET}", file=sys.stderr)
+
+
+def print_warning(message: str) -> None:
+    """Print a warning message in yellow."""
+    print(f"{Colors.YELLOW}⚠ {message}{Colors.RESET}", file=sys.stderr)
+
+
+def print_info(message: str) -> None:
+    """Print an info message in blue."""
+    print(f"{Colors.BLUE}ℹ {message}{Colors.RESET}")
+
+
+def print_progress(message: str) -> None:
+    """Print a progress message in cyan."""
+    print(f"{Colors.CYAN}→ {message}{Colors.RESET}")
+
+
+def ensure_directory(path: Path) -> Path:
+    """
+    Ensure a directory exists, creating it if necessary.
+    
+    Args:
+        path: Path to the directory
+        
+    Returns:
+        The resolved absolute path to the directory
+    """
+    path = Path(path).resolve()
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def format_filesize(size_bytes: int | float) -> str:
+    """
+    Format a file size in bytes to a human-readable string.
+    
+    Args:
+        size_bytes: Size in bytes
+        
+    Returns:
+        Human-readable size string (e.g., "15.5 MB")
+    """
+    if size_bytes < 0:
+        return "Unknown"
+    
+    for unit in ["B", "KB", "MB", "GB", "TB"]:
+        if abs(size_bytes) < 1024.0:
+            return f"{size_bytes:.1f} {unit}"
+        size_bytes /= 1024.0
+    
+    return f"{size_bytes:.1f} PB"
+
+
+def format_duration(seconds: int | float) -> str:
+    """
+    Format a duration in seconds to HH:MM:SS format.
+    
+    Args:
+        seconds: Duration in seconds
+        
+    Returns:
+        Formatted duration string
+    """
+    if seconds < 0:
+        return "Unknown"
+    
+    hours, remainder = divmod(int(seconds), 3600)
+    minutes, secs = divmod(remainder, 60)
+    
+    if hours > 0:
+        return f"{hours}:{minutes:02d}:{secs:02d}"
+    return f"{minutes}:{secs:02d}"
+
+
+def sanitize_filename(filename: str) -> str:
+    """
+    Sanitize a filename by removing invalid characters.
+    
+    Args:
+        filename: The filename to sanitize
+        
+    Returns:
+        Sanitized filename safe for use on most filesystems
+    """
+    # Characters not allowed in filenames on Windows
+    invalid_chars = '<>:"/\\|?*'
+    
+    for char in invalid_chars:
+        filename = filename.replace(char, "_")
+    
+    # Remove leading/trailing spaces and dots
+    filename = filename.strip(". ")
+    
+    # Ensure filename is not empty
+    if not filename:
+        filename = "untitled"
+    
+    return filename
+
+
+def get_quality_height(quality: str) -> int | None:
+    """
+    Convert a quality string to a height value.
+    
+    Args:
+        quality: Quality string (e.g., "720p", "1080p")
+        
+    Returns:
+        Height in pixels, or None for "best"
+    """
+    quality_map = {
+        "360p": 360,
+        "480p": 480,
+        "720p": 720,
+        "1080p": 1080,
+        "1440p": 1440,
+        "2160p": 2160,
+        "best": None,
+    }
+    return quality_map.get(quality.lower())

ytconvert/validators.py

@@ -0,0 +1,133 @@
+"""
+URL and input validation utilities for ytconvert-cli.
+"""
+
+import re
+from urllib.parse import urlparse, parse_qs
+
+from ytconvert.exceptions import InvalidURLError
+
+
+# Supported YouTube URL patterns
+YOUTUBE_PATTERNS = [
+    # Standard watch URLs
+    r"^(https?://)?(www\.)?youtube\.com/watch\?.*v=[\w-]+",
+    # Short URLs
+    r"^(https?://)?(www\.)?youtu\.be/[\w-]+",
+    # Embed URLs
+    r"^(https?://)?(www\.)?youtube\.com/embed/[\w-]+",
+    # Mobile URLs
+    r"^(https?://)?(m\.)?youtube\.com/watch\?.*v=[\w-]+",
+    # YouTube Shorts
+    r"^(https?://)?(www\.)?youtube\.com/shorts/[\w-]+",
+    # YouTube Live
+    r"^(https?://)?(www\.)?youtube\.com/live/[\w-]+",
+]
+
+# Valid output formats
+VALID_FORMATS = ["mp3", "mp4"]
+
+# Valid quality options for MP4
+VALID_QUALITIES = ["360p", "480p", "720p", "1080p", "1440p", "2160p", "best"]
+
+
+def validate_youtube_url(url: str) -> str:
+    """
+    Validate that the provided URL is a valid YouTube URL.
+    
+    Args:
+        url: The URL to validate
+        
+    Returns:
+        The validated URL (normalized if necessary)
+        
+    Raises:
+        InvalidURLError: If the URL is not a valid YouTube URL
+    """
+    if not url:
+        raise InvalidURLError("URL cannot be empty")
+    
+    url = url.strip()
+    
+    # Check against known YouTube URL patterns
+    for pattern in YOUTUBE_PATTERNS:
+        if re.match(pattern, url, re.IGNORECASE):
+            return url
+    
+    raise InvalidURLError(f"Invalid YouTube URL: {url}")
+
+
+def extract_video_id(url: str) -> str | None:
+    """
+    Extract the video ID from a YouTube URL.
+    
+    Args:
+        url: A valid YouTube URL
+        
+    Returns:
+        The video ID if found, None otherwise
+    """
+    # Handle youtu.be short URLs
+    if "youtu.be" in url:
+        parsed = urlparse(url)
+        return parsed.path.lstrip("/").split("?")[0]
+    
+    # Handle youtube.com/shorts/ URLs
+    if "/shorts/" in url:
+        match = re.search(r"/shorts/([\w-]+)", url)
+        return match.group(1) if match else None
+    
+    # Handle youtube.com/live/ URLs
+    if "/live/" in url:
+        match = re.search(r"/live/([\w-]+)", url)
+        return match.group(1) if match else None
+    
+    # Handle youtube.com/embed/ URLs
+    if "/embed/" in url:
+        match = re.search(r"/embed/([\w-]+)", url)
+        return match.group(1) if match else None
+    
+    # Handle standard watch URLs
+    parsed = urlparse(url)
+    query_params = parse_qs(parsed.query)
+    video_ids = query_params.get("v", [])
+    
+    return video_ids[0] if video_ids else None
+
+
+def validate_format(format_type: str) -> str:
+    """
+    Validate the output format.
+    
+    Args:
+        format_type: The format to validate (mp3 or mp4)
+        
+    Returns:
+        The validated format in lowercase
+        
+    Raises:
+        ValueError: If the format is not valid
+    """
+    format_lower = format_type.lower()
+    if format_lower not in VALID_FORMATS:
+        raise ValueError(f"Invalid format '{format_type}'. Must be one of: {', '.join(VALID_FORMATS)}")
+    return format_lower
+
+
+def validate_quality(quality: str) -> str:
+    """
+    Validate the quality option for MP4.
+    
+    Args:
+        quality: The quality to validate (e.g., 720p, 1080p)
+        
+    Returns:
+        The validated quality string
+        
+    Raises:
+        ValueError: If the quality is not valid
+    """
+    quality_lower = quality.lower()
+    if quality_lower not in VALID_QUALITIES:
+        raise ValueError(f"Invalid quality '{quality}'. Must be one of: {', '.join(VALID_QUALITIES)}")
+    return quality_lower

ytconvert_cli-1.0.0.dist-info/METADATA

@@ -0,0 +1,224 @@
+Metadata-Version: 2.4
+Name: ytconvert-cli
+Version: 1.0.0
+Summary: A command-line tool to convert YouTube videos to MP3 or MP4 using yt-dlp
+Project-URL: Homepage, https://github.com/yourusername/ytconvert-cli
+Project-URL: Documentation, https://github.com/yourusername/ytconvert-cli#readme
+Project-URL: Repository, https://github.com/yourusername/ytconvert-cli
+Project-URL: Issues, https://github.com/yourusername/ytconvert-cli/issues
+Project-URL: Changelog, https://github.com/yourusername/ytconvert-cli/blob/main/CHANGELOG.md
+Author: ytconvert-cli contributors
+License: MIT
+License-File: LICENSE
+Keywords: audio,cli,converter,download,mp3,mp4,video,youtube,yt-dlp
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: imageio-ffmpeg>=0.4.9
+Requires-Dist: typer>=0.9.0
+Requires-Dist: typing-extensions>=4.0.0
+Requires-Dist: yt-dlp>=2024.1.0
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+
+# ytconvert-cli
+
+**Production-ready YouTube to MP3/MP4 converter.**
+
+[![PyPI version](https://img.shields.io/pypi/v/ytconvert-cli.svg)](https://pypi.org/project/ytconvert-cli/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## 🚀 Features
+
+- Convert YouTube videos to **MP3** (audio extraction)
+- Download YouTube videos as **MP4** (with quality selection)
+- Custom output directory support
+- Progress indicators with download speed and ETA
+- Clean error handling with specific exit codes
+- **FFmpeg is bundled**—no separate install needed
+- Uses yt-dlp Python API (no shell calls)
+- Pip-installable and PyPI-ready
+
+---
+
+## 📦 Installation
+
+### From PyPI (recommended)
+
+```bash
+pip install ytconvert-cli
+```
+
+### From source
+
+```bash
+git clone https://github.com/yourusername/ytconvert-cli.git
+cd ytconvert-cli
+pip install .
+```
+
+---
+
+## 🖥️ CLI Usage
+
+```bash
+# Convert to MP3 (default)
+ytconvert https://www.youtube.com/watch?v=VIDEO_ID
+
+# Convert to MP4
+ytconvert https://www.youtube.com/watch?v=VIDEO_ID --format mp4
+
+# MP4 with specific quality
+ytconvert https://www.youtube.com/watch?v=VIDEO_ID --format mp4 --quality 720p
+
+# Save to custom directory
+ytconvert https://www.youtube.com/watch?v=VIDEO_ID -f mp3 -o ./downloads
+
+# Get video info only (no download)
+ytconvert https://www.youtube.com/watch?v=VIDEO_ID --info
+
+# Show help
+ytconvert --help
+```
+
+**Short options:**
+| Long      | Short | Description         |
+|-----------|-------|---------------------|
+| --format  | -f    | mp3 or mp4          |
+| --quality | -q    | Video quality       |
+| --output  | -o    | Output directory    |
+| --info    | -i    | Info only           |
+| --verbose | -v    | Debug mode          |
+| --version | -V    | Show version        |
+
+---
+
+## 🐍 Python API Usage
+
+```python
+from ytconvert import YouTubeConverter
+
+# Convert to MP3
+converter = YouTubeConverter(output_dir="./downloads")
+mp3_path = converter.convert_to_mp3("https://youtube.com/watch?v=VIDEO_ID")
+print(f"Saved: {mp3_path}")
+
+# Convert to MP4 with quality
+mp4_path = converter.convert_to_mp4("https://youtube.com/watch?v=VIDEO_ID", quality="720p")
+
+# Get video info only
+info = converter.get_video_info("https://youtube.com/watch?v=VIDEO_ID")
+print(f"Title: {info['title']}")
+print(f"Duration: {info['duration']} seconds")
+```
+
+---
+
+## 🛠️ Integration Example (Django, subprocess)
+
+```python
+import subprocess
+import sys
+
+def convert_youtube_video(url: str, format: str = "mp3", quality: str = "best"):
+    cmd = [
+        sys.executable, "-m", "ytconvert.cli",
+        url,
+        "--format", format,
+        "--output", "/path/to/downloads",
+    ]
+    if format == "mp4" and quality != "best":
+        cmd.extend(["--quality", quality])
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    if result.returncode == 0:
+        return {"success": True, "output": result.stdout}
+    else:
+        return {"success": False, "exit_code": result.returncode, "error": result.stderr}
+```
+
+---
+
+## ⚠️ Exit Codes
+
+| Code | Meaning                       |
+|------|-------------------------------|
+| 0    | Success                       |
+| 1    | Invalid YouTube URL           |
+| 2    | Download failure              |
+| 3    | Format or quality unavailable |
+| 4    | Unexpected error              |
+
+---
+
+## 🏗️ Project Structure
+
+```
+ytconvert-cli/
+├── ytconvert/
+│   ├── __init__.py      # Package exports
+│   ├── cli.py           # CLI entry point
+│   ├── converter.py     # yt-dlp logic
+│   ├── validators.py    # URL/format validation
+│   ├── exceptions.py    # Custom exceptions
+│   └── utils.py         # Utilities
+├── pyproject.toml       # Packaging config
+├── README.md            # This file
+└── LICENSE              # MIT License
+```
+
+---
+
+## 📝 Development
+
+```bash
+# Run tests
+pytest
+
+# Format code
+black ytconvert/
+ruff check ytconvert/ --fix
+
+# Type check
+mypy ytconvert/
+```
+
+---
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE)
+
+---
+
+## 🙏 Acknowledgments
+
+- [yt-dlp](https://github.com/yt-dlp/yt-dlp) - Video downloader
+- [Typer](https://typer.tiangolo.com/) - CLI framework
+- [FFmpeg](https://ffmpeg.org/) - Media backend (bundled)
+
+---
+
+## 📢 Disclaimer
+
+This tool is intended for downloading videos you have the right to download. Please respect copyright laws and YouTube's Terms of Service. The authors are not responsible for misuse.

ytconvert_cli-1.0.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+ytconvert/__init__.py,sha256=eQWk1xhGIuarupBZTBHg2vT0S0PXOSttaMql4Xl5GNU,563
+ytconvert/cli.py,sha256=S6tQRHqrYmvtAd2-xFpGSTe7b0SPnyg4ksn2Svqhg9s,4547
+ytconvert/converter.py,sha256=Nqe8b3CWI0EFvdBzAoaNCc1s8IDDIGkAdJTJO6uPszc,13374
+ytconvert/exceptions.py,sha256=81ZNF8UybmgVZO4DgW4mi4HiQMnm5Nr90RBztOswvXk,1887
+ytconvert/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ytconvert/utils.py,sha256=1TnYOiEw60jSvmh2cmDdasOoF3mpzu5WRBgQDmHQU_o,4710
+ytconvert/validators.py,sha256=sHlYfIyWpZfaChVt5NQjU9DjfqDIUMBe6RNZ1urZytE,3711
+ytconvert_cli-1.0.0.dist-info/METADATA,sha256=bdg3VGY4QLvJCDbFRM-SMqZrTrEIdJ9v8VfgDRX_d1I,6379
+ytconvert_cli-1.0.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+ytconvert_cli-1.0.0.dist-info/entry_points.txt,sha256=Pu10ig5rBHQe_WWHd--nB1e4euLEvuDgCctBsLsh9MU,48
+ytconvert_cli-1.0.0.dist-info/licenses/LICENSE,sha256=_4kcUQSSk-8V8RdYzr4Qym1voMibl4y-cHP1XqeMeHQ,1104
+ytconvert_cli-1.0.0.dist-info/RECORD,,

ytconvert_cli-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

ytconvert_cli-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ytconvert = ytconvert.cli:cli

ytconvert_cli-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ytconvert-cli contributors
+
+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.