@codebend3r/che 1.0.0

package/bin/video/delete-duplicate-videos.py

@@ -0,0 +1,313 @@
+#!/usr/bin/env python3
+"""🗑️  Delete duplicate MKV/MP4 files under a root directory.
+
+Pipeline:
+
+  1. Parse flags and normalize booleans/strategy (env overrides, then CLI).
+  2. Resolve --path to an absolute directory.
+  3. Walk every .mkv/.mp4 recursively, skipping AppleDouble "._*" sidecars.
+  4. Compute a duplicate group key per file (depends on --strategy).
+  5. Bucket files by that key.
+  6. For each bucket, keep one member (largest file; ties break lexically by
+     path, so the choice is deterministic) and delete the rest.
+
+Usage:
+  delete-duplicate-videos.py --path=/path/to/media [--strategy=MODE]
+                             [--dry-run] [--verbose]
+
+Strategies (--strategy):
+
+  episode   Same directory + identical SxxEyy token (tv-style names). Files
+            without such a token are ignored.
+  filename  Same directory + identical basename - exact filename duplicates.
+  size      Same directory + identical byte size. Fast, but CAN mis-group
+            different videos that coincidentally match size.
+  hash      Globally grouped by SHA-256 (byte-identical copies anywhere under
+            root). Reads every file fully - slow on huge trees.
+  all       Same directory + basename + byte size + SHA-256 must all match.
+            Strong confirmation before delete.
+
+Defaults:
+  --strategy=episode
+
+Security:
+  Defaults to dry-run when invoked by path. The .zshrc wrapper sources it with
+  DRY_RUN=false so interactive use deletes; delete-duplicate-videos-dr previews.
+
+Options:
+  --path=PATH      Required directory to scan
+  --strategy=MODE  episode | filename | size | hash | all
+  --dry-run        Show removals only - no deletes (same as env DRY_RUN=true)
+  --dry-run=BOOL   Explicit true|false (aliases: yes|no, 1|0)
+  --verbose        Extra per-file logging
+  --help, -h       This help
+
+Env:
+  STRATEGY=MODE       Same spelling as --strategy (default episode)
+  DRY_RUN=true|false  Overrides the preview-only default
+
+Examples:
+  delete-duplicate-videos.py --path=./Shows --strategy=filename
+  DRY_RUN=false delete-duplicate-videos.py --path=./Shows --strategy=hash
+"""
+
+from __future__ import annotations
+
+import hashlib
+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,
+    env_bool,
+    format_bytes,
+    info,
+    iter_files,
+    log,
+    note,
+    run_cli,
+    scan_root,
+    warning,
+)
+
+__version__ = "2.2.1"
+
+# Glue multiple logical fields into one key without a separator that could
+# plausibly appear in a directory name.
+KEY_RS = "\x1e"
+
+EPISODE_RE = re.compile(r"[Ss][0-9]{2}[Ee][0-9]{2,3}")
+
+VIDEO_EXTENSIONS = ("mkv", "mp4")
+
+STRATEGY_ALIASES = {
+    "episode": "episode",
+    "tv": "episode",
+    "filename": "filename",
+    "file": "filename",
+    "basename": "filename",
+    "name": "filename",
+    "size": "size",
+    "bytes": "size",
+    "hash": "hash",
+    "checksum": "hash",
+    "sha256": "hash",
+    "digest": "hash",
+    "all": "all",
+    "combined": "all",
+}
+
+# 1 MiB chunks: large enough that syscall overhead is irrelevant, small enough
+# that a 60 GB remux does not have to fit in memory.
+_HASH_CHUNK = 1024 * 1024
+
+
+def normalize_strategy(value: str) -> str:
+    """Collapse the strategy synonyms, or return "" for an unknown value."""
+    return STRATEGY_ALIASES.get(value.strip().lower(), "")
+
+
+def sha256_hex(path: Path) -> str:
+    """SHA-256 of a file, streamed.
+
+    The shell version shelled out to openssl / sha256sum / shasum and probed
+    which one worked. hashlib is in the standard library, so there is no
+    backend to detect and no smoke test to run.
+    """
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        while chunk := handle.read(_HASH_CHUNK):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def group_key(path: Path, strategy: str, *, verbose: bool) -> str | None:
+    """The duplicate-group key for one file, or None to skip it."""
+    directory = str(path.parent)
+    name = path.name
+
+    if strategy == "episode":
+        match = EPISODE_RE.search(name)
+        if match is None:
+            return None  # not TV-shaped; ignored, as in the shell version
+        return f"{directory}{KEY_RS}{match.group(0)}"
+
+    if strategy == "filename":
+        return f"{directory}{KEY_RS}{name}"
+
+    if strategy == "size":
+        try:
+            return f"{directory}{KEY_RS}{path.stat().st_size}"
+        except OSError:
+            warning(f"SKIP: unreadable size: {path}")
+            return None
+
+    if strategy == "hash":
+        if verbose:
+            note(f"HASH: {path}")
+        try:
+            return sha256_hex(path)
+        except OSError:
+            warning(f"SKIP: could not hash: {path}")
+            return None
+
+    if strategy == "all":
+        try:
+            size = path.stat().st_size
+        except OSError:
+            warning(f"SKIP: unreadable size: {path}")
+            return None
+        if verbose:
+            note(f"HASH: {path}")
+        try:
+            digest = sha256_hex(path)
+        except OSError:
+            warning(f"SKIP: could not hash: {path}")
+            return None
+        return f"{directory}{KEY_RS}{name}{KEY_RS}{size}{KEY_RS}{digest}"
+
+    raise ValueError(f"Internal error: unknown strategy {strategy!r}")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser(
+        prog="delete-duplicate-videos",
+        description="🗑️  Delete duplicate MKV/MP4 files under a root directory.",
+        epilog=(
+            "Examples:\n"
+            "  delete-duplicate-videos.py --path=./Shows --strategy=filename\n"
+            "  DRY_RUN=false delete-duplicate-videos.py --path=./Shows --strategy=hash"
+        ),
+    )
+    parser.add_argument("--path", default="", metavar="PATH", help="Directory to scan (required)")
+    parser.add_argument(
+        "--strategy",
+        # `or`, not a get() default: the shell used ${STRATEGY:-episode}, where
+        # an exported-but-empty value also falls back.
+        default=os.environ.get("STRATEGY") or "episode",
+        metavar="MODE",
+        help="episode | filename | size | hash | all (default: episode)",
+    )
+    add_bool_flag(
+        parser,
+        "--dry-run",
+        default=env_bool("DRY_RUN", True),
+        help="Show removals only - no deletes",
+    )
+    add_bool_flag(parser, "--verbose", help="Extra per-file logging")
+
+    info(f"Running command in {Path.cwd()}")
+    args = parser.parse_args(argv)
+
+    strategy = normalize_strategy(args.strategy)
+    if not strategy:
+        warning(f"Invalid --strategy value: {args.strategy}")
+        parser.print_help()
+        return 1
+
+    note(f"Scanning: {args.path}")
+    note(f"Strategy: {strategy}")
+    note(f"Dry run: {str(args.dry_run).lower()}")
+    note(f"Verbose: {str(args.verbose).lower()}")
+    note("----------------------------------------------------")
+
+    if not args.path:
+        warning("Missing required argument: --path")
+        return 1
+
+    # Absolute, with ../ collapsed, so group keys built from the parent
+    # directory are stable regardless of how --path was spelled. Note this also
+    # resolves symlinks mid-path, so a logged path can differ from the one the
+    # user typed; grouping and the choice of keeper are unaffected, since every
+    # key shares the same root prefix.
+    root = scan_root(args.path).resolve()
+
+    if strategy == "size":
+        info("NOTICE: grouping by SIZE can flag unrelated videos with identical byte lengths.")
+    elif strategy in ("hash", "all"):
+        info("NOTICE: hashing reads every scanned file entirely — slow on huge libraries.")
+
+    if args.dry_run:
+        info("Running in dry-run mode — no files will be deleted.")
+    if args.verbose:
+        info("Verbose mode — per-file tracing enabled.")
+
+    scanned = 0
+    groups: dict[str, list[Path]] = {}
+
+    for path in iter_files(root, extensions=VIDEO_EXTENSIONS):
+        scanned += 1
+        if args.verbose:
+            info(f"SCANNING: {path}")
+        key = group_key(path, strategy, verbose=args.verbose)
+        if key is not None:
+            groups.setdefault(key, []).append(path)
+
+    deleted = 0
+    duplicate_groups = 0
+    reclaimed = 0
+
+    for key in sorted(groups):
+        members = groups[key]
+        if len(members) <= 1:
+            continue
+
+        sized: list[tuple[int, Path]] = []
+        for path in members:
+            if not path.is_file():
+                continue  # a symlink to a missing target, or deleted mid-run
+            try:
+                sized.append((path.stat().st_size, path))
+            except OSError:
+                warning(f"SKIP: unreadable size: {path}")
+
+        if len(sized) <= 1:
+            continue
+
+        # Largest first; same-size ties break alphabetically by path, so the
+        # keeper is deterministic across runs and machines.
+        sized.sort(key=lambda item: (-item[0], str(item[1])))
+        duplicate_groups += 1
+
+        keep_size, keep_path = sized[0]
+        if args.verbose:
+            info(f"KEEPING: {keep_path} ({format_bytes(keep_size)})")
+
+        for size, path in sized[1:]:
+            human = format_bytes(size)
+            if args.dry_run:
+                deleted += 1
+                reclaimed += size
+                warning(f"[DRY-RUN] ❌ Would delete: {path} ({human})")
+                continue
+
+            warning(f"❌ Deleting: {path} ({human})")
+            try:
+                path.unlink()
+            except OSError as exc:
+                warning(f"  ✗ Failed to delete {path}: {exc}")
+                continue
+            deleted += 1
+            reclaimed += size
+
+    if args.dry_run:
+        log(f"Total files that would be deleted: {deleted}")
+    else:
+        log(f"Total files deleted: {deleted}")
+
+    log(
+        f"Duplicate groups merged ({strategy}): {duplicate_groups} "
+        f"(~{format_bytes(reclaimed)} freed)"
+    )
+    log(f"Total files scanned: {scanned}")
+    log("Scanning complete.")
+    return 0
+
+
+if __name__ == "__main__":
+    run_cli(main)

package/bin/video/detect-green-magenta-videos.py

@@ -0,0 +1,268 @@
+#!/usr/bin/env python3
+"""
+Detect videos with the "green and purple/magenta" decoding artifact.
+
+This artifact appears when chroma planes (U/V) are corrupted, swapped,
+or mishandled by the decoder. The result is an image dominated by
+green and magenta hues with almost no other colors -- unwatchable.
+
+Usage:
+    python detect_green_magenta.py path/to/video.mp4
+    python detect_green_magenta.py /path/to/folder --verbose
+    python detect_green_magenta.py vids/ --samples 40 --threshold 0.7
+
+Requires: opencv-python, numpy
+    pip install opencv-python numpy
+
+This is the only script in the repo that needs third-party packages. Rather
+than a separate bash launcher, it re-execs itself under a dedicated venv when
+cv2 is missing from the interpreter it was started with - Homebrew Python is
+PEP 668 "externally managed" and refuses plain pip installs, so the packages
+have to live somewhere isolated. Override the location with $DETECT_GM_PYTHON.
+"""
+
+import argparse
+import os
+import sys
+from pathlib import Path
+from typing import NoReturn
+
+VENV_PYTHON = Path(
+    os.environ.get("DETECT_GM_PYTHON", Path.home() / ".venvs" / "green-magenta" / "bin" / "python")
+)
+
+
+def _reexec_under_venv() -> NoReturn:
+    """Hand off to the venv interpreter when cv2 is not importable here.
+
+    ``_DETECT_GM_REEXEC`` guards against a loop if the venv itself is missing
+    the packages: the second run reaches the error path instead of re-execing
+    forever.
+    """
+    if os.environ.get("_DETECT_GM_REEXEC"):
+        print(
+            f"❌ {VENV_PYTHON} is missing cv2 or numpy. Run:\n"
+            f"  {VENV_PYTHON} -m pip install opencv-python numpy",
+            file=sys.stderr,
+        )
+        raise SystemExit(1)
+
+    if not os.access(VENV_PYTHON, os.X_OK):
+        print(
+            f"❌ Python venv not found: {VENV_PYTHON}\n"
+            "Bootstrap with:\n"
+            "  python3 -m venv $HOME/.venvs/green-magenta\n"
+            "  $HOME/.venvs/green-magenta/bin/pip install opencv-python numpy",
+            file=sys.stderr,
+        )
+        raise SystemExit(1)
+
+    os.environ["_DETECT_GM_REEXEC"] = "1"
+    os.execv(  # noqa: S606 - absolute interpreter path, no shell involved
+        str(VENV_PYTHON), [str(VENV_PYTHON), str(Path(__file__).resolve()), *sys.argv[1:]]
+    )
+
+
+# --help and bare usage must work on a machine with no venv at all, so the
+# import is skipped entirely for those. The bash launcher checked --help before
+# it checked for the venv, and asking someone to bootstrap OpenCV just to read
+# the usage text is a poor answer to "how do I use this?".
+_WANTS_HELP = len(sys.argv) == 1 or any(a in ("-h", "--help") for a in sys.argv[1:])
+
+if not _WANTS_HELP:
+    try:
+        # ImportError, not ModuleNotFoundError: a half-installed or
+        # ABI-mismatched OpenCV - the common opencv-on-macOS failure - raises
+        # plain ImportError, which would otherwise escape as a raw traceback.
+        import cv2
+        import numpy as np
+    except ImportError:
+        _reexec_under_venv()
+
+VIDEO_EXTS = {
+    ".mp4",
+    ".mkv",
+    ".avi",
+    ".mov",
+    ".webm",
+    ".m4v",
+    ".flv",
+    ".wmv",
+    ".mpg",
+    ".mpeg",
+    ".ts",
+    ".m2ts",
+}
+
+
+def analyze_frame(frame):
+    """
+    Return (green_magenta_ratio, mean_saturation) for one BGR frame.
+
+    green_magenta_ratio = fraction of saturated pixels whose hue falls
+    in the green or magenta bands. In a healthy video this is usually
+    well under 0.5; in a broken green/magenta video it sits near 1.0.
+    """
+    hsv = cv2.cvtColor(frame, cv2.COLOR_BGR2HSV)
+    h = hsv[..., 0]  # OpenCV hue range: 0-179 (half of 0-360 degrees)
+    s = hsv[..., 1]  # saturation: 0-255
+
+    # Only look at pixels with real color. Gray/near-gray pixels carry
+    # no useful hue information and shouldn't sway the verdict.
+    sat_mask = s > 40
+    if sat_mask.sum() < 100:
+        # Frame is essentially grayscale -- can't judge it.
+        return None, float(s.mean())
+
+    hues = h[sat_mask]
+
+    # Green band: ~70-170 deg  -> OpenCV 35-85
+    # Magenta band: ~260-340 deg -> OpenCV 130-170
+    green_mask = (hues >= 35) & (hues <= 85)
+    magenta_mask = (hues >= 130) & (hues <= 170)
+
+    ratio = (green_mask.sum() + magenta_mask.sum()) / hues.size
+    return float(ratio), float(s.mean())
+
+
+def analyze_video(path, sample_count=20, threshold=0.65):
+    cap = cv2.VideoCapture(str(path))
+    if not cap.isOpened():
+        return {"path": str(path), "error": "could not open"}
+
+    total = int(cap.get(cv2.CAP_PROP_FRAME_COUNT)) or 0
+
+    if total > sample_count * 2:
+        # Sample evenly, skipping the first/last 5% (intros, credits, black frames)
+        start = int(total * 0.05)
+        end = int(total * 0.95)
+        positions = np.linspace(start, end, sample_count, dtype=int)
+    else:
+        positions = None  # short or unknown-length file -- just read sequentially
+
+    ratios, sats = [], []
+
+    if positions is None:
+        for _ in range(sample_count):
+            ok, frame = cap.read()
+            if not ok:
+                break
+            r, s = analyze_frame(frame)
+            if r is not None:
+                ratios.append(r)
+            sats.append(s)
+    else:
+        for pos in positions:
+            cap.set(cv2.CAP_PROP_POS_FRAMES, int(pos))
+            ok, frame = cap.read()
+            if not ok:
+                continue
+            r, s = analyze_frame(frame)
+            if r is not None:
+                ratios.append(r)
+            sats.append(s)
+
+    cap.release()
+
+    if not ratios:
+        return {"path": str(path), "error": "no usable (color) frames decoded"}
+
+    avg_ratio = float(np.mean(ratios))
+    avg_sat = float(np.mean(sats))
+
+    # Flag if the green/magenta dominance is high AND the frames are
+    # actually saturated (otherwise we'd flag intentionally desaturated
+    # cinematography that happens to lean cool/warm).
+    flagged = avg_ratio >= threshold and avg_sat > 35
+
+    return {
+        "path": str(path),
+        "frames_sampled": len(ratios),
+        "green_magenta_ratio": round(avg_ratio, 3),
+        "avg_saturation": round(avg_sat, 1),
+        "flagged": flagged,
+    }
+
+
+def iter_videos(paths):
+    """Yield every video under the given files and directories.
+
+    Streams per directory rather than materialising the whole tree, and skips
+    macOS ``._*`` sidecars the way the rest of the repo does.
+    """
+    for p in paths:
+        p = Path(p)
+        if p.is_dir():
+            for dirpath, dirnames, filenames in os.walk(p, followlinks=False):
+                dirnames.sort()
+                for name in sorted(filenames):
+                    if name.startswith("._"):
+                        continue
+                    f = Path(dirpath) / name
+                    if f.suffix.lower() in VIDEO_EXTS and not f.is_symlink():
+                        yield f
+        elif p.is_file():
+            yield p
+        else:
+            print(f"[skip] {p}: not a file or directory", file=sys.stderr)
+
+
+def main():
+    ap = argparse.ArgumentParser(
+        description="Detect videos with the green/magenta chroma artifact."
+    )
+    ap.add_argument(
+        "paths",
+        nargs="+",
+        help="Video files or directories to scan (directories are searched recursively)",
+    )
+    ap.add_argument(
+        "--samples", type=int, default=20, help="Frames to sample per video (default: 20)"
+    )
+    ap.add_argument(
+        "--threshold",
+        type=float,
+        default=0.65,
+        help="Fraction of saturated pixels that must be green or magenta to flag (default: 0.65)",
+    )
+    ap.add_argument(
+        "--verbose", "-v", action="store_true", help="Print every video, not just flagged ones"
+    )
+    args = ap.parse_args()
+
+    # The bash launcher printed these before exec'ing, and the rest of the repo
+    # opens the same way. After parse_args, so --help stays clean.
+    print(f"Running command in {Path.cwd()}")
+    print(f"Scanning: {' '.join(args.paths)}")
+    print("----------------------------------------------------")
+
+    bad = []
+    any_seen = False
+    for v in iter_videos(args.paths):
+        any_seen = True
+        res = analyze_video(v, sample_count=args.samples, threshold=args.threshold)
+        if "error" in res:
+            print(f"[skip] {v}: {res['error']}", file=sys.stderr)
+            continue
+        tag = "BAD " if res["flagged"] else "ok  "
+        line = (
+            f"{tag} ratio={res['green_magenta_ratio']:.2f} sat={res['avg_saturation']:>5.1f}  {v}"
+        )
+        if res["flagged"] or args.verbose:
+            print(line)
+        if res["flagged"]:
+            bad.append(str(v))
+
+    if not any_seen:
+        print("No video files found.", file=sys.stderr)
+        sys.exit(2)
+
+    if bad:
+        print(f"\n{len(bad)} video(s) flagged as green/magenta-tinted:", file=sys.stderr)
+        for b in bad:
+            print(f"  {b}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/bin/video/find-movie-by-year.py

@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+"""🎞️  Find movie folders whose name ends with a given year, e.g. "Alien (1979)".
+
+Usage:
+  find-movie-by-year.py --year=YYYY [--path=/path/to/search]
+
+Options:
+  --year=YYYY   Year to match. Glob metacharacters work, so --year='2*'
+                matches any year starting with 2 (required)
+  --path=DIR    Directory to search (default: .)
+  --help        Show help
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from fnmatch import fnmatchcase
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from utils import build_parser, info, run_cli, scan_root, warning
+
+__version__ = "3.0.0"
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser(
+        prog="find-movie-by-year",
+        description='🎞️  Find movie folders whose name ends with "(YYYY)".',
+        epilog="Example: find-movie-by-year.py --year=2025 --path=/movies",
+    )
+    parser.add_argument("--year", default="", metavar="YYYY", help="Year to match (required)")
+    parser.add_argument(
+        "--path", default=".", metavar="DIR", help="Directory to search (default: .)"
+    )
+
+    info(f"Running command in {Path.cwd()}")
+    args = parser.parse_args(argv)
+
+    if not args.year:
+        warning("❌ --year is required")
+        return 1
+
+    root = scan_root(args.path)
+
+    # `find -type d -iname "*(YYYY)"` - a folder name ENDING in the
+    # parenthesised year, matched case-insensitively. fnmatch rather than a
+    # plain endswith so glob metacharacters in --year still work, as they did
+    # when the value was interpolated straight into the -iname pattern.
+    pattern = f"*({args.year.lower()})"
+
+    def emit(path: Path) -> None:
+        # `find <dir>` prints paths prefixed with the start directory exactly as
+        # the user spelled it, including a leading "./" for the default. pathlib
+        # collapses "." away, so join the raw string instead - anything piping
+        # this into xargs depends on that prefix.
+        if path == root:
+            print(args.path, flush=True)
+        else:
+            # os.path.join, not Path: Path would normalise a leading './'
+            # away, and that prefix is exactly what has to survive.
+            print(os.path.join(args.path, str(path.relative_to(root))), flush=True)  # noqa: PTH118
+
+    # `find` includes the start directory in its results.
+    if fnmatchcase(root.name.lower(), pattern):
+        emit(root)
+
+    # Results are sorted for reproducibility; `find` emitted readdir order.
+    for dirpath, dirnames, _ in os.walk(root, followlinks=False):
+        dirnames.sort()
+        for name in dirnames:
+            child = Path(dirpath) / name
+            if child.is_symlink():
+                continue
+            if fnmatchcase(name.lower(), pattern):
+                emit(child)
+
+    return 0
+
+
+if __name__ == "__main__":
+    run_cli(main)