mdl-cli 0.3.0__py3-none-any.whl

mdl/__init__.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("mdl-cli")
+except PackageNotFoundError:
+    __version__ = "0.0.0"

mdl/app.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import argparse
+from typing import Callable, Dict
+
+from mdl.commands.audio import handle_audio
+from mdl.commands.video import handle_video
+from mdl.commands.info import handle_info
+from mdl.commands.smoke import handle_smoke
+from mdl.commands.settings import SETTINGS_COMMANDS, handle_settings
+from mdl.core.options import Options
+from mdl.core.resolve import resolve_run_options
+
+
+# Handlers that require RunOptions
+_RUN_HANDLERS: Dict[str, Callable] = {
+    "info": handle_info,
+    "smoke": handle_smoke,
+    "audio": handle_audio,
+    "video": handle_video,
+}
+
+# Settings commands are handled without runtime resolution.
+_SETTINGS = set(SETTINGS_COMMANDS)
+
+
+def run_app(args: argparse.Namespace) -> int:
+    """
+    Application entrypoint (routing/orchestration).
+
+    Responsibilities:
+    - Convert argparse Namespace -> Options DTO
+    - Handle settings commands (no yt-dlp execution)
+    - Resolve RunOptions (config + defaults)
+    - Dispatch to the correct command handler
+    """
+    opts = Options.from_namespace(args)
+
+    # Settings commands: no runtime resolution needed
+    if opts.command in _SETTINGS:
+        return handle_settings(opts)
+
+    # Resolve runtime options (config + defaults) for commands that invoke yt-dlp
+    run_opts = resolve_run_options(opts)
+
+    handler = _RUN_HANDLERS.get(opts.command)
+    if handler is None:
+        raise SystemExit(f"[mdl] ERROR: Unknown command '{opts.command}'.")
+
+    return handler(opts, run_opts)

mdl/builders/yt_dlp_audio.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from typing import List
+
+from mdl.builders.yt_dlp_common import base_yt_dlp_args
+from mdl.core.config import Defaults
+from mdl.core.options import RunOptions
+from mdl.core.playlist import detect_playlist_layout, is_playlist_url
+
+
+def build_audio_command(url: str, opts: RunOptions) -> List[str]:
+    """Build the yt-dlp command for best-quality audio downloads."""
+    is_playlist = is_playlist_url(url)
+    if is_playlist:
+        mode = str(getattr(opts, "playlist_mode", "auto")).strip().lower()
+        if mode == "album":
+            layout = "album"
+        elif mode == "flat":
+            layout = "flat"
+        else:
+            layout = detect_playlist_layout(url)
+        tpl = Defaults.audio_playlist_tpl if layout == "album" else Defaults.audio_playlist_flat_tpl
+    else:
+        tpl = Defaults.audio_single_tpl
+    out_template = str(opts.out_dir / tpl)
+
+    cmd: List[str] = ["yt-dlp"]
+    cmd += base_yt_dlp_args(opts)
+
+    cmd += ["-f", "bestaudio/best"]
+    cmd += ["-x", "--audio-format", opts.audio_format]
+
+    # Metadata (no quality impact)
+    cmd += ["--add-metadata", "--embed-metadata"]
+
+    if is_playlist:
+        # Normalize autogenerated labels like "Album - <name>" to "<name>".
+        cmd += ["--replace-in-metadata", "playlist_title", r"^Album -\s*", ""]
+
+    # Cover behavior (best-effort; actual fallback strategy is handled later)
+    if opts.cover:
+        cmd += ["--embed-thumbnail"]
+
+    # Robustness
+    cmd += ["--ignore-errors", "--continue", "--no-overwrites"]
+
+    cmd += ["-o", out_template, url]
+    return cmd

mdl/builders/yt_dlp_common.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from typing import List
+
+from mdl.core.options import RunOptions
+
+
+def base_yt_dlp_args(opts: RunOptions) -> List[str]:
+    """Flags shared across all yt-dlp invocations."""
+    args: List[str] = []
+
+    if opts.cookies_from:
+        args += ["--cookies-from-browser", opts.cookies_from]
+
+    # Preset-derived throttling (only set in safe preset)
+    if opts.limit_rate:
+        args += ["--limit-rate", opts.limit_rate]
+
+    if opts.sleep_min is not None and opts.sleep_max is not None:
+        args += [
+            "--sleep-interval",
+            str(opts.sleep_min),
+            "--max-sleep-interval",
+            str(opts.sleep_max),
+        ]
+
+    return args

mdl/builders/yt_dlp_info.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from typing import List
+
+from mdl.builders.yt_dlp_common import base_yt_dlp_args
+from mdl.core.options import RunOptions
+
+
+def build_info_command(url: str, opts: RunOptions) -> List[str]:
+    """
+    Build the yt-dlp command to display available formats for a URL.
+
+    Equivalent to: yt-dlp -F URL
+    """
+    cmd: List[str] = ["yt-dlp"]
+    cmd += base_yt_dlp_args(opts)
+    cmd += ["-F", url]
+    return cmd

mdl/builders/yt_dlp_video.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from typing import List
+
+from mdl.builders.yt_dlp_common import base_yt_dlp_args
+from mdl.core.config import Defaults
+from mdl.core.options import RunOptions
+from mdl.core.playlist import is_playlist_url
+
+
+def build_video_command(url: str, opts: RunOptions) -> List[str]:
+    """
+    Build the yt-dlp command for best-quality video.
+
+    Strategy:
+    - Always pick best video + best audio (no forced downgrade).
+    - Remux to the configured container (mp4/mkv) without re-encoding.
+    """
+    is_playlist = is_playlist_url(url)
+    tpl = Defaults.video_playlist_flat_tpl if is_playlist else Defaults.video_single_tpl
+    out_template = str(opts.out_dir / tpl)
+
+    cmd: List[str] = ["yt-dlp"]
+    cmd += base_yt_dlp_args(opts)
+
+    # Best quality selection (avoid forcing container here)
+    cmd += ["-f", "bv*+ba/b"]
+
+    # Remux to the user-chosen container (safe subset: mp4|mkv)
+    cmd += ["--remux-video", opts.video_format]
+
+    if is_playlist:
+        # Normalize autogenerated labels like "Album - <name>" to "<name>".
+        cmd += ["--replace-in-metadata", "playlist_title", r"^Album -\s*", ""]
+
+    # Cover behavior (optional)
+    if opts.cover:
+        cmd += ["--write-thumbnail", "--embed-thumbnail"]
+
+    # Robustness
+    cmd += ["--ignore-errors", "--continue", "--no-overwrites"]
+
+    cmd += ["-o", out_template, url]
+    return cmd

mdl/cli.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Optional, List
+
+from mdl import __version__
+from mdl.app import run_app
+
+
+def _add_download_flags(p: argparse.ArgumentParser) -> None:
+    """
+    Flags for download commands (audio/video).
+    Intentionally minimal: users should not tune rate/sleep/etc.
+    Presets handle that internally.
+    """
+    p.add_argument("url", metavar="URL", help="Target URL (single item or playlist).")
+
+
+def _add_setting_value_arg(p: argparse.ArgumentParser, *, name: str, metavar: str = "VALUE") -> None:
+    """
+    Adds an optional positional VALUE for setting commands:
+    - `mdl <setting>` shows the current value.
+    - `mdl <setting> <VALUE>` sets a new value.
+    """
+    p.add_argument(name, nargs="?", default=None, metavar=metavar)
+
+
+def _add_print_flag(p: argparse.ArgumentParser) -> None:
+    """
+    Per-command print flag.
+    This makes `--print` valid AFTER the subcommand:
+      mdl audio URL --print
+    """
+    p.add_argument(
+        "--print",
+        action="store_true",
+        help="Print the final yt-dlp command and exit (no execution).",
+    )
+
+
+def _add_playlist_mode_flag(p: argparse.ArgumentParser) -> None:
+    """
+    Audio playlist folder layout strategy:
+    - auto: detect album-like playlists (OLAK...) and use album layout.
+    - album: force artist/channel + playlist folder layout.
+    - flat: force single playlist folder for all entries.
+    """
+    p.add_argument(
+        "--mode",
+        dest="playlist_mode",
+        choices=("auto", "album", "flat"),
+        default="auto",
+        help="Playlist folder layout strategy (default: auto).",
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """
+    CLI definition only. All business logic lives in mdl.app / core / commands.
+    """
+    parser = argparse.ArgumentParser(
+        prog="mdl",
+        description="mdl-cli: a human-friendly wrapper around yt-dlp.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        allow_abbrev=False,
+        epilog=(
+            "Examples:\n"
+            "  mdl audio URL --print\n"
+            "  mdl video URL --print\n"
+            "  mdl audio URL --mode flat\n"
+            "  mdl info URL\n"
+            "  mdl smoke audio\n"
+            "  mdl smoke video\n"
+            "  mdl config\n"
+            "  mdl out\n"
+            "  mdl out ./downloads\n"
+            "\n"
+            "Settings:\n"
+            "  mdl config\n"
+            "  mdl out\n"
+            "  mdl out ./downloads\n"
+            "  mdl preset\n"
+            "  mdl preset fast\n"
+            "  mdl preset --list\n"
+            "  mdl cookies brave\n"
+            "  mdl cover on\n"
+            "  mdl audio-format opus\n"
+            "  mdl video-format mkv\n"
+            "\n"
+            "Tip:\n"
+            "  During audio/video/smoke downloads, press Ctrl+C to cancel.\n"
+        ),
+    )
+
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"mdl {__version__}",
+        help="Show program version and exit.",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # Downloads
+    p_audio = subparsers.add_parser("audio", help="Download best-quality audio.")
+    _add_download_flags(p_audio)
+    _add_playlist_mode_flag(p_audio)
+    _add_print_flag(p_audio)
+
+    p_video = subparsers.add_parser("video", help="Download best-quality video.")
+    _add_download_flags(p_video)
+    _add_print_flag(p_video)
+
+    # Info
+    p_info = subparsers.add_parser("info", help="Show available formats for a URL (yt-dlp -F).")
+    p_info.add_argument("url", metavar="URL", help="Target URL to inspect (no download).")
+
+    # Smoke
+    p_smoke = subparsers.add_parser("smoke", help="Download a small sample to verify setup.")
+    smoke_sub = p_smoke.add_subparsers(dest="smoke_kind", required=True)
+
+    p_smoke_audio = smoke_sub.add_parser("audio", help="Smoke test: audio download.")
+    _add_print_flag(p_smoke_audio)
+
+    p_smoke_video = smoke_sub.add_parser("video", help="Smoke test: video download.")
+    _add_print_flag(p_smoke_video)
+
+    # Persistent settings (show on no arg, set on value, list on --list)
+    p_cover = subparsers.add_parser("cover", help="Configure cover behavior (thumbnail).")
+    p_cover.add_argument("--list", action="store_true", help="List allowed values.")
+    _add_setting_value_arg(p_cover, name="value", metavar="on|off")
+
+    p_cookies = subparsers.add_parser("cookies", help="Configure cookies browser (or disable).")
+    p_cookies.add_argument("--list", action="store_true", help="List allowed values.")
+    _add_setting_value_arg(p_cookies, name="value", metavar="BROWSER|none")
+
+    p_preset = subparsers.add_parser("preset", help="Configure the default preset (safe/fast).")
+    p_preset.add_argument("--list", action="store_true", help="List allowed values.")
+    _add_setting_value_arg(p_preset, name="value", metavar="safe|fast")
+
+    p_audio_fmt = subparsers.add_parser("audio-format", help="Configure default audio container.")
+    p_audio_fmt.add_argument("--list", action="store_true", help="List allowed values.")
+    _add_setting_value_arg(p_audio_fmt, name="value", metavar="opus|m4a|mp3|flac")
+
+    p_video_fmt = subparsers.add_parser("video-format", help="Configure default video container (remux).")
+    p_video_fmt.add_argument("--list", action="store_true", help="List allowed values.")
+    _add_setting_value_arg(p_video_fmt, name="value", metavar="mp4|mkv")
+
+    p_out = subparsers.add_parser("out", help="Configure default output base directory.")
+    _add_setting_value_arg(p_out, name="value", metavar="PATH")
+
+    subparsers.add_parser("config", help="Show the persistent config values.")
+
+    return parser
+
+
+def main(argv: Optional[List[str]] = None) -> None:
+    parser = build_parser()
+
+    # UX: if user runs just `mdl`, show help instead of an error.
+    if argv is None:
+        argv = sys.argv[1:]
+    if not argv:
+        parser.print_help()
+        raise SystemExit(0)
+
+    args = parser.parse_args(argv)
+    raise SystemExit(run_app(args))

mdl/commands/__init__.py

@@ -0,0 +1,13 @@
+from mdl.commands.audio import handle_audio
+from mdl.commands.video import handle_video
+from mdl.commands.info import handle_info
+from mdl.commands.smoke import handle_smoke
+from mdl.commands.settings import handle_settings
+
+__all__ = [
+    "handle_audio",
+    "handle_video",
+    "handle_info",
+    "handle_smoke",
+    "handle_settings",
+]

mdl/commands/audio.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+from mdl.core.options import Options, RunOptions
+from mdl.services.download_service import run_audio_download
+
+
+def handle_audio(opts: Options, run_opts: RunOptions) -> int:
+    return run_audio_download(opts, run_opts)

mdl/commands/info.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+from mdl.core.options import Options, RunOptions
+from mdl.services.download_service import run_info
+
+
+def handle_info(opts: Options, run_opts: RunOptions) -> int:
+    return run_info(opts, run_opts)

mdl/commands/settings.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import json
+import sys
+from dataclasses import asdict
+
+from mdl.core.config_store import (
+    describe_config_value,
+    list_allowed_values,
+    load_config,
+    save_config,
+    set_config_value,
+    SETTINGS_COMMANDS,
+)
+from mdl.core.options import Options
+
+
+def _handle_setting(cmd: str, value: str | None, list_flag: bool) -> int:
+    """
+    Settings UX:
+    - `mdl config`: show effective persistent config as JSON
+    - `mdl <cmd>`: show current value
+    - `mdl <cmd> <value>`: set value, persist, print confirmation
+    - `mdl <cmd> --list`: list allowed values
+    """
+    if cmd not in SETTINGS_COMMANDS:
+        raise SystemExit(f"[mdl] ERROR: unknown settings command '{cmd}'.")
+
+    if cmd == "config":
+        cfg = load_config()
+        print(json.dumps(asdict(cfg), indent=2, sort_keys=True))
+        return 0
+
+    if list_flag and cmd != "out":
+        values = list_allowed_values(cmd)
+        print(f"[mdl] {cmd} allowed: {', '.join(values)}")
+        return 0
+
+    cfg = load_config()
+
+    if value is None:
+        current = describe_config_value(cfg, cmd)
+        print(f"[mdl] {cmd}: {current}")
+        return 0
+
+    if cmd == "out" and not str(value).strip():
+        raise SystemExit("[mdl] ERROR: out requires a PATH")
+
+    cfg2 = set_config_value(cfg, cmd, value)
+    save_config(cfg2)
+    current = describe_config_value(cfg2, cmd)
+    print(f"[mdl] {cmd}: {current}")
+    return 0
+
+
+def handle_settings(opts: Options) -> int:
+    # `--print` makes sense for yt-dlp commands; settings don't execute anything.
+    if opts.print_cmd:
+        print("[mdl] NOTE: --print is ignored for settings commands.", file=sys.stderr)
+    return _handle_setting(opts.command, opts.value, opts.list_values)

mdl/commands/smoke.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+from mdl.core.options import Options, RunOptions
+from mdl.services.download_service import run_smoke
+
+
+def handle_smoke(opts: Options, run_opts: RunOptions) -> int:
+    return run_smoke(opts, run_opts)

mdl/commands/video.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+from mdl.core.options import Options, RunOptions
+from mdl.services.download_service import run_video_download
+
+
+def handle_video(opts: Options, run_opts: RunOptions) -> int:
+    return run_video_download(opts, run_opts)

mdl/core/__init__.py

@@ -0,0 +1,11 @@
+from mdl.core.options import Options, AppConfig, RunOptions
+from mdl.core.config import Defaults
+from mdl.core.resolve import resolve_run_options
+
+__all__ = [
+    "Options",
+    "AppConfig",
+    "RunOptions",
+    "Defaults",
+    "resolve_run_options",
+]

mdl/core/config.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+import os
+import re
+import sys
+
+
+def _expand_path(raw: str) -> Path:
+    return Path(os.path.expandvars(raw)).expanduser()
+
+
+def _xdg_music_dir() -> Path:
+    """
+    Best-effort: read XDG user dirs to find the real Music folder.
+    Falls back to ~/Music.
+    """
+    cfg = Path.home() / ".config" / "user-dirs.dirs"
+    if cfg.exists():
+        txt = cfg.read_text(encoding="utf-8", errors="ignore")
+
+        # Typical line: XDG_MUSIC_DIR="$HOME/Music"
+        m = re.search(r'^XDG_MUSIC_DIR=(?P<q>["\'])(?P<val>.*?)(?P=q)\s*$', txt, re.MULTILINE)
+        if m:
+            val = m.group("val").strip()
+
+            # Support $HOME and ${HOME}
+            home = str(Path.home())
+            val = val.replace("$HOME", home).replace("${HOME}", home)
+
+            # Expand any remaining env vars and user markers.
+            return _expand_path(val)
+
+    return Path.home() / "Music"
+
+
+def default_music_dir() -> Path:
+    """
+    Return the best default Music directory for the current platform.
+    Linux prefers XDG user-dirs; other platforms default to ~/Music.
+    """
+    if sys.platform.startswith("linux"):
+        return _xdg_music_dir()
+    return Path.home() / "Music"
+
+
+def default_config_dir(app_name: str = "mdl") -> Path:
+    """
+    Return an OS-appropriate config directory.
+    - Linux/Unix: $XDG_CONFIG_HOME/<app> or ~/.config/<app>
+    - macOS/iOS: ~/Library/Application Support/<app>
+    - Windows: %APPDATA%\\<app> (fallback to %LOCALAPPDATA%\\<app>)
+    """
+    if sys.platform == "win32":
+        base = os.environ.get("APPDATA") or os.environ.get("LOCALAPPDATA")
+        if base:
+            return _expand_path(base) / app_name
+        return Path.home() / "AppData" / "Roaming" / app_name
+
+    if sys.platform == "darwin" or sys.platform.startswith("ios"):
+        return Path.home() / "Library" / "Application Support" / app_name
+
+    xdg_base = os.environ.get("XDG_CONFIG_HOME")
+    if xdg_base:
+        return _expand_path(xdg_base) / app_name
+    return Path.home() / ".config" / app_name
+
+
+@dataclass(frozen=True)
+class Defaults:
+    # Output
+    out_dir: Path = default_music_dir() / "mdl"
+
+    # Networking behavior (safe preset)
+    limit_rate: str = "1M"
+    sleep_min: int = 5
+    sleep_max: int = 15
+
+    # Output templates
+    # Album layout: keep grouping by artist -> album/playlist title.
+    audio_single_tpl: str = "%(artists.0|artist|uploader)s/%(title)s.%(ext)s"
+    audio_playlist_tpl: str = "%(artists.0|artist|uploader)s/%(playlist_title|playlist)s/%(playlist_index)02d - %(title)s.%(ext)s"
+    video_playlist_tpl: str = "%(uploader|channel)s/%(playlist_title|playlist)s/%(playlist_index)02d - %(title)s.%(ext)s"
+
+    # Flat layout: keep all playlist entries under a single playlist folder.
+    audio_playlist_flat_tpl: str = "%(playlist_title|playlist)s/%(playlist_index)02d - %(title)s.%(ext)s"
+    video_playlist_flat_tpl: str = "%(playlist_title|playlist)s/%(playlist_index)02d - %(title)s.%(ext)s"
+
+    video_single_tpl: str = "%(uploader|channel)s/%(title)s.%(ext)s"

mdl/core/config_store.py

@@ -0,0 +1,175 @@
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import asdict, replace
+from pathlib import Path
+
+from mdl.core.config import Defaults, default_config_dir
+from mdl.core.options import AppConfig
+
+# Overrideable for tests and advanced users.
+_ENV_CONFIG_DIR = "MDL_CONFIG_DIR"
+
+SETTINGS_COMMANDS = {"config", "cover", "cookies", "preset", "audio-format", "video-format", "out"}
+
+ALLOWED = {
+    "cover": ["on", "off"],
+    "cookies": ["none", "brave", "chrome", "chromium", "firefox", "edge"],
+    "preset": ["safe", "fast"],
+    "audio-format": ["flac", "mp3", "opus", "m4a"],
+    "video-format": ["mp4", "mkv"],
+}
+
+
+def default_config() -> AppConfig:
+    # Default audio format: m4a (YouTube typically provides AAC in m4a or Opus in webm;
+    # "flac" outputs are transcodes, not true source FLAC).
+    return AppConfig(
+        preset="safe",
+        cookies="none",
+        cover=False,
+        audio_format="m4a",
+        video_format="mp4",
+        out_dir=_default_out_dir(),
+    )
+
+
+def _config_dir() -> Path:
+    raw = os.environ.get(_ENV_CONFIG_DIR)
+    if raw:
+        return _expand_path(raw)
+    return default_config_dir("mdl")
+
+
+def _config_file() -> Path:
+    return _config_dir() / "config.json"
+
+
+def load_config() -> AppConfig:
+    cfg_file = _config_file()
+    if not cfg_file.exists():
+        return default_config()
+
+    try:
+        data = json.loads(cfg_file.read_text(encoding="utf-8"))
+    except Exception:
+        return default_config()
+
+    cfg = default_config()
+
+    preset = _norm_str(data.get("preset", cfg.preset))
+    cookies = _norm_str(data.get("cookies", cfg.cookies))
+    cover = bool(data.get("cover", cfg.cover))
+    audio_format = _norm_str(data.get("audio_format", cfg.audio_format))
+    video_format = _norm_str(data.get("video_format", cfg.video_format))
+    out_dir = _normalize_out_dir(data.get("out_dir", cfg.out_dir), cfg.out_dir)
+
+    preset = preset if preset in ALLOWED["preset"] else cfg.preset
+    cookies = cookies if cookies in ALLOWED["cookies"] else cfg.cookies
+    audio_format = audio_format if audio_format in ALLOWED["audio-format"] else cfg.audio_format
+    video_format = video_format if video_format in ALLOWED["video-format"] else cfg.video_format
+
+    return AppConfig(
+        preset=preset,
+        cookies=cookies,
+        cover=cover,
+        audio_format=audio_format,
+        video_format=video_format,
+        out_dir=out_dir,
+    )
+
+
+def save_config(cfg: AppConfig) -> None:
+    cfg_dir = _config_dir()
+    cfg_dir.mkdir(parents=True, exist_ok=True)
+    payload = asdict(cfg)
+    _config_file().write_text(json.dumps(payload, indent=2, sort_keys=True), encoding="utf-8")
+
+
+def list_allowed_values(setting: str) -> list[str]:
+    setting = _norm_str(setting)
+    if setting not in ALLOWED:
+        raise SystemExit(f"[mdl] ERROR: unknown setting '{setting}'.")
+    return list(ALLOWED[setting])
+
+
+def describe_config_value(cfg: AppConfig, setting: str) -> str:
+    setting = _norm_str(setting)
+    if setting == "cover":
+        return "on" if cfg.cover else "off"
+    if setting == "cookies":
+        return cfg.cookies
+    if setting == "preset":
+        return cfg.preset
+    if setting == "audio-format":
+        return cfg.audio_format
+    if setting == "video-format":
+        return cfg.video_format
+    if setting == "out":
+        return cfg.out_dir
+    raise SystemExit(f"[mdl] ERROR: unknown setting '{setting}'.")
+
+
+def set_config_value(cfg: AppConfig, setting: str, value: str) -> AppConfig:
+    setting = _norm_str(setting)
+
+    if setting == "out":
+        value_s = str(value).strip()
+        if not value_s:
+            raise SystemExit("[mdl] ERROR: out requires a PATH")
+        out_dir = _normalize_out_dir(value_s, "")
+        if not out_dir:
+            raise SystemExit("[mdl] ERROR: out requires a PATH")
+        return replace(cfg, out_dir=out_dir)
+
+    value_n = _norm_str(value)
+
+    if setting not in ALLOWED:
+        raise SystemExit(f"[mdl] ERROR: unknown setting '{setting}'.")
+
+    if value_n not in ALLOWED[setting]:
+        allowed = ", ".join(ALLOWED[setting])
+        raise SystemExit(f"[mdl] ERROR: invalid value '{value}'. Allowed: {allowed}")
+
+    if setting == "cover":
+        return replace(cfg, cover=(value_n == "on"))
+    if setting == "cookies":
+        return replace(cfg, cookies=value_n)
+    if setting == "preset":
+        return replace(cfg, preset=value_n)
+    if setting == "audio-format":
+        return replace(cfg, audio_format=value_n)
+    if setting == "video-format":
+        return replace(cfg, video_format=value_n)
+
+    # unreachable
+    raise SystemExit(f"[mdl] ERROR: unknown setting '{setting}'.")
+
+
+def _norm_str(x: object) -> str:
+    return str(x).strip().lower()
+
+
+def _expand_path(value: str) -> Path:
+    return Path(os.path.expandvars(value)).expanduser()
+
+
+def _default_out_dir() -> str:
+    try:
+        return str(Path(Defaults.out_dir).resolve())
+    except Exception:
+        return str(Path(Defaults.out_dir))
+
+
+def _normalize_out_dir(raw: object, fallback: str) -> str:
+    try:
+        value = str(raw).strip()
+    except Exception:
+        return fallback
+    if not value:
+        return fallback
+    try:
+        return str(_expand_path(value).resolve())
+    except Exception:
+        return fallback

mdl/core/options.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class Options:
+    """
+    Raw CLI options (argparse output). Some fields are optional because not all
+    subcommands require them.
+    """
+    command: str
+    print_cmd: bool
+
+    # Download/info
+    url: Optional[str]
+    playlist_mode: str         # "auto" | "album" | "flat"
+
+    # Smoke
+    smoke_kind: Optional[str]  # "audio" | "video"
+
+    # Settings commands
+    list_values: bool          # --list
+    value: Optional[str]       # optional positional VALUE for settings
+
+    @staticmethod
+    def from_namespace(ns) -> "Options":
+        # In cli.py you used --print (dest defaults to "print").
+        # We store it internally as print_cmd to avoid using name "print".
+        return Options(
+            command=str(ns.command),
+            print_cmd=bool(getattr(ns, "print", False)),
+
+            url=(str(ns.url) if hasattr(ns, "url") else None),
+            playlist_mode=str(getattr(ns, "playlist_mode", "auto")),
+
+            smoke_kind=(
+                str(ns.smoke_kind)
+                if hasattr(ns, "smoke_kind") and ns.smoke_kind is not None
+                else None
+            ),
+
+            list_values=bool(getattr(ns, "list", False)),
+            value=(str(ns.value) if hasattr(ns, "value") and ns.value is not None else None),
+        )
+
+
+@dataclass(frozen=True)
+class AppConfig:
+    """
+    Persistent user configuration.
+    Values should be normalized (lowercase).
+    """
+    preset: str               # "safe" | "fast"
+    cookies: str              # "none" | "brave" | "chrome" | ...
+    cover: bool               # cover behavior enabled
+    audio_format: str         # "flac" | "mp3" | "opus" | "m4a"
+    video_format: str         # "mp4" | "mkv"
+    out_dir: str              # absolute base output path as string
+
+
+@dataclass(frozen=True)
+class RunOptions:
+    """
+    Resolved runtime options used by builders/runner.
+    Combines Defaults + AppConfig + command context.
+
+    Invariants:
+    - out_dir is defined (downloads)
+    - cookies_from is None when cookies are disabled
+    - limit_rate/sleep* are only set in safe preset
+    """
+    out_dir: Path
+    preset: str
+    cookies_from: Optional[str]
+    cover: bool
+    audio_format: str
+    video_format: str
+
+    # Internal network throttling derived from preset (not user-exposed)
+    limit_rate: Optional[str]
+    sleep_min: Optional[int]
+    sleep_max: Optional[int]
+    playlist_mode: str = "auto"

mdl/core/playlist.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from urllib.parse import parse_qs, urlparse
+
+def is_playlist_url(url: str) -> bool:
+    """
+    Best-effort heuristic used only for output templates.
+    yt-dlp remains the source of truth for what gets downloaded.
+    """
+    return "list=" in url
+
+
+def detect_playlist_layout(url: str) -> str:
+    """
+    Return the playlist output layout:
+    - "album": artist/channel folder + playlist folder
+    - "flat": single playlist folder
+
+    Rules:
+    - Non-playlist URLs => "flat" (layout is irrelevant for singles).
+    - YouTube Music album list IDs typically start with "OLAK".
+    """
+    if not is_playlist_url(url):
+        return "flat"
+
+    try:
+        query = parse_qs(urlparse(url).query)
+        list_ids = query.get("list", [])
+    except Exception:
+        list_ids = []
+
+    list_id = str(list_ids[0]).strip() if list_ids else ""
+    if list_id.upper().startswith("OLAK"):
+        return "album"
+    return "flat"

mdl/core/resolve.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from mdl.core.config import Defaults
+from mdl.core.config_store import load_config
+from mdl.core.options import Options, RunOptions
+
+
+def resolve_run_options(opts: Options) -> RunOptions:
+    """
+    Resolve runtime options from persisted config + Defaults.
+
+    Note:
+    - We intentionally do NOT expose rate/sleep/js runtime/remote components to the user.
+      Presets control internal throttling.
+    """
+    cfg = load_config()
+
+    out_raw = str(getattr(cfg, "out_dir", "")).strip()
+    out_value = out_raw if out_raw else str(Defaults.out_dir)
+    base_out = Path(os.path.expandvars(out_value)).expanduser()
+    try:
+        out_dir = base_out.resolve()
+    except Exception:
+        out_dir = Path(str(Defaults.out_dir)).expanduser().resolve()
+
+    preset = str(cfg.preset).strip().lower()
+
+    # Cookies: "none" disables cookies integration
+    cookies = str(cfg.cookies).strip().lower()
+    cookies_from = None if cookies == "none" else cookies
+
+    # Preset -> internal throttling (not user-visible)
+    if preset == "safe":
+        limit_rate = str(Defaults.limit_rate)
+        sleep_min = int(Defaults.sleep_min)
+        sleep_max = int(Defaults.sleep_max)
+    elif preset == "fast":
+        limit_rate = None
+        sleep_min = None
+        sleep_max = None
+    else:
+        # Defensive fallback: treat unknown preset as safe
+        preset = "safe"
+        limit_rate = str(Defaults.limit_rate)
+        sleep_min = int(Defaults.sleep_min)
+        sleep_max = int(Defaults.sleep_max)
+
+    # Defensive sanity checks (even though user can't set these via CLI)
+    if preset == "safe":
+        if sleep_min is None or sleep_max is None or sleep_min <= 0 or sleep_max <= 0:
+            raise SystemExit("[mdl] ERROR: internal sleep settings are invalid.")
+        if sleep_min > sleep_max:
+            raise SystemExit("[mdl] ERROR: internal sleep-min must be <= sleep-max.")
+
+    playlist_mode = str(getattr(opts, "playlist_mode", "auto")).strip().lower()
+    if playlist_mode not in {"auto", "album", "flat"}:
+        playlist_mode = "auto"
+
+    return RunOptions(
+        out_dir=out_dir,
+        preset=preset,
+        cookies_from=cookies_from,
+        cover=bool(cfg.cover),
+        audio_format=str(cfg.audio_format).strip().lower(),
+        video_format=str(cfg.video_format).strip().lower(),
+        limit_rate=limit_rate,
+        sleep_min=sleep_min,
+        sleep_max=sleep_max,
+        playlist_mode=playlist_mode,
+    )

mdl/infra/__init__.py

@@ -0,0 +1,3 @@
+from mdl.infra.runner import printable_cmd, print_command, run_command
+
+__all__ = ["printable_cmd", "print_command", "run_command"]

mdl/infra/runner.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import os
+import shutil
+import shlex
+import subprocess
+import sys
+from typing import List
+
+
+def _command_exists(name: str) -> bool:
+    return shutil.which(name) is not None
+
+
+def printable_cmd(cmd: List[str]) -> str:
+    if os.name == "nt":
+        return subprocess.list2cmdline(cmd)
+    return " ".join(shlex.quote(s) for s in cmd)
+
+
+def print_command(cmd: List[str]) -> None:
+    print(f"[mdl] exec: {printable_cmd(cmd)}")
+
+
+def _check_dependencies(*, needs_ffmpeg: bool) -> int:
+    if not _command_exists("yt-dlp"):
+        print("[mdl] ERROR: yt-dlp not found in PATH.", file=sys.stderr)
+        print("[mdl]        Install it (recommended): pipx install yt-dlp", file=sys.stderr)
+        print("[mdl]        Or ensure it is available in your PATH.", file=sys.stderr)
+        return 127
+
+    if needs_ffmpeg and not _command_exists("ffmpeg"):
+        print("[mdl] ERROR: ffmpeg not found in PATH.", file=sys.stderr)
+        print("[mdl]        Install it (Ubuntu/Debian): sudo apt install ffmpeg", file=sys.stderr)
+        print("[mdl]        Or ensure it is available in your PATH.", file=sys.stderr)
+        return 127
+
+    return 0
+
+
+def run_command(cmd: List[str], *, needs_ffmpeg: bool = False, print_first: bool = True) -> int:
+    """
+    Runs the given command, streaming stdout/stderr.
+    Returns the subprocess exit code.
+    """
+    dep_rc = _check_dependencies(needs_ffmpeg=needs_ffmpeg)
+    if dep_rc != 0:
+        # Keep transparency: still show what would have been executed.
+        if print_first:
+            print_command(cmd)
+        return dep_rc
+
+    if print_first:
+        print_command(cmd)
+
+    try:
+        p = subprocess.run(cmd)
+        return int(p.returncode)
+    except KeyboardInterrupt:
+        return 130

mdl/services/__init__.py

@@ -0,0 +1,15 @@
+from mdl.services.download_service import (
+    require_url,
+    run_audio_download,
+    run_video_download,
+    run_info,
+    run_smoke,
+)
+
+__all__ = [
+    "require_url",
+    "run_audio_download",
+    "run_video_download",
+    "run_info",
+    "run_smoke",
+]

mdl/services/download_service.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from mdl.builders.yt_dlp_audio import build_audio_command
+from mdl.builders.yt_dlp_video import build_video_command
+from mdl.builders.yt_dlp_info import build_info_command
+from mdl.core.options import Options, RunOptions
+from mdl.infra.runner import print_command, run_command
+
+
+# Deterministic smoke targets used to verify the full download pipeline.
+SMOKE_AUDIO_URL = "https://www.youtube.com/watch?v=dWRCooFKk3c"
+SMOKE_VIDEO_URL = "https://www.youtube.com/watch?v=jNQXAC9IVRw"
+
+def require_url(opts: Options) -> str:
+    if not opts.url:
+        cmd = opts.command or "command"
+        raise SystemExit(f"[mdl] ERROR: {cmd} requires URL. Try: mdl {cmd} -h")
+    return opts.url
+
+
+def _run_or_print(opts: Options, cmd: list[str], *, needs_ffmpeg: bool = False) -> int:
+    if opts.print_cmd:
+        print_command(cmd)
+        return 0
+    return run_command(cmd, needs_ffmpeg=needs_ffmpeg)
+
+
+def run_audio_download(opts: Options, run_opts: RunOptions) -> int:
+    url = require_url(opts)
+    cmd = build_audio_command(url, run_opts)
+    needs_ffmpeg = run_opts.cover
+    return _run_or_print(opts, cmd, needs_ffmpeg=needs_ffmpeg)
+
+
+def run_video_download(opts: Options, run_opts: RunOptions) -> int:
+    url = require_url(opts)
+    cmd = build_video_command(url, run_opts)
+    needs_ffmpeg = run_opts.cover
+    return _run_or_print(opts, cmd, needs_ffmpeg=needs_ffmpeg)
+
+
+def run_info(opts: Options, run_opts: RunOptions) -> int:
+    url = require_url(opts)
+    cmd = build_info_command(url, run_opts)
+    return _run_or_print(opts, cmd)
+
+
+def run_smoke(opts: Options, run_opts: RunOptions) -> int:
+    if opts.smoke_kind == "audio":
+        cmd = build_audio_command(SMOKE_AUDIO_URL, run_opts)
+    elif opts.smoke_kind == "video":
+        cmd = build_video_command(SMOKE_VIDEO_URL, run_opts)
+    else:
+        raise SystemExit("[mdl] ERROR: Unknown smoke kind (expected: audio|video).")
+
+    if opts.print_cmd:
+        print_command(cmd)
+        return 0
+
+    return run_command(cmd, needs_ffmpeg=run_opts.cover)

mdl_cli-0.3.0.dist-info/METADATA

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: mdl-cli
+Version: 0.3.0
+Summary: A human-friendly wrapper over yt-dlp.
+Author: Tomás Ezequiel Aguirre
+License: MIT License
+        
+        Copyright (c) 2026 Tomás Ezequiel Aguirre
+        
+        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.
+        
+Project-URL: Repository, https://github.com/tomieaguirre/mdl-cli
+Keywords: yt-dlp,downloader,cli,audio,video
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+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
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: yt-dlp>=2024.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov>=4; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: black>=24.0; extra == "dev"
+Dynamic: license-file
+
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![CI](https://github.com/tomieaguirre/mdl-cli/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/tomieaguirre/mdl-cli/actions/workflows/ci.yml?query=branch%3Amain)
+
+# mdl-cli
+
+`mdl` is a cross-platform CLI wrapper around `yt-dlp` with safer defaults and a simpler command surface.
+
+## Requirements
+
+- Python `>=3.10`
+- `ffmpeg` available in `PATH`
+
+`mdl` executes `yt-dlp` under the hood. Ensure `yt-dlp` is installed and available in `PATH`.
+
+## Installation
+
+Recommended (isolated app install):
+
+```bash
+pipx install mdl-cli
+```
+
+Alternative (standard Python environment):
+
+```bash
+pip install mdl-cli
+```
+
+For OS-specific setup (Python, `ffmpeg`, `yt-dlp`, and verification), see the [Installation Guide](docs/installation.md).
+
+## Basic Usage
+
+```bash
+mdl audio "URL"
+mdl video "URL"
+mdl info "URL"
+mdl --help
+```
+
+Supported platforms: Linux, macOS, and Windows.
+
+## Documentation
+
+Full command reference and advanced configuration:
+- [Installation Guide](docs/installation.md)
+- [Usage Guide](docs/usage.md)
+
+## License
+
+MIT (see [License](LICENSE))

mdl_cli-0.3.0.dist-info/RECORD

@@ -0,0 +1,30 @@
+mdl/__init__.py,sha256=-WXI6ePnpJ1-ibRIS9bWyTzx9KKgoWBdHznjRVI9ImE,195
+mdl/app.py,sha256=hXhGTZQXi1MYcyr6ZwathMGve4J7lemzgGOJiFZsX98,1500
+mdl/cli.py,sha256=WIJ1h-US3neUaQE4X5FZC2uvCtgQyUgss7A2KK2maxY,6076
+mdl/builders/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mdl/builders/yt_dlp_audio.py,sha256=M3Jll8fwxA67v6oOk5Mv-Xu9jvnly0jfObZk3SZIIX4,1597
+mdl/builders/yt_dlp_common.py,sha256=V_sA7hMkfSI87I72TtkT_DoKBvWZd09VkXolzSuYbKU,703
+mdl/builders/yt_dlp_info.py,sha256=nzHA84NDTR5UqN-PX39PXe_D01-S4WRrZ0C2_1VG9k4,447
+mdl/builders/yt_dlp_video.py,sha256=aurNJtOWjWqvvSswozTNX0p7M6bQ9QGnZw31tW012Aw,1391
+mdl/commands/__init__.py,sha256=bAScGj3QFhyjaHOQMWKU7_O_f8h0qU02VR_B1PQ-Kdc,341
+mdl/commands/audio.py,sha256=lWsbrx3R2GqviYdOjZ3tXBFacl6biChWRQNQOyRrj44,256
+mdl/commands/info.py,sha256=a5ZG3hm2IzJ2slGSM7cOWjNlFCl-xHWcMLsBqWaAGOw,235
+mdl/commands/settings.py,sha256=sVXItqq0l97FCmhI6MvAV04VmaLVBKSuVLQa1IwAyZg,1759
+mdl/commands/smoke.py,sha256=2vUhaaoWy21HgmBRxfPw6BvpRqkUn4T62oNpK80BgCM,238
+mdl/commands/video.py,sha256=pNJOQ3TSYmYg55THeE2IlUvvbO4NaDUzlvC51LdLlnQ,256
+mdl/core/__init__.py,sha256=BUr4rZXeKtOdrEol8DosJyqvvfOJrtn2W0H0LR8cMn8,254
+mdl/core/config.py,sha256=r1XE-butXZjGRyZn4h6glRGLdz18BF7RdOssITxT5as,3119
+mdl/core/config_store.py,sha256=0AsZlxLJMv7icdY-1lKCZAT_ieX2bN3xC1Ch4eNyCHs,5284
+mdl/core/options.py,sha256=sDXotvtQF_FcJtjZPWh6oZW8RxoXcukmRJVR3roRqt8,2554
+mdl/core/playlist.py,sha256=F5uEsXH0GJcC-qtD_2VRd0qlBzyZSJlAMYzU9AOC-R4,965
+mdl/core/resolve.py,sha256=9DLjKOJB1AEIpRHgsE2XGHhkX9wklqedCmiBVfXsefo,2518
+mdl/infra/__init__.py,sha256=BwTI-hcx54GhGDV_Cn7HCtaoD-9xzu4dqPSdatKy0K0,132
+mdl/infra/runner.py,sha256=qOOcihmFcSaEGLFNXrSpYhH-p10WtJFQ-SjRjDq1U4s,1784
+mdl/services/__init__.py,sha256=mA-LZnHeLheDppY5M9rv6CTmq94Ca61c8BogOVVJRhs,259
+mdl/services/download_service.py,sha256=_OrJqqa9kOs2oZz049sCwWgFi5DzIZe0XKszvLsLTpA,2053
+mdl_cli-0.3.0.dist-info/licenses/LICENSE,sha256=C8VyrqwLAOtNBP_TH_AlBzitg0vcM0tZGm0TDDdI570,1080
+mdl_cli-0.3.0.dist-info/METADATA,sha256=rFajLOAECejXQK8vjK8oxclIZo3-lcbxkby93nw_Vvw,3485
+mdl_cli-0.3.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+mdl_cli-0.3.0.dist-info/entry_points.txt,sha256=7u1H60O6FKjpQHfk6r9ft-Tt6RHYyOcoFI4lgBqgW2s,37
+mdl_cli-0.3.0.dist-info/top_level.txt,sha256=XzUJeQdNE2K7a6zWv5T4yj0nrs0wTr7KloMHefVnvr8,4
+mdl_cli-0.3.0.dist-info/RECORD,,

mdl_cli-0.3.0.dist-info/WHEEL

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

mdl_cli-0.3.0.dist-info/entry_points.txt

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

mdl_cli-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tomás Ezequiel Aguirre
+
+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.

mdl_cli-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mdl