@codebend3r/che 1.0.0

package/bin/video/find-video-mkv-issues.py

@@ -0,0 +1,242 @@
+#!/usr/bin/env python3
+"""🎬 Scan MKV files and estimate Plex direct-play compatibility.
+
+Usage:
+  find-video-mkv-issues.py --path=/media/path [--recursive]
+
+Options:
+  --path=PATH     Required path to scan
+  --recursive     Recursively scan subfolders (default: false)
+  --help          Show help
+
+Examples:
+  find-video-mkv-issues.py --path=./Movies
+  find-video-mkv-issues.py --path=/mnt/media --recursive
+
+Requires ffprobe. The shell version also required `find` and `bc`; neither is
+needed now.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from utils import (
+    add_bool_flag,
+    build_parser,
+    ffprobe_entries,
+    format_bytes,
+    info,
+    iter_files,
+    note,
+    require_binary,
+    run,
+    run_cli,
+    scan_root,
+    success,
+    warning,
+)
+
+__version__ = "2.1.0"
+
+# (score penalty, note). An empty note means "penalise silently", matching the
+# shell version, which docked a point for ac3/eac3 without explaining why.
+VIDEO_PENALTIES: dict[str, tuple[int, str]] = {
+    "h264": (0, ""),
+    "hevc": (1, "HEVC may transcode on older clients"),
+    "h265": (1, "HEVC may transcode on older clients"),
+    "vp9": (3, "VP9 support inconsistent"),
+    "av1": (5, "AV1 unsupported on many Plex devices"),
+    "vc1": (7, "Legacy video codec"),
+    "wmv3": (7, "Legacy video codec"),
+    "mpeg2video": (5, "MPEG2 commonly transcoded"),
+}
+VIDEO_DEFAULT = (8, "Unknown or niche video codec")
+
+AUDIO_PENALTIES: dict[str, tuple[int, str]] = {
+    "aac": (0, ""),
+    "ac3": (1, ""),
+    "eac3": (1, ""),
+    "dts": (3, "DTS unsupported on many TVs/mobile devices"),
+    "truehd": (5, "TrueHD frequently transcoded"),
+    "flac": (3, "FLAC audio may transcode"),
+    "mp2": (5, "MP2 audio uncommon"),
+}
+AUDIO_DEFAULT = (4, "Unknown or niche audio codec")
+
+SUBTITLE_PENALTIES: dict[str, tuple[int, str]] = {
+    "pgs": (2, "PGS subtitles may force transcoding"),
+    "hdmv_pgs_subtitle": (2, "PGS subtitles may force transcoding"),
+    "dvd_subtitle": (2, "Image subtitles may transcode"),
+}
+
+
+def rate_video(
+    video_codec: str,
+    audio_codec: str,
+    subtitle_codec: str,
+    width: int,
+    bitrate: int,
+) -> tuple[int, str]:
+    """Score a file 0-10 for Plex direct play, with the reasons for the deductions."""
+    score = 10
+    reasons: list[str] = []
+
+    for table, default, codec in (
+        (VIDEO_PENALTIES, VIDEO_DEFAULT, video_codec),
+        (AUDIO_PENALTIES, AUDIO_DEFAULT, audio_codec),
+        (SUBTITLE_PENALTIES, (0, ""), subtitle_codec),
+    ):
+        penalty, reason = table.get(codec, default)
+        score -= penalty
+        if reason:
+            reasons.append(reason)
+
+    if width >= 3840:
+        score -= 1
+        reasons.append("4K playback may struggle on weaker devices")
+
+    mbps = bitrate // 1_000_000
+    if mbps > 60:
+        score -= 2
+        reasons.append("Very high bitrate")
+    elif mbps > 30:
+        score -= 1
+        reasons.append("High bitrate")
+
+    score = max(0, min(10, score))
+    # ";" with no space: the shell version's `IFS='; '; echo "${reasons[*]}"`
+    # joins on the FIRST character of IFS only.
+    return score, ";".join(reasons) if reasons else "Excellent Plex compatibility"
+
+
+def as_int(value: str) -> int:
+    """ffprobe prints 'N/A' for absent fields; treat anything non-numeric as 0."""
+    return int(value) if value.isdigit() else 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser(
+        prog="find-video-mkv-issues",
+        description="🎬 Scan MKV files and estimate Plex direct-play compatibility.",
+        epilog=(
+            "Examples:\n"
+            "  find-video-mkv-issues.py --path=./Movies\n"
+            "  find-video-mkv-issues.py --path=/mnt/media --recursive"
+        ),
+    )
+    parser.add_argument("--path", default="", metavar="PATH", help="Required path to scan")
+    add_bool_flag(parser, "--recursive", help="Recursively scan subfolders (default: false)")
+
+    info(f"Running command in {Path.cwd()}")
+    args = parser.parse_args(argv)
+
+    require_binary("ffprobe", hint="Install FFmpeg: brew install ffmpeg")
+
+    if not args.path:
+        warning("--path is required")
+        parser.print_help()
+        return 1
+
+    root = scan_root(args.path)
+
+    note(f"Scanning: {args.path}")
+    note(f"Recursive: {str(args.recursive).lower()}")
+    note("----------------------------------------------------")
+
+    total = excellent = good = poor = bad = 0
+
+    # macOS ._ sidecars are skipped: they are never real media, and ffprobing
+    # each one would waste a subprocess per file on a NAS scan. The shell
+    # version probed them, failed, and counted each one as Bad - so Total and
+    # Bad both read lower here on a library that has them.
+    for path in iter_files(root, extensions=["mkv"], recursive=args.recursive):
+        total += 1
+
+        note("Checking:")
+        print(f"  {path}", flush=True)
+
+        readable = run(["ffprobe", "-v", "error", str(path)], check=False, capture=True)
+        if readable.returncode != 0:
+            warning("  Corrupt or unreadable file")
+            print(flush=True)
+            bad += 1
+            continue
+
+        video_codec = (
+            ffprobe_entries(
+                path, "stream=codec_name", stream="v:0", fmt="default=noprint_wrappers=1:nokey=1"
+            )
+            or "unknown"
+        )
+        audio_codec = (
+            ffprobe_entries(
+                path, "stream=codec_name", stream="a:0", fmt="default=noprint_wrappers=1:nokey=1"
+            )
+            or "unknown"
+        )
+        subtitle_codec = (
+            ffprobe_entries(
+                path, "stream=codec_name", stream="s:0", fmt="default=noprint_wrappers=1:nokey=1"
+            )
+            or "none"
+        )
+        width_raw = ffprobe_entries(
+            path, "stream=width", stream="v:0", fmt="default=noprint_wrappers=1:nokey=1"
+        )
+        bitrate_raw = ffprobe_entries(
+            path, "format=bit_rate", fmt="default=noprint_wrappers=1:nokey=1"
+        )
+        width = as_int(width_raw)
+        bitrate = as_int(bitrate_raw)
+
+        try:
+            filesize = path.stat().st_size
+        except OSError:
+            filesize = 0
+
+        score, notes = rate_video(video_codec, audio_codec, subtitle_codec, width, bitrate)
+
+        print(f"  Size      : {format_bytes(filesize)}", flush=True)
+        print(f"  Video     : {video_codec}", flush=True)
+        print(f"  Audio     : {audio_codec}", flush=True)
+        print(f"  Subtitles : {subtitle_codec}", flush=True)
+        # `is not None` rather than truthiness: the shell version gated on the
+        # value being numeric, so a literal 0 still printed its line.
+        if width_raw.isdigit():
+            print(f"  Resolution: {width}px", flush=True)
+        if bitrate_raw.isdigit():
+            print(f"  Bitrate   : {bitrate // 1_000_000} Mbps", flush=True)
+
+        if score >= 9:
+            success(f"  Plex Score: {score}/10")
+            excellent += 1
+        elif score >= 7:
+            info(f"  Plex Score: {score}/10")
+            good += 1
+        elif score >= 4:
+            note(f"  Plex Score: {score}/10")
+            poor += 1
+        else:
+            warning(f"  Plex Score: {score}/10")
+            bad += 1
+
+        print(f"  Notes     : {notes}", flush=True)
+        print(flush=True)
+
+    note("----------------------------------------------------")
+    success("Scan complete")
+    print(flush=True)
+    print(f"Total Files : {total}", flush=True)
+    print(f"Excellent   : {excellent}", flush=True)
+    print(f"Good        : {good}", flush=True)
+    print(f"Poor        : {poor}", flush=True)
+    print(f"Bad         : {bad}", flush=True)
+    return 0
+
+
+if __name__ == "__main__":
+    run_cli(main)

package/bin/video/fix-codecs.py

@@ -0,0 +1,209 @@
+#!/usr/bin/env python3
+"""🔧 Re-encode media to h265/aac mp4 so it Direct Plays.
+
+Usage:
+  fix-codecs.py --path=/path/to/media [--delete-original] [--dry-run]
+
+Options:
+  --path=DIR           Directory to scan (required)
+  --delete-original    Delete each source file after a successful convert
+  --dry-run            Print what would be converted, change nothing
+  --help               Show help
+
+Defaults: --delete-original=false, --dry-run=true
+
+Env:
+  DRY_RUN=false        Opt out of the preview-only default
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from utils import (
+    add_bool_flag,
+    build_parser,
+    env_bool,
+    info,
+    iter_files,
+    log,
+    note,
+    require_binary,
+    run,
+    run_cli,
+    scan_root,
+    success,
+    warning,
+)
+
+__version__ = "3.0.0"
+
+SCAN_EXTENSIONS = ("mp4", "mkv", "mov", "avi")
+
+FFMPEG_ARGS = (
+    "-map",
+    "0:v:0",
+    "-map",
+    "0:a:0",
+    "-map",
+    "0:s:0?",
+    "-c:v",
+    "libx265",
+    "-preset",
+    "slow",
+    "-crf",
+    "22",
+    "-c:a",
+    "aac",
+    "-b:a",
+    "384k",
+    "-c:s",
+    "mov_text",
+    "-movflags",
+    "+faststart",
+    "-max_muxing_queue_size",
+    "9999",
+)
+
+
+def encode(source: Path, output: Path) -> bool:
+    """Encode ``source`` to ``output``. True on success.
+
+    Written to a unique temp sibling and moved into place only on success, so
+    a failed run can never delete anything but its own partial output. The
+    shell version wrote straight to the final name; a naive port that cleaned
+    up ``output`` on failure would delete a *good* file produced earlier in the
+    same run whenever two sources share a stem (``Show.avi`` + ``Show.mkv``
+    both target ``Show_fixed.mp4``, and the second one failing is routine -
+    ``-map 0:a:0`` fails on any file with no audio track).
+    """
+    temp = output.with_name(f".{output.name}.{os.getpid()}.part")
+
+    completed = run(
+        [
+            "ffmpeg",
+            # -nostdin so ffmpeg cannot put an interactive terminal into raw
+            # mode. DEVNULL as well, so the guarantee does not rely on the flag.
+            "-nostdin",
+            # -y: the target is our own temp file, so overwriting a leftover
+            # from a killed run is correct. Without it ffmpeg silently refuses
+            # and, on some versions, still exits 0 - a false success.
+            "-y",
+            "-i",
+            str(source),
+            *FFMPEG_ARGS,
+            str(temp),
+        ],
+        check=False,
+        stdin=subprocess.DEVNULL,
+    )
+
+    if completed.returncode != 0 or not temp.exists() or temp.stat().st_size == 0:
+        temp.unlink(missing_ok=True)
+        return False
+
+    temp.replace(output)
+    return True
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser(
+        prog="fix-codecs",
+        description="🔧 Re-encode media to h265/aac mp4 so it Direct Plays.",
+    )
+    parser.add_argument("--path", default="", metavar="DIR", help="Directory to scan (required)")
+    add_bool_flag(
+        parser,
+        "--delete-original",
+        dest="delete_original",
+        help="Delete each source file after a successful convert",
+    )
+    add_bool_flag(
+        parser,
+        "--dry-run",
+        default=env_bool("DRY_RUN", True),
+        help="Print what would be converted, change nothing",
+    )
+
+    info(f"Running command in {Path.cwd()}")
+    args = parser.parse_args(argv)
+
+    if not args.path:
+        warning("Error: You must provide a path with --path=")
+        return 1
+
+    # Binary check before the path check, matching the shell version's order,
+    # so a missing ffmpeg is reported even when the path is also wrong.
+    require_binary("ffmpeg", hint="Install FFmpeg first.")
+
+    root = scan_root(args.path)
+
+    note(f"Scanning: {args.path}")
+    note(f"Delete original after conversion: {str(args.delete_original).lower()}")
+    note(f"Dry run: {str(args.dry_run).lower()}")
+    note("----------------------------------------------------")
+
+    converted = 0
+    failed = 0
+
+    for path in iter_files(root, extensions=SCAN_EXTENSIONS):
+        # Don't re-encode our own output on a second run. Announced rather than
+        # silent, because scene "PROPER/FIXED" repacks legitimately end in
+        # _fixed and would otherwise vanish from the listing with no trace.
+        if path.stem.endswith("_fixed"):
+            info(f"⏭️  Skipping (already _fixed): {path}")
+            continue
+
+        output = path.with_name(f"{path.stem}_fixed.mp4")
+
+        if args.dry_run:
+            info(f"[DRY RUN] Would re-encode: {path} -> {output}")
+            if args.delete_original:
+                info(f"[DRY RUN] Would delete original: {path}")
+            continue
+
+        # Never silently replace an existing conversion; the user may have
+        # produced it deliberately, and there is no way to tell it apart from
+        # one this run just made for a different same-stem source.
+        if output.exists():
+            warning(f"⏭️  Skipping (output already exists): {output}")
+            continue
+
+        log(f"Processing: {path}")
+
+        if not encode(path, output):
+            warning(f"❌ ffmpeg failed for: {path}")
+            failed += 1
+            continue
+
+        log(f"✅ Converted to: {output}")
+        converted += 1
+
+        if args.delete_original:
+            try:
+                path.unlink()
+            except OSError as exc:
+                warning(f"  ✗ Could not delete {path}: {exc}")
+                continue
+            warning(f"🗑 Deleted original: {path}")
+
+    if args.dry_run:
+        log("💡 Dry run complete. Nothing was actually changed.")
+        return 0
+
+    # Summary and the non-zero exit on failure are both new; the shell version
+    # printed nothing and always exited 0 from the loop.
+    success(f"✅ Converted: {converted}")
+    if failed:
+        warning(f"❌ Failed:    {failed}")
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    run_cli(main)

package/bin/video/largest-tv-shows.py

@@ -0,0 +1,175 @@
+#!/usr/bin/env python3
+"""📺 Rank TV show folders in a library by total size on disk.
+
+A TV show folder is any folder with at least one direct child folder named
+``Season <N>``.
+
+Usage:
+  largest-tv-shows.py --path=/path/to/tv [--limit=20] [--full-path] [--debug]
+
+Options:
+  --path=DIR     TV library root (required)
+  --limit=N      How many shows to list (default: 20)
+  --full-path    Print the whole path instead of just the show name
+  --debug        Print traversal detail
+  --help         Show help
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from utils import (
+    add_bool_flag,
+    build_parser,
+    format_bytes,
+    info,
+    note,
+    run_cli,
+    scan_root,
+    warning,
+)
+
+__version__ = "3.0.0"
+
+# `^Season[[:space:]]+[0-9]+$` in the shell version. \Z rather than $ because $
+# also matches before a trailing newline, and an explicit [ \t] rather than \s
+# because Python's \s and \d are Unicode-aware - a non-ASCII digit would
+# otherwise match where the shell version's POSIX classes did not.
+SEASON_RE = re.compile(r"Season[ \t]+[0-9]+\Z")
+
+_NON_NEGATIVE_INT = re.compile(r"[0-9]+")
+
+
+def is_tv_show_folder(path: Path, *, debug: bool) -> bool:
+    """True when ``path`` has a direct child folder named ``Season <N>``."""
+    if debug:
+        note(f"[DEBUG] Checking folder: {path}")
+    try:
+        for child in path.iterdir():
+            # find -type d does not match a symlink; following one here would
+            # report a show whose season folder lives elsewhere, and then size
+            # it at zero because the walk below refuses to descend.
+            if child.is_symlink() or not child.is_dir():
+                continue
+            if debug:
+                note(f"[DEBUG]   Found child folder: {child.name}")
+            if SEASON_RE.fullmatch(child.name):
+                if debug:
+                    note(f"[DEBUG]   Matched season folder in: {path}")
+                return True
+    except OSError:
+        return False
+    if debug:
+        note(f"[DEBUG]   No season folders found in: {path}")
+    return False
+
+
+def folder_size(path: Path, seen: set[tuple[int, int]]) -> int:
+    """Disk usage under ``path``, matching ``du -sk`` closely enough to rank by.
+
+    ``st_blocks * 512`` is ALLOCATED size, which is what ``du`` reports - not
+    ``st_size``, which is the apparent size. The difference is not cosmetic
+    here: a sparse preallocated download reads as its full final size, and a
+    library of many small files reads far under its real footprint.
+
+    ``seen`` collects inode identity so a hard-linked file is counted once,
+    again matching ``du``. Sonarr and Radarr hardlink into the library while
+    seeding, so without this a show holding both copies would double. The set
+    is per-show, because the shell version ran one ``du -sk`` per show and each
+    invocation de-duplicates only within its own tree.
+    """
+    total = 0
+    for dirpath, _, filenames in os.walk(path, followlinks=False):
+        for name in filenames:
+            try:
+                stat = (Path(dirpath) / name).lstat()
+            except OSError:
+                continue
+            if stat.st_nlink > 1:
+                key = (stat.st_dev, stat.st_ino)
+                if key in seen:
+                    continue
+                seen.add(key)
+            total += stat.st_blocks * 512
+    return total
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser(
+        prog="largest-tv-shows",
+        description="📺 Rank TV show folders in a library by total size on disk.",
+    )
+    parser.add_argument("--path", default="", metavar="DIR", help="TV library root (required)")
+    # Kept as a string so "+5" is rejected the way the shell version's
+    # ^[0-9]+$ test rejected it, rather than silently accepted by int().
+    parser.add_argument("--limit", default="20", metavar="N", help="How many to list")
+    add_bool_flag(parser, "--full-path", dest="full_path", help="Print the whole path")
+    add_bool_flag(parser, "--debug", help="Print traversal detail")
+
+    info(f"Running command in {Path.cwd()}")
+    args = parser.parse_args(argv)
+
+    note(f"Searching in: {args.path}")
+    note(f"Limit: {args.limit}")
+    note(f"Show full path: {str(args.full_path).lower()}")
+    note(f"Debug: {str(args.debug).lower()}")
+
+    if not args.path:
+        info(
+            "📋 Usage: largest-tv-shows.py --path=/path/to/tv [--limit=20] [--full-path] [--debug]"
+        )
+        return 1
+
+    root = scan_root(args.path)
+
+    if not _NON_NEGATIVE_INT.fullmatch(args.limit) or int(args.limit) < 1:
+        warning("Error: --limit must be a positive integer")
+        return 1
+    limit = int(args.limit)
+
+    note("Scanning for TV show folders...")
+
+    shows: list[tuple[int, str, Path]] = []
+
+    # Nested show folders are listed too (a "Doctor Who Confidential" inside
+    # "Doctor Who" is its own row), matching the shell version. Its bytes still
+    # count toward the parent as well - that is how `du -s` on the parent works.
+    for dirpath, dirnames, _ in os.walk(root, followlinks=False):
+        dirnames.sort()
+        directory = Path(dirpath)
+        if args.debug:
+            note(f"[DEBUG] Scanning candidate: {directory}")
+        if not is_tv_show_folder(directory, debug=args.debug):
+            continue
+        size = folder_size(directory, set())
+        shows.append((size, directory.name, directory))
+        if args.debug:
+            note(f"[DEBUG] Detected TV show folder: {directory.name} | Size: {size}")
+
+    info(f"Detected {len(shows)} TV show folder(s)")
+
+    if not shows:
+        warning("No TV show folders found.")
+        return 0
+
+    # `sort -rn` reverses the whole comparison, including its last-resort
+    # tiebreak on the full line - so equal-sized shows come out in DESCENDING
+    # name order. Reversing both key fields reproduces that.
+    shows.sort(key=lambda item: (item[0], item[1]), reverse=True)
+
+    note(f"Top {limit} largest TV show folders:")
+    for size, name, path in shows[:limit]:
+        label = str(path) if args.full_path else name
+        print(f"{format_bytes(size):<12} {label}", flush=True)
+
+    return 0
+
+
+if __name__ == "__main__":
+    run_cli(main)