evo-cli 0.20.2__tar.gz → 0.21.0__tar.gz

{evo_cli-0.20.2 → evo_cli-0.21.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: evo_cli
-Version: 0.20.2
+Version: 0.21.0
 Summary: Evolution CLI - a developer toolbox for setting up dev machines
 Author: maycuatroi
 Project-URL: Homepage, https://github.com/maycuatroi/evo-cli

evo_cli-0.21.0/evo_cli/VERSION

@@ -0,0 +1 @@
+0.21.0

{evo_cli-0.20.2 → evo_cli-0.21.0}/evo_cli/commands/download.py

@@ -1,9 +1,11 @@
 import datetime
 import importlib.util
+import json
 import os
 import shutil
 import subprocess
 import sys
+import tempfile
 from pathlib import Path
 from urllib.parse import unquote, urlparse
 
@@ -28,6 +30,17 @@ CONTAINERS = ["mp4", "mkv", "webm", "auto"]
 BROWSERS = ["chrome", "edge", "firefox", "brave", "chromium", "opera", "vivaldi", "safari"]
 JS_RUNTIMES = ["deno", "bun", "node"]
 YTDLP_STALE_DAYS = 60
+# Codecs an MP4 is actually expected to carry. Facebook reels and YouTube serve
+# their best streams as VP9 / AV1, and muxing those into MP4 gives a file that
+# QuickTime, Photos and iMovie open with sound but a black picture - the picture
+# is there, macOS just has no VP9 decoder. Anything outside this set gets
+# re-encoded to H.264 so the download plays everywhere.
+PLAYABLE_VCODECS = frozenset({"h264", "hevc", "mpeg4", "mjpeg", "prores"})
+PLAYABLE_ACODECS = frozenset({"aac", "mp3", "ac3", "eac3", "alac"})
+# VP9 and AV1 fit the same picture into fewer bits than H.264 does, so matching
+# the source bitrate would visibly soften the result.
+H264_BITRATE_HEADROOM = 1.5
+MIN_H264_BITRATE = 1_000_000
 # Facebook reels and Instagram posts hand back the whole caption as the title,
 # which walks straight past the 255-byte limit filesystems put on a single path
 # component. `.<N>B` truncates the field to N bytes (before yt-dlp swaps `:` and
@@ -107,6 +120,7 @@ EPILOG = Text.from_markup(
     "  [cyan]evo download <url> --section 10:00-15:00[/cyan]    cut a clip out of a long video\n"
     "  [cyan]evo download <url> -p --archive[/cyan]             whole playlist, skip what you have\n"
     "  [cyan]evo download <url> --cookies chrome[/cyan]         private / age-gated / member-only\n"
+    "  [cyan]evo download <url> --keep-codec[/cyan]             keep VP9 / AV1, skip the H.264 pass\n"
     "  [cyan]evo download formats <url>[/cyan]                  list every available stream\n"
     "  [cyan]evo download check[/cyan]                          verify yt-dlp + ffmpeg\n"
     "  [cyan]evo download sites[/cyan]                          common supported sources\n\n"
@@ -193,6 +207,137 @@ def ffmpeg_version():
     return first[0] if first else None
 
 
+def find_ffprobe():
+    return shutil.which("ffprobe")
+
+
+def probe_media(path):
+    """Codecs and bitrate of `path`, or None when ffprobe cannot read it."""
+    exe = find_ffprobe()
+    if not exe:
+        return None
+    cmd = [
+        exe,
+        "-v",
+        "error",
+        "-show_entries",
+        "stream=codec_type,codec_name,bit_rate:format=bit_rate,duration",
+        "-of",
+        "json",
+        str(path),
+    ]
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True)
+    except OSError:
+        return None
+    if result.returncode != 0:
+        return None
+    try:
+        probed = json.loads(result.stdout or "{}")
+    except ValueError:
+        return None
+
+    streams = probed.get("streams") or []
+    video = next((s for s in streams if s.get("codec_type") == "video"), None)
+    if not video:
+        return None
+    audio = next((s for s in streams if s.get("codec_type") == "audio"), None)
+    return {
+        "vcodec": video.get("codec_name"),
+        "acodec": audio.get("codec_name") if audio else None,
+        "vbitrate": int_or_none(video.get("bit_rate")) or int_or_none(probed.get("format", {}).get("bit_rate")),
+    }
+
+
+def int_or_none(value):
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def h264_encoder():
+    """The fastest H.264 encoder available. VideoToolbox is hardware-backed and
+    always present on macOS; elsewhere the software encoder is the safe bet,
+    since an nvenc/qsv build only works when the matching GPU is there too."""
+    if sys.platform == "darwin":
+        exe = find_ffmpeg()
+        try:
+            result = subprocess.run([exe, "-v", "error", "-encoders"], capture_output=True, text=True)
+        except OSError:
+            return "libx264"
+        if "h264_videotoolbox" in (result.stdout or ""):
+            return "h264_videotoolbox"
+    return "libx264"
+
+
+def transcode_args(source, target, encoder, media):
+    # `-map 0` keeps every stream and the embedded metadata; only the video
+    # track goes through the encoder, the rest is copied as-is.
+    args = [find_ffmpeg(), "-v", "warning", "-stats", "-y", "-i", str(source), "-map", "0"]
+    args += ["-c:v", encoder, "-pix_fmt", "yuv420p"]
+    if encoder == "libx264":
+        args += ["-crf", "20", "-preset", "veryfast"]
+    else:
+        bitrate = media.get("vbitrate")
+        target_bitrate = max(int(bitrate * H264_BITRATE_HEADROOM), MIN_H264_BITRATE) if bitrate else MIN_H264_BITRATE
+        args += ["-b:v", str(target_bitrate)]
+    if media.get("acodec") in PLAYABLE_ACODECS:
+        args += ["-c:a", "copy"]
+    else:
+        args += ["-c:a", "aac", "-b:a", "192k"]
+    args += ["-c:s", "copy", "-movflags", "+faststart", str(target)]
+    return args
+
+
+def make_playable(path):
+    """Re-encode `path` to H.264 when its video codec is one MP4 players choke on.
+
+    Returns True when the file was converted, False when it was already fine or
+    the conversion did not work out (in which case the download is left alone).
+    """
+    path = Path(path)
+    if not path.is_file():
+        return False
+    media = probe_media(path)
+    if not media or media["vcodec"] in PLAYABLE_VCODECS:
+        return False
+
+    warning(f"{path.name}: {media['vcodec']} in MP4 does not play in QuickTime / Photos.")
+    # A short temp name next to the download: the title can already be near the
+    # file name limit, and os.replace is only atomic within one filesystem.
+    target = path.with_name(f".evo-recode-{os.getpid()}{path.suffix}")
+    encoder = h264_encoder()
+    info(f"Converting to H.264 with [accent]{encoder}[/accent] (keeps the resolution).")
+    result = run_command(transcode_args(path, target, encoder, media), check=False)
+    if result.returncode != 0 and encoder != "libx264":
+        warning(f"{encoder} failed, retrying with libx264.")
+        encoder = "libx264"
+        result = run_command(transcode_args(path, target, encoder, media), check=False)
+    if result.returncode != 0 or not target.is_file():
+        target.unlink(missing_ok=True)
+        warning("Conversion failed. Keeping the original file - play it with VLC or IINA.")
+        return False
+
+    os.replace(target, path)
+    success(f"Converted [accent]{path.name}[/accent] to H.264.")
+    return True
+
+
+def downloaded_paths(manifest):
+    """Files yt-dlp reported writing, deduplicated and in order."""
+    try:
+        lines = Path(manifest).read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return []
+    seen = {}
+    for line in lines:
+        line = line.strip()
+        if line:
+            seen[line] = None
+    return list(seen)
+
+
 def find_js_runtime():
     for name in JS_RUNTIMES:
         path = shutil.which(name)
@@ -282,7 +427,7 @@ def direct_filename(url):
     return name or "download.bin"
 
 
-def build_ytdlp_args(opts, has_ffmpeg):
+def build_ytdlp_args(opts, has_ffmpeg, manifest=None):
     args = []
     runtime, _ = find_js_runtime()
     if runtime and runtime != "deno":
@@ -293,6 +438,8 @@ def build_ytdlp_args(opts, has_ffmpeg):
         return args
 
     args += ["-o", output_template(opts["outdir"], opts["playlist"], opts["name"])]
+    if manifest:
+        args += ["--print-to-file", "after_move:filepath", str(manifest)]
     args += ["--no-playlist"] if not opts["playlist"] else ["--yes-playlist"]
     args += ["-N", str(opts["concurrent"])]
 
@@ -328,6 +475,21 @@ def build_ytdlp_args(opts, has_ffmpeg):
     return args
 
 
+def wants_playable_output(opts, has_ffmpeg):
+    """Whether the H.264 conversion applies to this run.
+
+    Only for MP4, the container people pick precisely because it plays
+    everywhere - `-c auto` / `webm` / `mkv` mean the codec was not the point.
+    """
+    return (
+        has_ffmpeg
+        and not opts["keep_codec"]
+        and not opts["audio_only"]
+        and not opts["list_formats"]
+        and opts["container"] == "mp4"
+    )
+
+
 def report_environment():
     version = ytdlp_version()
     ffmpeg = ffmpeg_version()
@@ -395,18 +557,29 @@ def do_get(urls, opts, assume_yes):
         warning("ffmpeg not found: falling back to single-file streams (lower quality).")
         info("Install it with `evo download install --with-deps` for the best quality.")
 
-    cmd = exe + build_ytdlp_args(opts, has_ffmpeg) + list(media)
+    recoding = wants_playable_output(opts, has_ffmpeg)
+    manifest = Path(tempfile.mkdtemp(prefix="evo-download-")) / "files.txt" if recoding else None
+
+    cmd = exe + build_ytdlp_args(opts, has_ffmpeg, manifest) + list(media)
     if opts["dry_run"]:
         console.print(f"[cmd]$ {escape(' '.join(cmd))}[/cmd]")
         return
 
-    result = run_command(cmd, check=False)
-    if result.returncode != 0:
-        if ytdlp_stale_age() is not None:
-            raise click.ClickException(
-                "yt-dlp failed and the installed build is stale. Run `evo download install`, then try again."
-            )
-        raise click.ClickException("yt-dlp failed. Try `evo download formats <url>` to inspect the source.")
+    try:
+        result = run_command(cmd, check=False)
+        if result.returncode != 0:
+            if ytdlp_stale_age() is not None:
+                raise click.ClickException(
+                    "yt-dlp failed and the installed build is stale. Run `evo download install`, then try again."
+                )
+            raise click.ClickException("yt-dlp failed. Try `evo download formats <url>` to inspect the source.")
+        if manifest:
+            for path in downloaded_paths(manifest):
+                make_playable(path)
+    finally:
+        if manifest:
+            shutil.rmtree(manifest.parent, ignore_errors=True)
+
     if not opts["list_formats"]:
         success(f"Saved to [accent]{outdir}[/accent]")
 
@@ -491,6 +664,11 @@ def get_options(func):
         click.option(
             "--ascii", "ascii_names", is_flag=True, help="Restrict filenames to ASCII (no spaces or diacritics)."
         ),
+        click.option(
+            "--keep-codec",
+            is_flag=True,
+            help="Keep the codec the site served instead of converting VP9 / AV1 to H.264.",
+        ),
         click.option(
             "-N", "--concurrent", type=int, default=4, show_default=True, help="Fragments to download in parallel."
         ),
@@ -524,6 +702,7 @@ def collect_opts(
     name,
     dry_run,
     list_formats=False,
+    keep_codec=False,
 ):
     return {
         "outdir": Path(outdir) if outdir else default_output_dir(),
@@ -545,6 +724,7 @@ def collect_opts(
         "name": name,
         "dry_run": dry_run,
         "list_formats": list_formats,
+        "keep_codec": keep_codec,
     }
 
 
@@ -577,6 +757,7 @@ def get_cmd(
     archive,
     section,
     ascii_names,
+    keep_codec,
     concurrent,
     limit_rate,
     name,
@@ -603,6 +784,7 @@ def get_cmd(
         limit_rate,
         name,
         dry_run,
+        keep_codec=keep_codec,
     )
     do_get(list(urls), opts, assume_yes)
 

{evo_cli-0.20.2 → evo_cli-0.21.0}/evo_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: evo_cli
-Version: 0.20.2
+Version: 0.21.0
 Summary: Evolution CLI - a developer toolbox for setting up dev machines
 Author: maycuatroi
 Project-URL: Homepage, https://github.com/maycuatroi/evo-cli

{evo_cli-0.20.2 → evo_cli-0.21.0}/tests/test_download.py

@@ -1,4 +1,5 @@
 import datetime
+import subprocess
 from pathlib import Path
 
 import pytest
@@ -112,6 +113,130 @@ def test_title_cap_leaves_room_for_the_suffixes_ytdlp_appends():
     assert dl.TITLE_BYTE_LIMIT + len(".f1049104804294604v.mp4.part") < 255
 
 
+def test_build_args_records_what_it_downloaded(opts, tmp_path):
+    args = dl.build_ytdlp_args(opts, has_ffmpeg=True, manifest=tmp_path / "files.txt")
+    assert args[args.index("--print-to-file") + 1] == "after_move:filepath"
+    assert args[args.index("--print-to-file") + 2] == str(tmp_path / "files.txt")
+
+
+def test_build_args_without_manifest_stays_quiet(opts):
+    assert "--print-to-file" not in dl.build_ytdlp_args(opts, has_ffmpeg=True)
+
+
+def test_downloaded_paths_drops_blanks_and_repeats(tmp_path):
+    manifest = tmp_path / "files.txt"
+    manifest.write_text("/a.mp4\n\n/b.mp4\n/a.mp4\n", encoding="utf-8")
+    assert dl.downloaded_paths(manifest) == ["/a.mp4", "/b.mp4"]
+
+
+def test_downloaded_paths_survives_a_missing_manifest(tmp_path):
+    assert dl.downloaded_paths(tmp_path / "nope.txt") == []
+
+
+def test_mp4_downloads_get_the_h264_pass(opts):
+    assert dl.wants_playable_output(opts, has_ffmpeg=True) is True
+
+
+@pytest.mark.parametrize(
+    "key, value",
+    [("keep_codec", True), ("audio_only", True), ("list_formats", True), ("container", "webm")],
+)
+def test_h264_pass_is_skipped_when_it_does_not_apply(opts, key, value):
+    opts[key] = value
+    assert dl.wants_playable_output(opts, has_ffmpeg=True) is False
+
+
+def test_h264_pass_needs_ffmpeg(opts):
+    assert dl.wants_playable_output(opts, has_ffmpeg=False) is False
+
+
+def test_transcode_keeps_a_playable_audio_track(monkeypatch, tmp_path):
+    monkeypatch.setattr(dl, "find_ffmpeg", lambda: "ffmpeg")
+    args = dl.transcode_args(tmp_path / "in.mp4", tmp_path / "out.mp4", "libx264", {"acodec": "aac"})
+    assert args[args.index("-c:v") + 1] == "libx264"
+    assert args[args.index("-c:a") + 1] == "copy"
+    assert "-crf" in args
+
+
+def test_transcode_re_encodes_an_unplayable_audio_track(monkeypatch, tmp_path):
+    monkeypatch.setattr(dl, "find_ffmpeg", lambda: "ffmpeg")
+    args = dl.transcode_args(tmp_path / "in.mp4", tmp_path / "out.mp4", "libx264", {"acodec": "opus"})
+    assert args[args.index("-c:a") + 1] == "aac"
+
+
+def test_hardware_encoder_gets_a_bitrate_instead_of_a_crf(monkeypatch, tmp_path):
+    monkeypatch.setattr(dl, "find_ffmpeg", lambda: "ffmpeg")
+    media = {"acodec": "aac", "vbitrate": 2_000_000}
+    args = dl.transcode_args(tmp_path / "in.mp4", tmp_path / "out.mp4", "h264_videotoolbox", media)
+    # H.264 needs more bits than VP9 for the same picture.
+    assert args[args.index("-b:v") + 1] == str(int(2_000_000 * dl.H264_BITRATE_HEADROOM))
+    assert "-crf" not in args
+
+
+def test_hardware_encoder_falls_back_to_a_floor_bitrate(monkeypatch, tmp_path):
+    monkeypatch.setattr(dl, "find_ffmpeg", lambda: "ffmpeg")
+    args = dl.transcode_args(tmp_path / "in.mp4", tmp_path / "out.mp4", "h264_videotoolbox", {"acodec": "aac"})
+    assert args[args.index("-b:v") + 1] == str(dl.MIN_H264_BITRATE)
+
+
+def test_playable_codec_is_left_alone(monkeypatch, tmp_path):
+    video = tmp_path / "clip.mp4"
+    video.write_bytes(b"data")
+    monkeypatch.setattr(dl, "probe_media", lambda path: {"vcodec": "h264", "acodec": "aac", "vbitrate": 1})
+    assert dl.make_playable(video) is False
+    assert video.read_bytes() == b"data"
+
+
+def test_vp9_is_converted_in_place(monkeypatch, tmp_path):
+    video = tmp_path / "clip.mp4"
+    video.write_bytes(b"vp9 data")
+    monkeypatch.setattr(dl, "probe_media", lambda path: {"vcodec": "vp9", "acodec": "aac", "vbitrate": 1})
+    monkeypatch.setattr(dl, "find_ffmpeg", lambda: "ffmpeg")
+    monkeypatch.setattr(dl, "h264_encoder", lambda: "libx264")
+
+    def fake_ffmpeg(cmd, check=True):
+        Path(cmd[-1]).write_bytes(b"h264 data")
+        return subprocess.CompletedProcess(cmd, 0)
+
+    monkeypatch.setattr(dl, "run_command", fake_ffmpeg)
+    assert dl.make_playable(video) is True
+    assert video.read_bytes() == b"h264 data"
+    assert list(tmp_path.iterdir()) == [video]
+
+
+def test_a_failed_conversion_keeps_the_download(monkeypatch, tmp_path):
+    video = tmp_path / "clip.mp4"
+    video.write_bytes(b"vp9 data")
+    monkeypatch.setattr(dl, "probe_media", lambda path: {"vcodec": "vp9", "acodec": "aac", "vbitrate": 1})
+    monkeypatch.setattr(dl, "find_ffmpeg", lambda: "ffmpeg")
+    monkeypatch.setattr(dl, "h264_encoder", lambda: "libx264")
+    monkeypatch.setattr(dl, "run_command", lambda cmd, check=True: subprocess.CompletedProcess(cmd, 1))
+    assert dl.make_playable(video) is False
+    assert video.read_bytes() == b"vp9 data"
+    assert list(tmp_path.iterdir()) == [video]
+
+
+def test_hardware_encoder_failure_retries_in_software(monkeypatch, tmp_path):
+    video = tmp_path / "clip.mp4"
+    video.write_bytes(b"vp9 data")
+    monkeypatch.setattr(dl, "probe_media", lambda path: {"vcodec": "vp9", "acodec": "aac", "vbitrate": 1})
+    monkeypatch.setattr(dl, "find_ffmpeg", lambda: "ffmpeg")
+    monkeypatch.setattr(dl, "h264_encoder", lambda: "h264_videotoolbox")
+    attempts = []
+
+    def flaky_ffmpeg(cmd, check=True):
+        encoder = cmd[cmd.index("-c:v") + 1]
+        attempts.append(encoder)
+        if encoder == "h264_videotoolbox":
+            return subprocess.CompletedProcess(cmd, 1)
+        Path(cmd[-1]).write_bytes(b"h264 data")
+        return subprocess.CompletedProcess(cmd, 0)
+
+    monkeypatch.setattr(dl, "run_command", flaky_ffmpeg)
+    assert dl.make_playable(video) is True
+    assert attempts == ["h264_videotoolbox", "libx264"]
+
+
 def test_build_args_default(opts):
     args = dl.build_ytdlp_args(opts, has_ffmpeg=True)
     assert "--no-playlist" in args

evo_cli-0.20.2/evo_cli/VERSION

@@ -1 +0,0 @@
-0.20.2