mmcli-dl 0.1.0b1__py3-none-any.whl

app/__init__.py

@@ -0,0 +1,3 @@
+from .tools.media_downloader import download
+from .utils.command_manager import command_manager
+from .utils.media_format import all_formats, audio_formats, video_formats

app/cli.py

@@ -0,0 +1,18 @@
+import asyncio
+from app import download, command_manager
+
+
+async def _async_main():
+    """Parse arguments and run the download."""
+    args = command_manager()
+    await download(args)
+
+
+def main():
+    """CLI entry point: run the async download pipeline."""
+    try:
+        asyncio.run(_async_main())
+    except KeyboardInterrupt:
+        print("\nOperation cancelled by user")
+    except Exception as e:
+        print(f"Error: {e}")

app/tools/media_converter.py

@@ -0,0 +1,233 @@
+import asyncio
+import ffmpeg
+import os
+import shutil
+import textwrap
+from pathlib import Path
+from datetime import datetime
+from typing import Optional, List, Dict, Any
+from functools import reduce
+from ..utils.media_format import all_formats
+
+
+def ensure_output_directory(output_dir: Optional[str]) -> Path:
+    """Create output directory if needed and return Path object."""
+    path = Path(output_dir) if output_dir else Path(os.getcwd()) / "convert"
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def generate_output_filename(input_file: Path, output_format: str) -> str:
+    """Generate unique output filename with timestamp."""
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S_%f")
+    return f"{input_file.stem}_{timestamp}.{output_format}"
+
+
+def create_output_path(input_file: Path, output_format: str, output_dir: Path) -> Path:
+    """Create full output file path."""
+    output_filename = generate_output_filename(input_file, output_format)
+    return output_dir / output_filename
+
+
+def find_ffmpeg_format(output_format: str) -> Optional[str]:
+    """Find matching ffmpeg format from format alias."""
+    format_matches = list(
+        filter(lambda fmt: fmt["alias"] == output_format, all_formats)
+    )
+    return format_matches[0]["format"] if format_matches else None
+
+
+def create_conversion_config(
+    input_file: Path, output_format: str, output_dir: Path
+) -> Dict[str, Any]:
+    """Create conversion configuration object."""
+    ffmpeg_format = find_ffmpeg_format(output_format)
+    output_path = create_output_path(input_file, output_format, output_dir)
+
+    return {
+        "input_file": input_file,
+        "output_path": output_path,
+        "ffmpeg_format": ffmpeg_format,
+        "output_format": output_format,
+    }
+
+
+async def execute_ffmpeg_conversion(config: Dict[str, Any]) -> bool:
+    """Execute ffmpeg conversion with given configuration asynchronously."""
+    if not config["ffmpeg_format"]:
+        print(f"Unsupported format: {config['output_format']}")
+        return False
+
+    def _convert():
+        try:
+            ffmpeg.input(str(config["input_file"])).output(
+                str(config["output_path"]), format=config["ffmpeg_format"]
+            ).run(quiet=True, overwrite_output=True)
+            return True
+        except Exception as e:
+            print(f"Error converting {config['input_file']}: {e}")
+            return False
+
+    loop = asyncio.get_event_loop()
+    return await loop.run_in_executor(None, _convert)
+
+
+async def convert_single_file_functional(
+    input_file: Path, output_format: str, output_dir: Path
+) -> Dict[str, Any]:
+    """Convert single file using functional approach with detailed result."""
+    config = create_conversion_config(input_file, output_format, output_dir)
+    success = await execute_ffmpeg_conversion(config)
+
+    return {
+        "input_file": str(input_file),
+        "output_file": str(config["output_path"]) if success else None,
+        "success": success,
+        "format": output_format,
+    }
+
+
+async def process_conversion_batch(
+    input_files: List[Path],
+    output_format: str,
+    output_dir: Path,
+    max_concurrent: int = 1,
+) -> List[Dict[str, Any]]:
+    """Process batch conversion using async concurrency control."""
+
+    async def convert_with_feedback(input_file: Path) -> Dict[str, Any]:
+        try:
+            result = await convert_single_file_functional(
+                input_file, output_format, output_dir
+            )
+            if result["success"]:
+                print(f"[OK] Converted {input_file.name}")
+            else:
+                print(f"[FAIL] Failed to convert {input_file.name}")
+            return result
+        except Exception as e:
+            print(f"[ERROR] Error converting {input_file.name}: {e}")
+            return {
+                "input_file": str(input_file),
+                "output_file": None,
+                "success": False,
+                "format": output_format,
+                "error": str(e),
+            }
+
+    if len(input_files) == 1 or max_concurrent <= 1:
+        # Sequential conversion for single files or when max_concurrent is 1
+        print(f"Converting {len(input_files)} file(s) to {output_format}...")
+        results = []
+        for input_file in input_files:
+            result = await convert_with_feedback(input_file)
+            results.append(result)
+        return results
+    else:
+        # Concurrent conversion for multiple files
+        print(
+            f"Converting {len(input_files)} file(s) to {output_format} using max {max_concurrent} concurrent conversions..."
+        )
+
+        # Use semaphore to limit concurrent conversions
+        semaphore = asyncio.Semaphore(max_concurrent)
+
+        async def convert_with_semaphore(input_file: Path):
+            async with semaphore:
+                return await convert_with_feedback(input_file)
+
+        tasks = [convert_with_semaphore(input_file) for input_file in input_files]
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+
+        # Handle exceptions in results
+        processed_results = []
+        for i, result in enumerate(results):
+            if isinstance(result, Exception):
+                processed_results.append(
+                    {
+                        "input_file": str(input_files[i]),
+                        "output_file": None,
+                        "success": False,
+                        "format": output_format,
+                        "error": str(result),
+                    }
+                )
+            else:
+                processed_results.append(result)
+
+        return processed_results
+
+
+def calculate_conversion_stats(results: List[Dict[str, Any]]) -> Dict[str, int]:
+    """Calculate conversion statistics from results."""
+    return reduce(
+        lambda acc, result: {
+            "total": acc["total"] + 1,
+            "success": acc["success"] + (1 if result["success"] else 0),
+            "failed": acc["failed"] + (0 if result["success"] else 1),
+        },
+        results,
+        {"total": 0, "success": 0, "failed": 0},
+    )
+
+
+def format_conversion_summary(
+    stats: Dict[str, int], output_format: str, output_dir: str
+) -> str:
+    """Format conversion summary message."""
+    return textwrap.dedent(f"""
+        Summary:
+        Successfully converted: {stats["success"]}
+        Failed to convert: {stats["failed"]}
+        Format: {output_format}
+        Output directory: {output_dir}
+    """).strip()
+
+
+def print_conversion_results(
+    results: List[Dict[str, Any]], output_format: str, output_dir: str
+) -> None:
+    """Print detailed conversion results and summary."""
+    stats = calculate_conversion_stats(results)
+
+    print("Conversion complete.")
+    print(format_conversion_summary(stats, output_format, output_dir))
+
+    if stats["failed"] > 0:
+        print("\nFailed conversions:")
+        failed_files = [r["input_file"] for r in results if not r["success"]]
+        for file_path in failed_files:
+            print(f"  - {file_path}")
+
+
+async def convert_files_functional(
+    input_files: List[Path],
+    output_format: str,
+    output_dir: Optional[str] = None,
+    max_workers: int = 1,
+) -> List[Dict[str, Any]]:
+    """Convert batch of files using async concurrency."""
+    if shutil.which("ffmpeg") is None:
+        print(
+            "FFmpeg not found on PATH. Install FFmpeg and try again: "
+            "https://ffmpeg.org/download.html"
+        )
+        return [
+            {
+                "input_file": str(input_file),
+                "output_file": None,
+                "success": False,
+                "format": output_format,
+                "error": "ffmpeg not found",
+            }
+            for input_file in input_files
+        ]
+
+    resolved_output_dir = ensure_output_directory(output_dir)
+
+    results = await process_conversion_batch(
+        input_files, output_format, resolved_output_dir, max_workers
+    )
+    print_conversion_results(results, output_format, str(resolved_output_dir))
+
+    return results

app/tools/media_downloader.py

@@ -0,0 +1,233 @@
+import os
+import sys
+from pathlib import Path
+from typing import Optional, Dict, Any, List
+from functools import reduce
+from ..utils.media_format import is_audio_format
+from ..utils.constants import PLAYLIST_MAX_CONCURRENT
+from . import media_converter
+from . import youtube_downloader
+
+
+def resolve_output_dir(args) -> str:
+    """Resolve the base output directory, defaulting to the current directory."""
+    target = getattr(args, "output_dir", None)
+    return os.path.abspath(target) if target else os.getcwd()
+
+
+def ensure_directory_exists(path: str) -> str:
+    """Create the directory if missing and return it."""
+    os.makedirs(path, exist_ok=True)
+    return path
+
+
+def normalize_resolution(resolution: Optional[str]) -> Optional[str]:
+    """Normalize '720' -> '720p' for pytubefix; pass through None and '720p'."""
+    if not resolution:
+        return None
+    return resolution if resolution.endswith("p") else f"{resolution}p"
+
+
+def extract_file_extension(filepath: str) -> str:
+    """Return the lowercased extension without the leading dot."""
+    return os.path.splitext(filepath)[1][1:].lower()
+
+
+def should_convert(current_ext: str, target_format: Optional[str]) -> bool:
+    """True when a non-empty target format differs from the current extension."""
+    if not target_format:
+        return False
+    return current_ext.lower() != target_format.lower()
+
+
+async def convert_downloaded_file(downloaded_file: str, target_format: str) -> str:
+    """Convert one downloaded file in place; remove the original on success."""
+    results = await media_converter.convert_files_functional(
+        [Path(downloaded_file)],
+        target_format,
+        output_dir=os.path.dirname(downloaded_file),
+    )
+    if results and results[0]["success"]:
+        try:
+            os.remove(downloaded_file)
+        except OSError:
+            pass
+        return results[0]["output_file"]
+    print(f"Failed to convert {downloaded_file}")
+    return downloaded_file
+
+
+def sanitize_subfolder(name: str) -> str:
+    """Reduce a playlist title to a safe single path segment."""
+    # Drop path separators and surrounding whitespace so a title can never
+    # escape base_dir or create nested folders; fall back to 'playlist' when
+    # nothing meaningful survives (empty, or only separators/dots).
+    cleaned = name.replace("/", "_").replace("\\", "_").strip().strip(".")
+    if not cleaned or set(cleaned) <= {"_"}:
+        return "playlist"
+    return cleaned
+
+
+def resolve_playlist_output(base_dir: str, url: str) -> str:
+    """Return <base_dir>/<playlist-title>/, falling back to 'playlist'."""
+    try:
+        playlist = youtube_downloader.create_playlist_instance(url)
+        title = playlist.title
+    except Exception:
+        title = "playlist"
+    return ensure_directory_exists(os.path.join(base_dir, sanitize_subfolder(title)))
+
+
+def _finalize_single(result: Dict[str, Any], converted_path: str) -> Dict[str, Any]:
+    """Build the user-facing result dict for a single download."""
+    return {
+        "success": True,
+        "title": result["metadata"]["title"],
+        "file_path": converted_path,
+        "format": extract_file_extension(converted_path),
+    }
+
+
+def _failed(result: Dict[str, Any]) -> Dict[str, Any]:
+    """Build a failure result dict from a download result."""
+    return {
+        "success": False,
+        "title": result["metadata"].get("title", "Unknown"),
+        "error": result["metadata"].get("error", "Download failed"),
+    }
+
+
+async def _download_single(
+    url: str, output_path: str, audio_only: bool, resolution, target_format
+) -> Dict[str, Any]:
+    if audio_only:
+        result = await youtube_downloader.download_single_audio(url, output_path)
+    else:
+        result = await youtube_downloader.download_single_video(
+            url, output_path, resolution
+        )
+
+    if not result["success"]:
+        return _failed(result)
+
+    file_path = result["file_path"]
+    if target_format and should_convert(
+        extract_file_extension(file_path), target_format
+    ):
+        file_path = await convert_downloaded_file(file_path, target_format)
+    return _finalize_single(result, file_path)
+
+
+async def _download_playlist(
+    url: str, output_path: str, audio_only: bool, resolution, target_format
+) -> List[Dict[str, Any]]:
+    if audio_only:
+        results = await youtube_downloader.download_playlist_audios(
+            url, output_path, max_concurrent=PLAYLIST_MAX_CONCURRENT
+        )
+    else:
+        results = await youtube_downloader.download_playlist_videos(
+            url, output_path, resolution, max_concurrent=PLAYLIST_MAX_CONCURRENT
+        )
+    return await _finalize_playlist(results, target_format)
+
+
+async def _finalize_playlist(
+    results: List[Dict[str, Any]], target_format: Optional[str]
+) -> List[Dict[str, Any]]:
+    downloaded = [r["file_path"] for r in results if r["success"] and r["file_path"]]
+    conversion_map: Dict[str, Dict[str, Any]] = {}
+
+    if target_format:
+        to_convert = [
+            f
+            for f in downloaded
+            if should_convert(extract_file_extension(f), target_format)
+        ]
+        if to_convert:
+            conv_results = await media_converter.convert_files_functional(
+                [Path(f) for f in to_convert],
+                target_format,
+                output_dir=os.path.dirname(to_convert[0]),
+                max_workers=PLAYLIST_MAX_CONCURRENT,
+            )
+            for i, cr in enumerate(conv_results):
+                if cr["success"]:
+                    try:
+                        os.remove(to_convert[i])
+                    except OSError:
+                        pass
+                # Key on the original download path, not cr["input_file"], so the
+                # lookup below matches regardless of Path round-trip normalization.
+                conversion_map[to_convert[i]] = cr
+
+    processed = []
+    for r in results:
+        if not r["success"]:
+            processed.append(_failed(r))
+            continue
+        file_path = r["file_path"]
+        cr = conversion_map.get(file_path)
+        final_path = cr["output_file"] if cr and cr["success"] else file_path
+        processed.append(_finalize_single(r, final_path))
+    return processed
+
+
+def calculate_success_stats(results: List[Dict[str, Any]]) -> Dict[str, int]:
+    """Tally total/success/failed across a list of result dicts."""
+    return reduce(
+        lambda acc, r: {
+            "total": acc["total"] + 1,
+            "success": acc["success"] + (1 if r["success"] else 0),
+            "failed": acc["failed"] + (0 if r["success"] else 1),
+        },
+        results,
+        {"total": 0, "success": 0, "failed": 0},
+    )
+
+
+def print_summary(results) -> None:
+    """Print a human-readable summary for single or playlist results."""
+    if isinstance(results, list):
+        stats = calculate_success_stats(results)
+        print("Download Summary:")
+        print(f"- Total items: {stats['total']}")
+        print(f"- Successfully downloaded: {stats['success']}")
+        print(f"- Failed: {stats['failed']}")
+    elif results.get("success"):
+        print(f"Done: {results.get('title', '')}")
+    else:
+        print(f"Failed: {results.get('error', 'Download failed')}")
+
+
+async def download(args):
+    """Download a YouTube URL (single or playlist), converting to --format if given."""
+    url = args.url
+    validation = youtube_downloader.validate_youtube_url(url)
+    if not validation["is_valid"]:
+        print(f"Error: Unsupported URL: {url}. Only YouTube URLs are supported.")
+        sys.exit(1)
+
+    target_format = getattr(args, "format", None)
+    audio_only = target_format is not None and is_audio_format(target_format)
+    resolution = normalize_resolution(getattr(args, "resolution", None))
+    base_dir = resolve_output_dir(args)
+
+    try:
+        if validation["is_playlist"]:
+            output_path = resolve_playlist_output(base_dir, url)
+            results = await _download_playlist(
+                url, output_path, audio_only, resolution, target_format
+            )
+        else:
+            output_path = ensure_directory_exists(base_dir)
+            results = await _download_single(
+                url, output_path, audio_only, resolution, target_format
+            )
+        print_summary(results)
+        return results
+    except SystemExit:
+        raise
+    except Exception as e:
+        print(f"Error: {e}")
+        sys.exit(1)

app/tools/youtube_downloader.py

@@ -0,0 +1,227 @@
+import asyncio
+from typing import Optional, Dict, Any, Callable, List
+from pytubefix import YouTube, Playlist
+from pytubefix.cli import on_progress
+
+
+def create_youtube_instance(
+    url: str, progress_callback: Callable = on_progress
+) -> YouTube:
+    """Create YouTube instance with progress callback."""
+    return YouTube(url, on_progress_callback=progress_callback)
+
+
+def create_playlist_instance(url: str) -> Playlist:
+    """Create YouTube playlist instance."""
+    return Playlist(url)
+
+
+def select_video_stream(yt: YouTube, resolution: Optional[str]):
+    """Select video stream based on resolution preference."""
+    if resolution is not None:
+        return yt.streams.get_by_resolution(resolution)
+    return yt.streams.get_highest_resolution()
+
+
+def select_audio_stream(yt: YouTube):
+    """Select best available audio stream."""
+    return yt.streams.get_audio_only()
+
+
+def download_stream(stream, output_path: str) -> Optional[str]:
+    """Download stream to specified output path."""
+    return stream.download(output_path=output_path)
+
+
+def get_video_metadata(yt: YouTube) -> Dict[str, Any]:
+    """Extract video metadata."""
+    return {
+        "title": yt.title,
+        "length": yt.length,
+        "views": yt.views,
+        "author": yt.author,
+    }
+
+
+def get_playlist_metadata(playlist: Playlist) -> Dict[str, Any]:
+    """Extract playlist metadata."""
+    return {
+        "title": playlist.title,
+        "video_count": len(list(playlist.videos)),
+        "owner": playlist.owner,
+    }
+
+
+async def download_single_video(
+    url: str,
+    output_path: str,
+    resolution: Optional[str] = None,
+    progress_callback: Callable = on_progress,
+) -> Dict[str, Any]:
+    """Download single YouTube video asynchronously."""
+    loop = asyncio.get_event_loop()
+
+    def _download():
+        yt = create_youtube_instance(url, progress_callback)
+        stream = select_video_stream(yt, resolution)
+        downloaded_file = download_stream(stream, output_path)
+        metadata = get_video_metadata(yt)
+        return {
+            "success": downloaded_file is not None,
+            "file_path": downloaded_file,
+            "metadata": metadata,
+        }
+
+    return await loop.run_in_executor(None, _download)
+
+
+async def download_single_audio(
+    url: str, output_path: str, progress_callback: Callable = on_progress
+) -> Dict[str, Any]:
+    """Download single YouTube audio asynchronously."""
+    loop = asyncio.get_event_loop()
+
+    def _download():
+        yt = create_youtube_instance(url, progress_callback)
+        stream = select_audio_stream(yt)
+        downloaded_file = download_stream(stream, output_path)
+        metadata = get_video_metadata(yt)
+        return {
+            "success": downloaded_file is not None,
+            "file_path": downloaded_file,
+            "metadata": metadata,
+        }
+
+    return await loop.run_in_executor(None, _download)
+
+
+async def download_playlist_videos(
+    url: str,
+    output_path: str,
+    resolution: Optional[str] = None,
+    progress_callback: Callable = on_progress,
+    max_concurrent: int = 3,
+) -> List[Dict[str, Any]]:
+    """Download all videos from YouTube playlist asynchronously."""
+    playlist = create_playlist_instance(url)
+    playlist_meta = get_playlist_metadata(playlist)
+
+    async def download_with_info(index: int, yt) -> Dict[str, Any]:
+        print(f"[{index + 1}/{playlist_meta['video_count']}] Downloading: {yt.title}")
+        try:
+            result = await download_single_video(
+                yt.watch_url, output_path, resolution, progress_callback
+            )
+            if result["success"]:
+                print(f"[OK] Successfully downloaded {yt.title}")
+            else:
+                print(f"[FAIL] Failed to download {yt.title}")
+            return result
+        except Exception as e:
+            print(f"[FAIL] Error downloading {yt.title}: {e}")
+            return {
+                "success": False,
+                "file_path": None,
+                "metadata": {"title": yt.title, "error": str(e)},
+            }
+
+    # Use semaphore to limit concurrent downloads
+    semaphore = asyncio.Semaphore(max_concurrent)
+
+    async def download_with_semaphore(index: int, yt):
+        async with semaphore:
+            return await download_with_info(index, yt)
+
+    tasks = [
+        download_with_semaphore(index, yt) for index, yt in enumerate(playlist.videos)
+    ]
+    results = await asyncio.gather(*tasks, return_exceptions=True)
+
+    # Handle exceptions in results
+    processed_results = []
+    for i, result in enumerate(results):
+        if isinstance(result, Exception):
+            processed_results.append(
+                {
+                    "success": False,
+                    "file_path": None,
+                    "metadata": {"title": f"video_{i}", "error": str(result)},
+                }
+            )
+        else:
+            processed_results.append(result)
+
+    return processed_results
+
+
+async def download_playlist_audios(
+    url: str,
+    output_path: str,
+    progress_callback: Callable = on_progress,
+    max_concurrent: int = 3,
+) -> List[Dict[str, Any]]:
+    """Download all audios from YouTube playlist asynchronously."""
+    playlist = create_playlist_instance(url)
+    playlist_meta = get_playlist_metadata(playlist)
+
+    async def download_with_info(index: int, yt) -> Dict[str, Any]:
+        print(f"[{index + 1}/{playlist_meta['video_count']}] Downloading: {yt.title}")
+        try:
+            result = await download_single_audio(
+                yt.watch_url, output_path, progress_callback
+            )
+            if result["success"]:
+                print(f"[OK] Successfully downloaded {yt.title}")
+            else:
+                print(f"[FAIL] Failed to download {yt.title}")
+            return result
+        except Exception as e:
+            print(f"[FAIL] Error downloading {yt.title}: {e}")
+            return {
+                "success": False,
+                "file_path": None,
+                "metadata": {"title": yt.title, "error": str(e)},
+            }
+
+    # Use semaphore to limit concurrent downloads
+    semaphore = asyncio.Semaphore(max_concurrent)
+
+    async def download_with_semaphore(index: int, yt):
+        async with semaphore:
+            return await download_with_info(index, yt)
+
+    tasks = [
+        download_with_semaphore(index, yt) for index, yt in enumerate(playlist.videos)
+    ]
+    results = await asyncio.gather(*tasks, return_exceptions=True)
+
+    # Handle exceptions in results
+    processed_results = []
+    for i, result in enumerate(results):
+        if isinstance(result, Exception):
+            processed_results.append(
+                {
+                    "success": False,
+                    "file_path": None,
+                    "metadata": {"title": f"audio_{i}", "error": str(result)},
+                }
+            )
+        else:
+            processed_results.append(result)
+
+    return processed_results
+
+
+def is_youtube_url(url: str) -> bool:
+    """Check if URL is a YouTube URL."""
+    return "youtube.com" in url or "youtu.be" in url
+
+
+def is_playlist_url(url: str) -> bool:
+    """Check if URL is a playlist URL."""
+    return "list=" in url
+
+
+def validate_youtube_url(url: str) -> Dict[str, bool]:
+    """Validate YouTube URL and determine type."""
+    return {"is_valid": is_youtube_url(url), "is_playlist": is_playlist_url(url)}

app/utils/command_manager.py

@@ -0,0 +1,51 @@
+import argparse
+from .media_format import all_formats, video_formats, audio_formats
+from .constants import APP_VERSION
+
+
+def command_manager():
+    epilog_text = """
+    Examples:
+        mmcli "https://youtube.com/watch?v=..."                      # best-quality video
+        mmcli "https://youtube.com/watch?v=..." --resolution 720     # video at 720p
+        mmcli "https://youtube.com/watch?v=..." --format mp3         # audio only, as mp3
+        mmcli "https://youtube.com/watch?v=..." --format mkv         # video as mkv
+        mmcli "https://youtube.com/playlist?list=..." --format mp3   # whole playlist as mp3
+        mmcli "<url>" --output-dir ~/Downloads                       # choose a directory
+    """
+    parser = argparse.ArgumentParser(
+        prog="mmcli",
+        description="YouTube downloader with format conversion",
+        epilog=epilog_text,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "--version", "-v", action="version", version=f"mmcli {APP_VERSION}"
+    )
+    parser.add_argument("url", help="YouTube video or playlist URL")
+    parser.add_argument(
+        "--resolution",
+        "-r",
+        help="Video resolution, e.g. 720 or 720p (ignored for audio formats)",
+    )
+    video_aliases = ", ".join(f["alias"] for f in video_formats)
+    audio_aliases = ", ".join(f["alias"] for f in audio_formats)
+    parser.add_argument(
+        "--format",
+        "-f",
+        choices=[f["alias"] for f in all_formats],
+        metavar="FORMAT",
+        help=(
+            "Output format. Audio formats download audio only "
+            f"({audio_aliases}); video formats convert the container "
+            f"({video_aliases})."
+        ),
+    )
+    parser.add_argument(
+        "--output-dir",
+        "-o",
+        dest="output_dir",
+        help="Output directory (default: current directory)",
+    )
+
+    return parser.parse_args()

app/utils/constants.py

@@ -0,0 +1,6 @@
+"""Hardcoded defaults for the few values dependencies don't provide."""
+
+APP_VERSION = "0.1.0b1"
+
+# pytubefix/ffmpeg provide quality defaults; only playlist fan-out needs a constant.
+PLAYLIST_MAX_CONCURRENT = 3

app/utils/media_format.py

@@ -0,0 +1,55 @@
+video_formats = [
+    {"alias": "mp4", "format": "mp4", "desc": "MPEG-4 Part 14"},
+    {"alias": "mkv", "format": "matroska", "desc": "Matroska Multimedia Container"},
+    {"alias": "avi", "format": "avi", "desc": "Audio Video Interleaved"},
+    {"alias": "mov", "format": "mov", "desc": "QuickTime Movie"},
+    {"alias": "flv", "format": "flv", "desc": "Flash Video"},
+    {"alias": "webm", "format": "webm", "desc": "WebM Video"},
+    {"alias": "mpeg", "format": "mpeg", "desc": "MPEG Program Stream"},
+    {"alias": "mpg", "format": "mpeg", "desc": "MPEG Program Stream"},
+    {"alias": "ts", "format": "mpegts", "desc": "MPEG Transport Stream"},
+    {"alias": "m2ts", "format": "mpegts", "desc": "MPEG-2 Transport Stream"},
+    {"alias": "ogv", "format": "ogg", "desc": "Ogg Video"},
+    {"alias": "3gp", "format": "3gp", "desc": "3GPP Multimedia Container"},
+    {"alias": "3g2", "format": "3g2", "desc": "3GPP2 Multimedia Container"},
+    {"alias": "vob", "format": "vob", "desc": "DVD Video Object"},
+    {"alias": "f4v", "format": "f4v", "desc": "Flash Video F4V"},
+    {"alias": "wmv", "format": "asf", "desc": "Windows Media Video"},
+    {"alias": "rm", "format": "rm", "desc": "RealMedia"},
+    {"alias": "rmvb", "format": "rm", "desc": "RealMedia Variable Bitrate"},
+]
+
+audio_formats = [
+    {"alias": "mp3", "format": "mp3", "desc": "MPEG Audio Layer III"},
+    {"alias": "wav", "format": "wav", "desc": "Waveform Audio File Format"},
+    {"alias": "flac", "format": "flac", "desc": "Free Lossless Audio Codec"},
+    {"alias": "aac", "format": "aac", "desc": "Advanced Audio Coding"},
+    {"alias": "m4a", "format": "ipod", "desc": "MPEG-4 Audio"},
+    {"alias": "ogg", "format": "ogg", "desc": "Ogg Vorbis/Opus"},
+    {"alias": "oga", "format": "ogg", "desc": "Ogg Audio"},
+    {"alias": "opus", "format": "ogg", "desc": "Opus in Ogg"},
+    {"alias": "wma", "format": "asf", "desc": "Windows Media Audio"},
+    {"alias": "alac", "format": "ipod", "desc": "Apple Lossless Audio Codec"},
+    {"alias": "amr", "format": "amr", "desc": "Adaptive Multi-Rate Audio"},
+    {"alias": "ac3", "format": "ac3", "desc": "Dolby Digital AC-3"},
+    {"alias": "dts", "format": "dts", "desc": "Digital Theater Systems"},
+    {"alias": "eac3", "format": "eac3", "desc": "Enhanced AC-3"},
+]
+
+all_formats = video_formats + audio_formats
+
+
+def get_format(format: str, formats: list = all_formats) -> list:
+    return list(
+        filter(lambda f: f["alias"] == format or f["format"] == format, formats)
+    )
+
+
+def is_audio_format(alias: str) -> bool:
+    """True when alias names an audio output format."""
+    return any(f["alias"] == alias for f in audio_formats)
+
+
+def is_video_format(alias: str) -> bool:
+    """True when alias names a video output format."""
+    return any(f["alias"] == alias for f in video_formats)

mmcli_dl-0.1.0b1.dist-info/METADATA

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: mmcli-dl
+Version: 0.1.0b1
+Summary: A command-line YouTube downloader with built-in audio/video format conversion
+Author: rizkirakasiwi
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/rizukirr/mmcli
+Project-URL: Repository, https://github.com/rizukirr/mmcli
+Project-URL: Issues, https://github.com/rizukirr/mmcli/issues
+Keywords: youtube,downloader,cli,ffmpeg,video,audio,playlist
+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.12
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ffmpeg-python>=0.2.0
+Requires-Dist: pytubefix>=10.10.1
+Provides-Extra: test
+Requires-Dist: pytest>=9.0; extra == "test"
+Requires-Dist: pytest-cov>=7.0; extra == "test"
+Requires-Dist: pytest-asyncio>=1.0; extra == "test"
+Dynamic: license-file
+
+# mmcli
+
+mmcli is a command-line YouTube downloader with built-in format conversion. Give
+it a video or playlist URL and it downloads the media, optionally converting it
+to the audio or video format you choose. Playlists are detected automatically and
+saved into a per-playlist folder. Requires Python 3.12+ and FFmpeg on your `PATH`.
+
+## Install
+
+```
+pip install mmcli-dl      # or: pipx install mmcli-dl / uv tool install mmcli-dl
+```
+
+The installed command is `mmcli`. FFmpeg must be on your `PATH` for format conversion.
+
+## Command
+
+```
+mmcli <url> [--resolution RES] [--format FMT] [--output-dir DIR]
+```
+
+| Argument | Short | Description |
+|----------|-------|-------------|
+| `url` | | YouTube video or playlist URL (required). |
+| `--resolution` | `-r` | Video resolution, e.g. `720` or `720p`. Ignored for audio formats. Default: highest available. |
+| `--format` | `-f` | Output format. An audio format (`mp3`, `m4a`, `wav`, ...) downloads audio only; a video format (`mp4`, `mkv`, `webm`, ...) converts the container. Default: keep the downloaded video as-is. |
+| `--output-dir` | `-o` | Directory to save into. Default: current directory. |
+| `--version` | `-v` | Print the version and exit. |
+
+Examples:
+
+```
+mmcli "https://youtube.com/watch?v=..."                       # best-quality video
+mmcli "https://youtube.com/watch?v=..." --resolution 720      # video at 720p
+mmcli "https://youtube.com/watch?v=..." --format mp3          # audio only, as mp3
+mmcli "https://youtube.com/watch?v=..." --format mkv          # video, converted to mkv
+mmcli "https://youtube.com/playlist?list=..." --format mp3    # whole playlist as mp3
+mmcli "https://youtube.com/watch?v=..." --output-dir ~/Videos # choose the output directory
+```
+
+## Supported `--format` values
+
+An **audio** format downloads audio only; a **video** format downloads video and
+converts the container.
+
+- **Audio:** `mp3`, `wav`, `flac`, `aac`, `m4a`, `ogg`, `oga`, `opus`, `wma`, `alac`, `amr`, `ac3`, `dts`, `eac3`
+- **Video:** `mp4`, `mkv`, `avi`, `mov`, `flv`, `webm`, `mpeg`, `mpg`, `ts`, `m2ts`, `ogv`, `3gp`, `3g2`, `vob`, `f4v`, `wmv`, `rm`, `rmvb`

mmcli_dl-0.1.0b1.dist-info/RECORD

@@ -0,0 +1,16 @@
+app/__init__.py,sha256=bgjtefMCsDatNGIlFOcXbqNtob2dzu7rxRj04KwOBwI,170
+app/cli.py,sha256=knopJsZhJTYUVHKgWvBMSKP_VrIcZO3PytLbagm66R0,437
+app/tools/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+app/tools/media_converter.py,sha256=wHJFp4DgwvBkqMjum0PoykDtUQyhnfgs4HVgeeT11IM,8029
+app/tools/media_downloader.py,sha256=tiGaJPnaBQn50z31NzQARQQFCcjgiGvsmyZvgdjlPnE,8434
+app/tools/youtube_downloader.py,sha256=eXpO3xajfm3aQNi1rg8OzcNDh1__Y8t3h3aOlIVCcCo,7386
+app/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+app/utils/command_manager.py,sha256=ZiDJyCrkhImvE_x2poIeHmAbDZzhDxXUjT3l0ZAuRDU,1922
+app/utils/constants.py,sha256=PK7NnAOMl59SfF42pIoPORBtz-u425YjhXHlyCvbnk4,211
+app/utils/media_format.py,sha256=mZ6V2VNJVohPfj_purw9Jm5yXHdlNDNVJJ7F38UgRPQ,2819
+mmcli_dl-0.1.0b1.dist-info/licenses/LICENSE,sha256=U_xp6fNHr77KKxgMyEBpilbr3Pfj3pRFV85cBNy6fGY,1071
+mmcli_dl-0.1.0b1.dist-info/METADATA,sha256=FUO5SisMiWlHA2_tOVBajCayzjvREZ6NTmHM8R72c8s,3294
+mmcli_dl-0.1.0b1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+mmcli_dl-0.1.0b1.dist-info/entry_points.txt,sha256=xbJcgmZwoyNa8h6mIHc6At5UhNv7feW8tJgYybhz1cg,39
+mmcli_dl-0.1.0b1.dist-info/top_level.txt,sha256=io9g7LCbfmTG1SFKgEOGXmCFB9uMP2H5lerm0HiHWQE,4
+mmcli_dl-0.1.0b1.dist-info/RECORD,,

mmcli_dl-0.1.0b1.dist-info/WHEEL

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

mmcli_dl-0.1.0b1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mmcli = app.cli:main

mmcli_dl-0.1.0b1.dist-info/licenses/LICENSE

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

mmcli_dl-0.1.0b1.dist-info/top_level.txt

@@ -0,0 +1 @@
+app