mdl-cli 0.3.0__tar.gz → 0.3.1__tar.gz

{mdl_cli-0.3.0 → mdl_cli-0.3.1}/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.3.1] - 2026-10-22
+
+### Changed
+- `mdl` now prefers the `yt-dlp` installed as a dependency of `mdl-cli`, so upgrading `mdl-cli` also updates `yt-dlp` and its dependencies.
+- Dependency now requires `yt-dlp[default]>=2026.10.21`, which includes `yt-dlp-ejs` and current YouTube support.
+
+### Fixed
+- Corrected output template fallback syntax (for example, folders named `artist｜uploader`).
+- Audio, video, and smoke downloads now always require `ffmpeg`, since extraction and remuxing depend on it.
+- Removed the redundant `--add-metadata` flag from audio downloads.
+
 ## [0.3.0] - 2026-04-13
 
 ### Added

{mdl_cli-0.3.0/mdl_cli.egg-info → mdl_cli-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mdl-cli
-Version: 0.3.0
+Version: 0.3.1
 Summary: A human-friendly wrapper over yt-dlp.
 Author: Tomás Ezequiel Aguirre
 License: MIT License
@@ -39,7 +39,7 @@ Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: yt-dlp>=2024.0
+Requires-Dist: yt-dlp[default]>=2026.10.21
 Provides-Extra: dev
 Requires-Dist: pytest>=7; extra == "dev"
 Requires-Dist: pytest-cov>=4; extra == "dev"
@@ -59,8 +59,11 @@ Dynamic: license-file
 
 - Python `>=3.10`
 - `ffmpeg` available in `PATH`
+- A JavaScript runtime for YouTube (`deno >=2.3` recommended, or `node >=22`)
 
-`mdl` executes `yt-dlp` under the hood. Ensure `yt-dlp` is installed and available in `PATH`.
+`mdl` executes `yt-dlp` under the hood. Installing `mdl-cli` installs `yt-dlp[default]`
+(including `yt-dlp-ejs`) automatically. If `yt-dlp` is not bundled, `mdl` falls back to
+the `yt-dlp` available in `PATH`.
 
 ## Installation
 

{mdl_cli-0.3.0 → mdl_cli-0.3.1}/README.md

@@ -10,8 +10,11 @@
 
 - Python `>=3.10`
 - `ffmpeg` available in `PATH`
+- A JavaScript runtime for YouTube (`deno >=2.3` recommended, or `node >=22`)
 
-`mdl` executes `yt-dlp` under the hood. Ensure `yt-dlp` is installed and available in `PATH`.
+`mdl` executes `yt-dlp` under the hood. Installing `mdl-cli` installs `yt-dlp[default]`
+(including `yt-dlp-ejs`) automatically. If `yt-dlp` is not bundled, `mdl` falls back to
+the `yt-dlp` available in `PATH`.
 
 ## Installation
 

mdl_cli-0.3.1/docs/installation.md

@@ -0,0 +1,175 @@
+# Installation
+
+## Requirements
+
+- Python 3.10+
+- `ffmpeg` (required for audio extraction and video remuxing)
+- A JavaScript runtime for YouTube (`deno >=2.3` recommended, or `node >=22`)
+
+`mdl-cli` installs `yt-dlp[default]` automatically, which includes `yt-dlp-ejs`.
+If `yt-dlp` is not bundled, `mdl` falls back to the `yt-dlp` available in `PATH`.
+
+---
+
+## Install Python
+
+### Linux
+
+Use your distribution package manager. Example (Debian/Ubuntu):
+
+```bash
+sudo apt update
+sudo apt install -y python3 python3-pip python3-venv
+```
+
+### macOS
+
+```bash
+brew install python
+```
+
+### Windows
+
+PowerShell:
+
+```powershell
+winget install -e --id Python.Python.3.12
+```
+
+Manual installer:
+- https://www.python.org/downloads/windows/
+
+---
+
+## Install mdl-cli
+
+### Install pipx (if needed)
+
+Linux (Debian/Ubuntu):
+
+```bash
+sudo apt install pipx
+pipx ensurepath
+```
+
+macOS:
+
+```bash
+python3 -m pip install --user pipx
+python3 -m pipx ensurepath
+```
+
+Windows (PowerShell):
+
+```powershell
+py -m pip install --user pipx
+py -m pipx ensurepath
+```
+
+Open a new terminal after `ensurepath`.
+
+### Recommended (pipx)
+
+```bash
+pipx install mdl-cli
+```
+
+### Alternative (pip)
+
+```bash
+pip install mdl-cli
+```
+
+---
+
+## Install ffmpeg
+
+### Linux
+
+```bash
+sudo apt install ffmpeg
+```
+
+### macOS
+
+```bash
+brew install ffmpeg
+```
+
+### Windows
+
+PowerShell:
+
+```powershell
+winget install -e --id Gyan.FFmpeg
+```
+
+Manual install:
+- https://ffmpeg.org/download.html
+
+---
+
+## Install a JavaScript runtime (YouTube)
+
+yt-dlp needs a JavaScript runtime for full YouTube support. Deno is recommended and
+enabled by default.
+
+### Deno
+
+Linux/macOS:
+
+```bash
+curl -fsSL https://deno.land/install.sh | sh
+```
+
+Windows (PowerShell):
+
+```powershell
+winget install -e --id DenoLand.Deno
+```
+
+Minimum supported version: `2.3.0`.
+
+If you prefer Node.js (`>=22`), enable it in your yt-dlp configuration file with
+`--js-runtimes node`. See the yt-dlp EJS guide for details:
+https://github.com/yt-dlp/yt-dlp/wiki/EJS
+
+---
+
+## yt-dlp installation and updates
+
+`yt-dlp[default]` is installed automatically as a dependency of `mdl-cli`.
+You do not need to install it separately.
+
+To upgrade `mdl-cli` and its dependencies (including `yt-dlp` and `yt-dlp-ejs`):
+
+```bash
+pipx upgrade mdl-cli --pip-args="--upgrade-strategy eager"
+```
+
+If you install with `pip` instead:
+
+```bash
+pip install -U mdl-cli
+```
+
+`mdl` prefers the `yt-dlp` installed alongside it and falls back to `yt-dlp` in
+`PATH` when needed.
+
+---
+
+## Verify Installation
+
+```bash
+python --version
+ffmpeg -version
+deno --version
+mdl --version
+mdl smoke audio
+```
+
+Check the yt-dlp version used by `mdl`:
+
+```bash
+mdl info "https://www.youtube.com/watch?v=jNQXAC9IVRw"
+```

{mdl_cli-0.3.0 → mdl_cli-0.3.1}/docs/usage.md

@@ -15,8 +15,11 @@ It provides:
 ## Requirements
 
 - Python `>=3.10`
-- `yt-dlp` available in `PATH`
-- `ffmpeg` available in `PATH` (required when `cover=on`)
+- `ffmpeg` available in `PATH` (required for audio extraction and video remuxing)
+- A JavaScript runtime for YouTube (`deno >=2.3` recommended, or `node >=22`)
+
+`mdl-cli` installs `yt-dlp[default]` (including `yt-dlp-ejs`) automatically. If it is
+not bundled, `mdl` falls back to `yt-dlp` in `PATH`.
 
 ## Installation
 
@@ -173,11 +176,11 @@ Downloads include:
 
 ## Output Templates
 
-- Audio single: `%(artists.0|artist|uploader)s/%(title)s.%(ext)s`
-- Audio playlist (album): `%(artists.0|artist|uploader)s/%(playlist_title|playlist)s/%(playlist_index)02d - %(title)s.%(ext)s`
-- Audio playlist (flat): `%(playlist_title|playlist)s/%(playlist_index)02d - %(title)s.%(ext)s`
-- Video single: `%(uploader|channel)s/%(title)s.%(ext)s`
-- Video playlist: `%(playlist_title|playlist)s/%(playlist_index)02d - %(title)s.%(ext)s`
+- Audio single: `%(artists.0,artist,uploader|Unknown)s/%(title)s.%(ext)s`
+- Audio playlist (album): `%(artists.0,artist,uploader|Unknown)s/%(playlist_title,playlist|Unknown)s/%(playlist_index)02d - %(title)s.%(ext)s`
+- Audio playlist (flat): `%(playlist_title,playlist|Unknown)s/%(playlist_index)02d - %(title)s.%(ext)s`
+- Video single: `%(uploader,channel|Unknown)s/%(title)s.%(ext)s`
+- Video playlist: `%(playlist_title,playlist|Unknown)s/%(playlist_index)02d - %(title)s.%(ext)s`
 
 Layout behavior:
 
@@ -198,12 +201,32 @@ Command-level defaults:
 
 ## Troubleshooting
 
-### `yt-dlp not found in PATH`
+### `yt-dlp is not available`
+
+Reinstall `mdl-cli` so its dependencies are installed:
+
+```bash
+pipx install --force mdl-cli
+```
+
+When using `pip`:
+
+```bash
+pip install --force-reinstall mdl-cli
+```
+
+If you want an explicit external install:
+
+```bash
+pipx install "yt-dlp[default]"
+```
+
+### `yt-dlp` version warning
 
-Install `yt-dlp` and verify:
+Update `mdl-cli` and all of its dependencies:
 
 ```bash
-yt-dlp --version
+pipx upgrade mdl-cli --pip-args="--upgrade-strategy eager"
 ```
 
 ### `ffmpeg not found in PATH`

{mdl_cli-0.3.0 → mdl_cli-0.3.1}/mdl/builders/yt_dlp_audio.py

@@ -6,6 +6,7 @@ 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
+from mdl.core.runtime import yt_dlp_command
 
 
 def build_audio_command(url: str, opts: RunOptions) -> List[str]:
@@ -24,14 +25,14 @@ def build_audio_command(url: str, opts: RunOptions) -> List[str]:
         tpl = Defaults.audio_single_tpl
     out_template = str(opts.out_dir / tpl)
 
-    cmd: List[str] = ["yt-dlp"]
+    cmd: List[str] = yt_dlp_command()
     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"]
+    cmd += ["--embed-metadata"]
 
     if is_playlist:
         # Normalize autogenerated labels like "Album - <name>" to "<name>".

{mdl_cli-0.3.0 → mdl_cli-0.3.1}/mdl/builders/yt_dlp_info.py

@@ -4,6 +4,7 @@ from typing import List
 
 from mdl.builders.yt_dlp_common import base_yt_dlp_args
 from mdl.core.options import RunOptions
+from mdl.core.runtime import yt_dlp_command
 
 
 def build_info_command(url: str, opts: RunOptions) -> List[str]:
@@ -12,7 +13,7 @@ def build_info_command(url: str, opts: RunOptions) -> List[str]:
 
     Equivalent to: yt-dlp -F URL
     """
-    cmd: List[str] = ["yt-dlp"]
+    cmd: List[str] = yt_dlp_command()
     cmd += base_yt_dlp_args(opts)
     cmd += ["-F", url]
     return cmd

{mdl_cli-0.3.0 → mdl_cli-0.3.1}/mdl/builders/yt_dlp_video.py

@@ -6,6 +6,7 @@ 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
+from mdl.core.runtime import yt_dlp_command
 
 
 def build_video_command(url: str, opts: RunOptions) -> List[str]:
@@ -20,7 +21,7 @@ def build_video_command(url: str, opts: RunOptions) -> List[str]:
     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: List[str] = yt_dlp_command()
     cmd += base_yt_dlp_args(opts)
 
     # Best quality selection (avoid forcing container here)

{mdl_cli-0.3.0 → mdl_cli-0.3.1}/mdl/core/config.py

@@ -79,12 +79,12 @@ class Defaults:
 
     # 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"
+    audio_single_tpl: str = "%(artists.0,artist,uploader|Unknown)s/%(title)s.%(ext)s"
+    audio_playlist_tpl: str = "%(artists.0,artist,uploader|Unknown)s/%(playlist_title,playlist|Unknown)s/%(playlist_index)02d - %(title)s.%(ext)s"
+    video_playlist_tpl: str = "%(uploader,channel|Unknown)s/%(playlist_title,playlist|Unknown)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"
+    audio_playlist_flat_tpl: str = "%(playlist_title,playlist|Unknown)s/%(playlist_index)02d - %(title)s.%(ext)s"
+    video_playlist_flat_tpl: str = "%(playlist_title,playlist|Unknown)s/%(playlist_index)02d - %(title)s.%(ext)s"
 
-    video_single_tpl: str = "%(uploader|channel)s/%(title)s.%(ext)s"
+    video_single_tpl: str = "%(uploader,channel|Unknown)s/%(title)s.%(ext)s"

mdl_cli-0.3.1/mdl/core/runtime.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+import importlib.util
+import re
+import shutil
+import subprocess
+import sys
+from datetime import date
+from functools import lru_cache
+
+YT_DLP_MAX_AGE_DAYS = 90
+
+_VERSION_DATE_RE = re.compile(
+    r"^(?P<year>\d{4})\.(?P<month>\d{2})\.(?P<day>\d{2})(?:\.|$)"
+)
+
+
+def has_bundled_yt_dlp() -> bool:
+    """Whether yt-dlp is installed alongside mdl."""
+    return importlib.util.find_spec("yt_dlp") is not None
+
+
+def yt_dlp_command() -> list[str]:
+    """
+    Return the command prefix used to invoke yt-dlp.
+
+    Prefer the yt-dlp installed as a dependency of mdl so that installing or
+    upgrading mdl also installs or upgrades yt-dlp. Fall back to PATH for
+    development setups that manage yt-dlp externally.
+    """
+    if has_bundled_yt_dlp():
+        return [sys.executable, "-m", "yt_dlp"]
+    return ["yt-dlp"]
+
+
+def yt_dlp_available() -> bool:
+    return has_bundled_yt_dlp() or shutil.which("yt-dlp") is not None
+
+
+def _bundled_yt_dlp_version() -> str | None:
+    from importlib.metadata import PackageNotFoundError, version
+
+    try:
+        return version("yt-dlp")
+    except PackageNotFoundError:
+        pass
+
+    try:
+        from yt_dlp.version import __version__
+    except ImportError:
+        return None
+
+    return str(__version__)
+
+
+def _external_yt_dlp_version() -> str | None:
+    executable = shutil.which("yt-dlp")
+    if executable is None:
+        return None
+
+    try:
+        result = subprocess.run(
+            [executable, "--version"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+
+    if result.returncode != 0:
+        return None
+
+    version = result.stdout.strip()
+    return version or None
+
+
+@lru_cache(maxsize=1)
+def yt_dlp_version() -> str | None:
+    version = _bundled_yt_dlp_version()
+    if version:
+        return version
+    return _external_yt_dlp_version()
+
+
+def yt_dlp_age_days(version: str, *, today: date | None = None) -> int | None:
+    match = _VERSION_DATE_RE.match(version)
+    if match is None:
+        return None
+
+    try:
+        released = date(
+            int(match.group("year")),
+            int(match.group("month")),
+            int(match.group("day")),
+        )
+    except ValueError:
+        return None
+
+    return ((today or date.today()) - released).days
+
+
+def yt_dlp_update_hint() -> str:
+    if has_bundled_yt_dlp():
+        return 'pipx upgrade mdl-cli --pip-args="--upgrade-strategy eager"'
+    return 'pipx install --force "yt-dlp[default]"'
+
+
+def yt_dlp_version_warning(*, today: date | None = None) -> str | None:
+    version = yt_dlp_version()
+    if version is None:
+        return None
+
+    age = yt_dlp_age_days(version, today=today)
+    if age is None or age <= YT_DLP_MAX_AGE_DAYS:
+        return None
+
+    return (
+        f"[mdl] WARNING: yt-dlp {version} is {age} days old. "
+        f"Update it with: {yt_dlp_update_hint()}"
+    )

{mdl_cli-0.3.0 → mdl_cli-0.3.1}/mdl/infra/runner.py

@@ -7,6 +7,8 @@ import subprocess
 import sys
 from typing import List
 
+from mdl.core import runtime
+
 
 def _command_exists(name: str) -> bool:
     return shutil.which(name) is not None
@@ -23,10 +25,17 @@ def print_command(cmd: List[str]) -> None:
 
 
 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)
+    if not runtime.yt_dlp_available():
+        print("[mdl] ERROR: yt-dlp is not available.", file=sys.stderr)
+        print(
+            "[mdl]        Reinstall mdl-cli so its dependencies are installed: "
+            "pipx install --force mdl-cli",
+            file=sys.stderr,
+        )
+        print(
+            '[mdl]        Or install yt-dlp manually: pipx install "yt-dlp[default]"',
+            file=sys.stderr,
+        )
         return 127
 
     if needs_ffmpeg and not _command_exists("ffmpeg"):
@@ -35,6 +44,10 @@ def _check_dependencies(*, needs_ffmpeg: bool) -> int:
         print("[mdl]        Or ensure it is available in your PATH.", file=sys.stderr)
         return 127
 
+    warning = runtime.yt_dlp_version_warning()
+    if warning:
+        print(warning, file=sys.stderr)
+
     return 0
 
 

{mdl_cli-0.3.0 → mdl_cli-0.3.1}/mdl/services/download_service.py

@@ -28,15 +28,13 @@ def _run_or_print(opts: Options, cmd: list[str], *, needs_ffmpeg: bool = False)
 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)
+    return _run_or_print(opts, cmd, needs_ffmpeg=True)
 
 
 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)
+    return _run_or_print(opts, cmd, needs_ffmpeg=True)
 
 
 def run_info(opts: Options, run_opts: RunOptions) -> int:
@@ -57,4 +55,4 @@ def run_smoke(opts: Options, run_opts: RunOptions) -> int:
         print_command(cmd)
         return 0
 
-    return run_command(cmd, needs_ffmpeg=run_opts.cover)
+    return run_command(cmd, needs_ffmpeg=True)

{mdl_cli-0.3.0 → mdl_cli-0.3.1/mdl_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mdl-cli
-Version: 0.3.0
+Version: 0.3.1
 Summary: A human-friendly wrapper over yt-dlp.
 Author: Tomás Ezequiel Aguirre
 License: MIT License
@@ -39,7 +39,7 @@ Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: yt-dlp>=2024.0
+Requires-Dist: yt-dlp[default]>=2026.10.21
 Provides-Extra: dev
 Requires-Dist: pytest>=7; extra == "dev"
 Requires-Dist: pytest-cov>=4; extra == "dev"
@@ -59,8 +59,11 @@ Dynamic: license-file
 
 - Python `>=3.10`
 - `ffmpeg` available in `PATH`
+- A JavaScript runtime for YouTube (`deno >=2.3` recommended, or `node >=22`)
 
-`mdl` executes `yt-dlp` under the hood. Ensure `yt-dlp` is installed and available in `PATH`.
+`mdl` executes `yt-dlp` under the hood. Installing `mdl-cli` installs `yt-dlp[default]`
+(including `yt-dlp-ejs`) automatically. If `yt-dlp` is not bundled, `mdl` falls back to
+the `yt-dlp` available in `PATH`.
 
 ## Installation
 

{mdl_cli-0.3.0 → mdl_cli-0.3.1}/mdl_cli.egg-info/SOURCES.txt

@@ -27,6 +27,7 @@ mdl/core/config_store.py
 mdl/core/options.py
 mdl/core/playlist.py
 mdl/core/resolve.py
+mdl/core/runtime.py
 mdl/infra/__init__.py
 mdl/infra/runner.py
 mdl/services/__init__.py
@@ -36,6 +37,8 @@ mdl_cli.egg-info/SOURCES.txt
 mdl_cli.egg-info/dependency_links.txt
 mdl_cli.egg-info/entry_points.txt
 mdl_cli.egg-info/requires.txt
+mdl_cli.egg-info/scm_file_list.json
+mdl_cli.egg-info/scm_version.json
 mdl_cli.egg-info/top_level.txt
 tests/conftest.py
 tests/test_app.py
@@ -49,5 +52,6 @@ tests/test_core_config_store.py
 tests/test_core_options.py
 tests/test_core_playlist.py
 tests/test_core_resolve.py
+tests/test_core_runtime.py
 tests/test_infra_runner.py
 tests/test_services_download_service.py

{mdl_cli-0.3.0 → mdl_cli-0.3.1}/mdl_cli.egg-info/requires.txt

@@ -1,4 +1,4 @@
-yt-dlp>=2024.0
+yt-dlp[default]>=2026.10.21
 
 [dev]
 pytest>=7

mdl_cli-0.3.1/mdl_cli.egg-info/scm_file_list.json

@@ -0,0 +1,53 @@
+{
+  "files": [
+    ".github/workflows/ci.yml",
+    ".github/workflows/release.yml",
+    ".gitignore",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md",
+    "docs/installation.md",
+    "docs/usage.md",
+    "mdl/__init__.py",
+    "mdl/app.py",
+    "mdl/builders/__init__.py",
+    "mdl/builders/yt_dlp_audio.py",
+    "mdl/builders/yt_dlp_common.py",
+    "mdl/builders/yt_dlp_info.py",
+    "mdl/builders/yt_dlp_video.py",
+    "mdl/cli.py",
+    "mdl/commands/__init__.py",
+    "mdl/commands/audio.py",
+    "mdl/commands/info.py",
+    "mdl/commands/settings.py",
+    "mdl/commands/smoke.py",
+    "mdl/commands/video.py",
+    "mdl/core/__init__.py",
+    "mdl/core/config.py",
+    "mdl/core/config_store.py",
+    "mdl/core/options.py",
+    "mdl/core/playlist.py",
+    "mdl/core/resolve.py",
+    "mdl/core/runtime.py",
+    "mdl/infra/__init__.py",
+    "mdl/infra/runner.py",
+    "mdl/services/__init__.py",
+    "mdl/services/download_service.py",
+    "pyproject.toml",
+    "tests/conftest.py",
+    "tests/test_app.py",
+    "tests/test_builders.py",
+    "tests/test_builders_common.py",
+    "tests/test_cli.py",
+    "tests/test_commands_settings.py",
+    "tests/test_commands_wrappers.py",
+    "tests/test_core_config.py",
+    "tests/test_core_config_store.py",
+    "tests/test_core_options.py",
+    "tests/test_core_playlist.py",
+    "tests/test_core_resolve.py",
+    "tests/test_core_runtime.py",
+    "tests/test_infra_runner.py",
+    "tests/test_services_download_service.py"
+  ]
+}

mdl_cli-0.3.1/mdl_cli.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "0.3.1",
+  "distance": 0,
+  "node": "gc9fdff90179cb2f7ace5a84c5642b42cd2b9a797",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-10-22"
+}

{mdl_cli-0.3.0 → mdl_cli-0.3.1}/pyproject.toml

@@ -17,7 +17,7 @@ authors = [
 keywords = ["yt-dlp", "downloader", "cli", "audio", "video"]
 
 dependencies = [
-  "yt-dlp>=2024.0"
+  "yt-dlp[default]>=2026.10.21"
 ]
 
 classifiers = [

{mdl_cli-0.3.0 → mdl_cli-0.3.1}/tests/test_builders.py

@@ -4,6 +4,7 @@ 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.config import Defaults
+from mdl.core.runtime import yt_dlp_command
 
 
 def _assert_contains_kv(cmd: list[str], key: str, value: str) -> None:
@@ -27,7 +28,7 @@ def test_audio_single_with_shared_flags_and_cover_snapshot(make_run_options) ->
     cmd = build_audio_command(url, opts)
 
     assert cmd == [
-        "yt-dlp",
+        *yt_dlp_command(),
         "--cookies-from-browser",
         "brave",
         "--limit-rate",
@@ -41,7 +42,6 @@ def test_audio_single_with_shared_flags_and_cover_snapshot(make_run_options) ->
         "-x",
         "--audio-format",
         "opus",
-        "--add-metadata",
         "--embed-metadata",
         "--embed-thumbnail",
         "--ignore-errors",
@@ -59,11 +59,10 @@ def test_audio_playlist_uses_playlist_template_and_no_cover_flags(make_run_optio
 
     cmd = build_audio_command(url, opts)
 
-    assert cmd[0] == "yt-dlp"
+    assert cmd[: len(yt_dlp_command())] == yt_dlp_command()
     _assert_contains_kv(cmd, "-f", "bestaudio/best")
     assert "-x" in cmd
     _assert_contains_kv(cmd, "--audio-format", "m4a")
-    assert "--add-metadata" in cmd
     assert "--embed-metadata" in cmd
     assert "--ignore-errors" in cmd
     assert "--continue" in cmd
@@ -107,7 +106,7 @@ def test_video_single_cover_flags_present_only_when_cover_true(make_run_options)
 
     cmd = build_video_command(url, opts)
 
-    assert cmd[0] == "yt-dlp"
+    assert cmd[: len(yt_dlp_command())] == yt_dlp_command()
     _assert_contains_kv(cmd, "-f", "bv*+ba/b")
     _assert_contains_kv(cmd, "--remux-video", "mkv")
 
@@ -125,7 +124,7 @@ def test_video_playlist_cover_flags_absent_when_cover_false(make_run_options) ->
 
     cmd = build_video_command(url, opts)
 
-    assert cmd[0] == "yt-dlp"
+    assert cmd[: len(yt_dlp_command())] == yt_dlp_command()
     _assert_contains_kv(cmd, "-f", "bv*+ba/b")
     _assert_contains_kv(cmd, "--remux-video", "mp4")
     assert "--replace-in-metadata" in cmd
@@ -152,7 +151,7 @@ def test_info_command_minimal(make_run_options) -> None:
     opts = make_run_options()
 
     cmd = build_info_command(url, opts)
-    assert cmd == ["yt-dlp", "-F", url]
+    assert cmd == [*yt_dlp_command(), "-F", url]
 
 
 def test_info_command_includes_shared_flags_when_present(make_run_options) -> None:
@@ -166,7 +165,7 @@ def test_info_command_includes_shared_flags_when_present(make_run_options) -> No
 
     cmd = build_info_command(url, opts)
 
-    assert cmd[0] == "yt-dlp"
+    assert cmd[: len(yt_dlp_command())] == yt_dlp_command()
     _assert_contains_kv(cmd, "--cookies-from-browser", "chrome")
     _assert_contains_kv(cmd, "--limit-rate", "1M")
     _assert_contains_kv(cmd, "--sleep-interval", "5")

{mdl_cli-0.3.0 → mdl_cli-0.3.1}/tests/test_core_config.py

@@ -31,13 +31,21 @@ def test_xdg_music_dir_reads_user_dirs_file_and_expands_home(
 
 
 def test_defaults_audio_templates_use_primary_artist_first() -> None:
-    assert core_config.Defaults.audio_single_tpl.startswith("%(artists.0|artist|uploader)s/")
-    assert core_config.Defaults.audio_playlist_tpl.startswith("%(artists.0|artist|uploader)s/")
+    assert core_config.Defaults.audio_single_tpl.startswith(
+        "%(artists.0,artist,uploader|Unknown)s/"
+    )
+    assert core_config.Defaults.audio_playlist_tpl.startswith(
+        "%(artists.0,artist,uploader|Unknown)s/"
+    )
 
 
 def test_defaults_flat_playlist_templates_group_under_playlist_folder() -> None:
-    assert core_config.Defaults.audio_playlist_flat_tpl.startswith("%(playlist_title|playlist)s/")
-    assert core_config.Defaults.video_playlist_flat_tpl.startswith("%(playlist_title|playlist)s/")
+    assert core_config.Defaults.audio_playlist_flat_tpl.startswith(
+        "%(playlist_title,playlist|Unknown)s/"
+    )
+    assert core_config.Defaults.video_playlist_flat_tpl.startswith(
+        "%(playlist_title,playlist|Unknown)s/"
+    )
 
 
 def test_default_config_dir_uses_xdg_on_linux(monkeypatch, tmp_path: Path) -> None:

mdl_cli-0.3.1/tests/test_core_runtime.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import sys
+from datetime import date
+
+from mdl.core import runtime
+
+
+def test_yt_dlp_command_prefers_bundled_module(monkeypatch) -> None:
+    monkeypatch.setattr(runtime, "has_bundled_yt_dlp", lambda: True)
+
+    assert runtime.yt_dlp_command() == [sys.executable, "-m", "yt_dlp"]
+
+
+def test_yt_dlp_command_falls_back_to_path(monkeypatch) -> None:
+    monkeypatch.setattr(runtime, "has_bundled_yt_dlp", lambda: False)
+
+    assert runtime.yt_dlp_command() == ["yt-dlp"]
+
+
+def test_yt_dlp_age_days_parses_release_date() -> None:
+    assert runtime.yt_dlp_age_days("2026.02.04", today=date(2026, 10, 22)) == 260
+
+
+def test_yt_dlp_age_days_rejects_unparseable_versions() -> None:
+    assert runtime.yt_dlp_age_days("nightly", today=date(2026, 10, 22)) is None
+
+
+def test_yt_dlp_version_warning_for_old_version(monkeypatch) -> None:
+    monkeypatch.setattr(runtime, "yt_dlp_version", lambda: "2026.02.04")
+    monkeypatch.setattr(runtime, "yt_dlp_update_hint", lambda: "update-me")
+
+    warning = runtime.yt_dlp_version_warning(today=date(2026, 10, 22))
+
+    assert warning is not None
+    assert "2026.02.04" in warning
+    assert "260 days old" in warning
+    assert "update-me" in warning
+
+
+def test_yt_dlp_version_warning_for_recent_version(monkeypatch) -> None:
+    monkeypatch.setattr(runtime, "yt_dlp_version", lambda: "2026.10.21")
+
+    assert runtime.yt_dlp_version_warning(today=date(2026, 10, 22)) is None
+
+
+def test_yt_dlp_version_warning_without_version(monkeypatch) -> None:
+    monkeypatch.setattr(runtime, "yt_dlp_version", lambda: None)
+
+    assert runtime.yt_dlp_version_warning(today=date(2026, 10, 22)) is None

{mdl_cli-0.3.0 → mdl_cli-0.3.1}/tests/test_infra_runner.py

@@ -3,8 +3,6 @@ from __future__ import annotations
 import os
 from types import SimpleNamespace
 
-import pytest
-
 from mdl.infra import runner
 
 
@@ -17,17 +15,19 @@ def test_printable_cmd_quotes_arguments_with_spaces() -> None:
 
 
 def test_check_dependencies_returns_127_when_yt_dlp_is_missing(monkeypatch, capsys) -> None:
-    monkeypatch.setattr(runner, "_command_exists", lambda name: False if name == "yt-dlp" else True)
+    monkeypatch.setattr(runner.runtime, "yt_dlp_available", lambda: False)
 
     rc = runner._check_dependencies(needs_ffmpeg=False)
     captured = capsys.readouterr()
 
     assert rc == 127
-    assert "yt-dlp not found in PATH" in captured.err
+    assert "yt-dlp is not available" in captured.err
 
 
 def test_check_dependencies_returns_127_when_ffmpeg_is_required_and_missing(monkeypatch, capsys) -> None:
-    monkeypatch.setattr(runner, "_command_exists", lambda name: name == "yt-dlp")
+    monkeypatch.setattr(runner.runtime, "yt_dlp_available", lambda: True)
+    monkeypatch.setattr(runner, "_command_exists", lambda name: name != "ffmpeg")
+    monkeypatch.setattr(runner.runtime, "yt_dlp_version_warning", lambda: None)
 
     rc = runner._check_dependencies(needs_ffmpeg=True)
     captured = capsys.readouterr()
@@ -36,6 +36,22 @@ def test_check_dependencies_returns_127_when_ffmpeg_is_required_and_missing(monk
     assert "ffmpeg not found in PATH" in captured.err
 
 
+def test_check_dependencies_warns_when_yt_dlp_is_old(monkeypatch, capsys) -> None:
+    monkeypatch.setattr(runner.runtime, "yt_dlp_available", lambda: True)
+    monkeypatch.setattr(runner, "_command_exists", lambda name: True)
+    monkeypatch.setattr(
+        runner.runtime,
+        "yt_dlp_version_warning",
+        lambda: "[mdl] WARNING: yt-dlp is old",
+    )
+
+    rc = runner._check_dependencies(needs_ffmpeg=False)
+    captured = capsys.readouterr()
+
+    assert rc == 0
+    assert "yt-dlp is old" in captured.err
+
+
 def test_run_command_returns_dependency_error_and_still_prints_command(monkeypatch, capsys) -> None:
     monkeypatch.setattr(runner, "_check_dependencies", lambda *, needs_ffmpeg: 127)
     monkeypatch.setattr(runner.subprocess, "run", lambda cmd: (_ for _ in ()).throw(AssertionError("unexpected call")))

{mdl_cli-0.3.0 → mdl_cli-0.3.1}/tests/test_services_download_service.py

@@ -50,7 +50,7 @@ def test_run_audio_download_builds_command_and_passes_ffmpeg_requirement(
     monkeypatch.setattr(svc, "_run_or_print", fake_run_or_print)
 
     opts = make_options(command="audio", url="https://example.com")
-    run_opts = make_run_options(cover=True, audio_format="opus")
+    run_opts = make_run_options(cover=False, audio_format="opus")
     rc = svc.run_audio_download(opts, run_opts)
 
     assert rc == 7
@@ -83,7 +83,7 @@ def test_run_video_download_builds_command_and_passes_ffmpeg_requirement(
 
     assert rc == 9
     assert calls["cmd"] == ["video-cmd", "https://example.com", "mkv"]
-    assert calls["needs_ffmpeg"] is False
+    assert calls["needs_ffmpeg"] is True
 
 
 def test_run_info_builds_info_command_without_ffmpeg_flag(
@@ -130,7 +130,7 @@ def test_run_smoke_audio_print_mode_uses_smoke_audio_url(
     assert printed == [["audio-smoke", svc.SMOKE_AUDIO_URL]]
 
 
-def test_run_smoke_video_executes_with_cover_driven_ffmpeg_requirement(
+def test_run_smoke_video_always_requires_ffmpeg(
     monkeypatch,
     make_options,
     make_run_options,
@@ -147,7 +147,7 @@ def test_run_smoke_video_executes_with_cover_driven_ffmpeg_requirement(
     monkeypatch.setattr(svc, "run_command", fake_run_command)
 
     opts = make_options(command="smoke", smoke_kind="video", print_cmd=False, url=None)
-    rc = svc.run_smoke(opts, make_run_options(cover=True))
+    rc = svc.run_smoke(opts, make_run_options(cover=False))
 
     assert rc == 5
     assert calls["cmd"] == ["video-smoke", svc.SMOKE_VIDEO_URL]

mdl_cli-0.3.0/docs/installation.md

@@ -1,131 +0,0 @@
-# Installation
-
-## Requirements
-
-- Python 3.10+
-- `ffmpeg` (required for some features)
-- `yt-dlp` available in `PATH`
-
----
-
-## Install Python
-
-### Linux
-
-Use your distribution package manager. Example (Debian/Ubuntu):
-
-```bash
-sudo apt update
-sudo apt install -y python3 python3-pip python3-venv
-```
-
-### macOS
-
-```bash
-brew install python
-```
-
-### Windows
-
-PowerShell:
-
-```powershell
-winget install -e --id Python.Python.3.12
-```
-
-Manual installer:
-- https://www.python.org/downloads/windows/
-
----
-
-## Install mdl-cli
-
-### Install pipx (if needed)
-
-Linux (Debian/Ubuntu):
-
-```bash
-sudo apt install pipx
-pipx ensurepath
-```
-
-macOS:
-
-```bash
-python3 -m pip install --user pipx
-python3 -m pipx ensurepath
-```
-
-Windows (PowerShell):
-
-```powershell
-py -m pip install --user pipx
-py -m pipx ensurepath
-```
-
-Open a new terminal after `ensurepath`.
-
-### Recommended (pipx)
-
-```bash
-pipx install mdl-cli
-```
-
-### Alternative (pip)
-
-```bash
-pip install mdl-cli
-```
-
----
-
-## Install ffmpeg
-
-### Linux
-
-```bash
-sudo apt install ffmpeg
-```
-
-### macOS
-
-```bash
-brew install ffmpeg
-```
-
-### Windows
-
-PowerShell:
-
-```powershell
-winget install -e --id Gyan.FFmpeg
-```
-
-Manual install:
-- https://ffmpeg.org/download.html
-
----
-
-## Install yt-dlp
-
-```bash
-pipx install yt-dlp
-```
-
-If you prefer `pip`:
-
-```bash
-pip install yt-dlp
-```
-
----
-
-## Verify Installation
-
-```bash
-python --version
-yt-dlp --version
-ffmpeg -version
-mdl --version
-mdl smoke audio
-```