mmcli-dl 0.1.0__tar.gz

mmcli_dl-0.1.0/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.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: mmcli-dl
+Version: 0.1.0
+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.0/README.md

@@ -0,0 +1,47 @@
+# 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.0/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

mmcli_dl-0.1.0/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}")

mmcli_dl-0.1.0/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

mmcli_dl-0.1.0/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)