video

#!/usr/bin/env python3
"""
video - unified video tool backed by ffmpeg

Subcommands:
  catalog    [-o OUTPUT] DIR
                               scan a directory tree and write an HTML report
  clamp      [-s START] [-e END] [-o OUTPUT] FILE
                               cut to a time range; start and end are optional
                               (omit -s to start from the beginning, omit -e to
                               go to the end of the video)
  concat     [-o OUTPUT] FILE...
                               join videos of the same format and resolution
  convert    [-f FORMAT] [-o OUTPUT] FILE
                               transcode to a target format (default: H.264/AAC MP4)
  formats    [--all]           explain supported container formats and codecs,
                               check availability in the installed ffmpeg,
                               and show current config defaults
  info       [--json] FILE     print detailed file, container and stream info
                               (codec, profile, resolution, aspect ratio, fps,
                               colour space, bit depth, bitrate, channels,
                               tags, and more; --json for raw ffprobe output)
  normalise  [-n] [-l N] [-f] DIR
                               batch-normalise a directory tree to a web-friendly
                               format (H.264/AAC MP4 at 720p); deinterlaces CRT
                               footage and upscales low-res content via lanczos;
                               -n dry-run: writes a full HTML assessment report
                               (green/red per criterion) without converting;
                               -l N stop after converting N files (re-run to continue)
  thumb      [-t TIME] [-H PX] [-o OUTPUT] FILE
                               extract a single frame as a PNG image

Run `video <subcommand> -h` for per-command help.
"""

import argparse
import configparser
import datetime
import json
import logging
import os
import re
import shutil
import subprocess
import sys
import tempfile
import time

LOG = logging.getLogger(__name__)
logging.basicConfig(format='%(levelname)s: %(message)s', level=logging.WARNING)

# ---------------------------------------------------------------------------
# Config schema
# Each entry: (key, default, description).
# Consumed by `bcconfig --init` to generate a .bcconfig template.
# Defaults here must match the fallbacks used in _vcfg() / gcfg() calls below.
#
# Default encoding rationale
# --------------------------
# Goal: quality archive of mixed-source footage (480p–1080p) that won't be
# played on 4K screens. Priority is good quality at reasonable file size;
# encode time is secondary since files are encoded once.
#
# video_codec = libx264 (H.264)
#   Universal hardware decode support on every GPU, phone, and browser.
#   VP9/WebM and H.265 have patchier hardware decoders, which matters when
#   playing multiple streams simultaneously. H.264 is the safe archive choice.
#
# video_crf = 20
#   CRF 23 is the ffmpeg default but is tuned for web delivery (acceptable
#   quality, small files). CRF 20 is noticeably better quality (~50% larger
#   than CRF 23) while still compressing bloated/inefficient sources hard.
#   CRF 18 would be near-lossless but produces unnecessarily large files.
#
# video_preset = slow
#   At the same CRF, a slower preset finds more efficient ways to encode,
#   producing smaller files at identical quality. Since we encode once and
#   play back many times, the extra encode time is worth it. `slow` gives
#   most of the benefit of `slower`/`veryslow` without extreme encode times.
#
# audio_codec = aac / audio_bitrate = 160k
#   AAC has universal container and device support. 160k is a meaningful step
#   up from 128k for archive quality with negligible extra storage cost.
#   192k+ offers diminishing returns for typical speech/mixed audio.
#
# target_height = 720 (normalise default)
#   Acts as a ceiling, not a target. Videos taller than 720p are scaled down
#   to 720p (width auto-calculated from source aspect ratio, scale=-2:720,
#   lanczos). Videos at or below 720p are left at their original resolution.
#   This preserves 480p sources at 480p — upscaling would add no real quality
#   and wastes storage. AI upscaling (e.g. Real-ESRGAN) is a known future
#   improvement for 480p content but requires a separate tool.
# ---------------------------------------------------------------------------

BCCONFIG_SCHEMA = {
    "video": [
        ("default_format", "mp4",     "Default container format: mp4, mkv, mov, webm"),
    ],
    "video.convert": [
        ("video_codec",   "libx264",  "Video codec: libx264, libx265, libvpx-vp9"),
        ("video_preset",  "slow",     "Encoding speed/compression: ultrafast … veryslow"),
        ("video_crf",     "20",       "Quality (lower = better): libx264 18–28, libx265 24–28"),
        ("audio_codec",   "aac",      "Audio codec: aac, libmp3lame, libopus"),
        ("audio_bitrate", "160k",     "Audio bitrate (e.g. 128k, 192k, 256k)"),
    ],
    "video.thumb": [
        ("time", "00:00:01", "Default timestamp for frame extraction (HH:MM:SS or seconds)"),
    ],
    "video.normalise": [
        ("format",        "mp4",                  "Target container format: mp4, mkv, mov, webm"),
        ("target_height", "720",                  "Maximum height in pixels; taller videos are scaled down (aspect preserved), shorter videos are left as-is"),
        ("video_codec",   "libx264",              "Video codec: libx264, libx265, libvpx-vp9"),
        ("audio_codec",   "aac",                  "Audio codec: aac, libmp3lame, libopus"),
        ("video_preset",  "slow",                 "Encoding speed/compression: ultrafast … veryslow"),
        ("video_crf",     "20",                   "Quality (lower = better): libx264 18–28, libx265 24–28"),
        ("audio_bitrate", "160k",                 "Audio bitrate (e.g. 128k, 192k, 256k)"),
        ("original_dir",  "/tmp/video-originals", "Where to move originals before transcoding"),
        ("deinterlace",   "auto",                 "Deinterlace: auto (detect), yes, no"),
    ],
}


def _schema_for_metadata():
    sections = {}
    for section, entries in BCCONFIG_SCHEMA.items():
        sections[section] = [
            {"key": key, "default": default, "description": desc}
            for key, default, desc in entries
        ]
    return sections


def bc_metadata():
    """Return machine-readable command metadata for bcui/bcconfig discovery."""
    return {
        "schema_version": 1,
        "name": "video",
        "summary": "ffmpeg-backed video tools",
        "command_style": "subcommands",
        "config_sections": _schema_for_metadata(),
        "subcommands": [
            {
                "name": "formats",
                "summary": "Explain supported formats and codecs",
                "safety": "read",
                "args": [],
                "options": [
                    {"name": "all", "flag": "--all", "kind": "boolean",
                     "label": "List all ffmpeg encoders"},
                ],
                "artifacts": [],
            },
            {
                "name": "info",
                "summary": "Print detailed file, container, and stream information",
                "safety": "read",
                "args": [
                    {"name": "file", "label": "Video file", "kind": "path",
                     "required": True, "exists": True},
                ],
                "options": [
                    {"name": "json", "flag": "--json", "kind": "boolean",
                     "label": "Raw ffprobe JSON"},
                ],
                "artifacts": [
                    {"kind": "json", "source": "stdout", "when_option": "json"},
                ],
            },
            {
                "name": "convert",
                "summary": "Transcode a file using config defaults",
                "safety": "write",
                "args": [
                    {"name": "file", "label": "Video file", "kind": "path",
                     "required": True, "exists": True},
                ],
                "options": [
                    {"name": "format", "flag": "--format", "short_flag": "-f",
                     "kind": "choice", "choices": ["mp4", "mkv", "mov", "webm"],
                     "config": "video.default_format"},
                    {"name": "height", "flag": "--height", "short_flag": "-H",
                     "kind": "integer", "label": "Height"},
                    {"name": "vcodec", "flag": "--vcodec", "kind": "string",
                     "label": "Video codec", "config": "video.convert.video_codec"},
                    {"name": "acodec", "flag": "--acodec", "kind": "string",
                     "label": "Audio codec", "config": "video.convert.audio_codec"},
                    {"name": "crf", "flag": "--crf", "kind": "integer",
                     "label": "CRF", "config": "video.convert.video_crf"},
                    {"name": "preset", "flag": "--preset", "kind": "string",
                     "config": "video.convert.video_preset"},
                    {"name": "abitrate", "flag": "--abitrate", "kind": "string",
                     "label": "Audio bitrate", "config": "video.convert.audio_bitrate"},
                    {"name": "output", "flag": "--output", "short_flag": "-o",
                     "kind": "path", "label": "Output file", "artifact": "video"},
                ],
                "artifacts": [
                    {"kind": "video", "path_option": "output"},
                ],
            },
            {
                "name": "concat",
                "summary": "Join videos of the same format and resolution",
                "safety": "write",
                "args": [
                    {"name": "files", "label": "Video files", "kind": "path-list",
                     "required": True, "exists": True},
                ],
                "options": [
                    {"name": "output", "flag": "--output", "short_flag": "-o",
                     "kind": "path", "label": "Output file", "artifact": "video"},
                ],
                "artifacts": [
                    {"kind": "video", "path_option": "output"},
                ],
            },
            {
                "name": "clamp",
                "summary": "Cut a video to a time range",
                "safety": "write",
                "args": [
                    {"name": "file", "label": "Video file", "kind": "path",
                     "required": True, "exists": True},
                ],
                "options": [
                    {"name": "start", "flag": "--start", "short_flag": "-s",
                     "kind": "string", "label": "Start time"},
                    {"name": "end", "flag": "--end", "short_flag": "-e",
                     "kind": "string", "label": "End time"},
                    {"name": "output", "flag": "--output", "short_flag": "-o",
                     "kind": "path", "label": "Output file", "artifact": "video"},
                ],
                "artifacts": [
                    {"kind": "video", "path_option": "output"},
                ],
            },
            {
                "name": "thumb",
                "summary": "Extract a single frame as a PNG image",
                "safety": "write",
                "args": [
                    {"name": "file", "label": "Video file", "kind": "path",
                     "required": True, "exists": True},
                ],
                "options": [
                    {"name": "time", "flag": "--time", "short_flag": "-t",
                     "kind": "string", "config": "video.thumb.time"},
                    {"name": "height", "flag": "--height", "short_flag": "-H",
                     "kind": "integer", "label": "Height"},
                    {"name": "output", "flag": "--output", "short_flag": "-o",
                     "kind": "path", "label": "Output PNG", "artifact": "image/png"},
                ],
                "artifacts": [
                    {"kind": "image", "path_option": "output"},
                ],
            },
            {
                "name": "catalog",
                "summary": "Scan a directory tree and write an HTML report",
                "safety": "write",
                "args": [
                    {"name": "directory", "label": "Directory", "kind": "directory",
                     "required": True, "exists": True},
                ],
                "options": [
                    {"name": "output", "flag": "--output", "short_flag": "-o",
                     "kind": "path", "label": "Output HTML", "artifact": "text/html"},
                ],
                "artifacts": [
                    {"kind": "html", "path_option": "output"},
                ],
            },
            {
                "name": "normalise",
                "summary": "Batch-normalise a directory tree to a web-friendly format",
                "safety": "write",
                "args": [
                    {"name": "directory", "label": "Directory", "kind": "directory",
                     "required": True, "exists": True},
                ],
                "options": [
                    {"name": "dry_run", "flag": "--dry-run", "short_flag": "-n",
                     "kind": "boolean", "label": "Dry run"},
                    {"name": "limit", "flag": "--limit", "short_flag": "-l",
                     "kind": "integer", "label": "Limit"},
                    {"name": "force", "flag": "--force", "short_flag": "-f",
                     "kind": "boolean", "label": "Force"},
                    {"name": "output", "flag": "--output", "short_flag": "-o",
                     "kind": "path", "label": "Output HTML", "artifact": "text/html"},
                ],
                "artifacts": [
                    {"kind": "html", "path_option": "output"},
                ],
            },
        ],
    }


_BCCONFIG_NAME = ".bcconfig"


def _find_bcconfig_files(cwd=None):
    """Return list of .bcconfig file paths from ~ down to cwd (root first)."""
    home = os.path.expanduser("~")
    cwd = os.path.abspath(cwd or os.getcwd())

    paths = []
    home_cfg = os.path.join(home, _BCCONFIG_NAME)
    if os.path.isfile(home_cfg):
        paths.append(home_cfg)

    try:
        rel = os.path.relpath(cwd, home)
    except ValueError:
        return paths  # different drive on Windows

    if rel.startswith(".."):
        return paths  # cwd is outside home; only home config applies

    parts = [p for p in rel.split(os.sep) if p and p != "."]
    current = home
    for part in parts:
        current = os.path.join(current, part)
        candidate = os.path.join(current, _BCCONFIG_NAME)
        if os.path.isfile(candidate):
            paths.append(candidate)

    return paths


def _load_config(local_dir=None):
    """Load .bcconfig configuration via configparser.

    Reads .bcconfig files from ~ down to local_dir (or cwd), merging them
    so that closer-to-pwd values override parent values.
    Returns a RawConfigParser instance; missing keys fall back gracefully.
    """
    cfg = configparser.RawConfigParser()
    files = _find_bcconfig_files(local_dir or os.getcwd())
    cfg.read(files, encoding="utf-8")
    return cfg


# Global config loaded once at import time.
# Subcommands that accept a directory load their own merged config at runtime.
_VIDEO_CFG = _load_config()


def _vcfg(section, key, fallback, cfg=None):
    """Return a value from [section]/key, falling back to *fallback*.

    Uses the module-level global config unless *cfg* is supplied.
    """
    return (cfg or _VIDEO_CFG).get(section, key, fallback=fallback)


# ---------------------------------------------------------------------------
# Dependency check
# ---------------------------------------------------------------------------

def _require(*tools):
    missing = [t for t in tools if not _on_path(t)]
    if missing:
        sys.exit(
            f"Error: required tool(s) not found on PATH: {', '.join(missing)}\n"
            "Run 'bcinit' to install missing dependencies."
        )


def _on_path(tool):
    return shutil.which(tool) is not None


# ---------------------------------------------------------------------------
# ffmpeg / ffprobe helpers
# ---------------------------------------------------------------------------

def _run(cmd, check=True):
    """Run a command, streaming output to the terminal."""
    LOG.debug("run: %s", " ".join(str(c) for c in cmd))
    result = subprocess.run([str(c) for c in cmd], check=check)
    return result.returncode


def _probe(path):
    """Return ffprobe JSON for *path*."""
    cmd = [
        "ffprobe", "-v", "quiet",
        "-print_format", "json",
        "-show_format", "-show_streams",
        path,
    ]
    out = subprocess.check_output([str(c) for c in cmd], stderr=subprocess.DEVNULL)
    return json.loads(out)


def _default_output(path, suffix):
    """Derive an output filename from *path* with *suffix* appended before the extension."""
    base, _ = os.path.splitext(os.path.basename(path))
    return f"{base}{suffix}"


# Covers the major Unicode emoji blocks: misc symbols, pictographs, emoticons,
# transport, flags (regional indicators), variation selectors, ZWJ.
_EMOJI_RE = re.compile(
    "["
    "\U0001F300-\U0001F9FF"  # Misc Symbols & Pictographs, Emoticons, Transport, Supplemental
    "\U0001FA00-\U0001FAFF"  # Symbols & Pictographs Extended-A
    "\U00002600-\U000027BF"  # Misc Symbols, Dingbats
    "\U0001F1E0-\U0001F1FF"  # Regional Indicator letters (flags)
    "\uFE00-\uFE0F"          # Variation Selectors
    "\u200D"                 # Zero Width Joiner
    "]+",
    flags=re.UNICODE,
)


def _strip_emoji(s):
    """Remove emoji characters from *s* and normalise any resulting whitespace."""
    cleaned = _EMOJI_RE.sub("", s)
    # Collapse runs of whitespace left after removal; strip leading/trailing
    return re.sub(r"[ \t]+", " ", cleaned).strip()


# ---------------------------------------------------------------------------
# Subcommands
# ---------------------------------------------------------------------------

def cmd_info(args):
    _require("ffprobe")

    if args.json:
        data = _probe(args.file)
        print(json.dumps(data, indent=2))
        return

    path = args.file
    stat = os.stat(path)
    data = _probe(path)

    fmt     = data.get("format", {})
    streams = data.get("streams", [])
    tags    = fmt.get("tags", {})

    # ---- helpers ----
    W  = 18   # label column width
    HR = "─" * 54

    def section(title):
        print(f"\n\033[1m{title}\033[0m")
        print(HR)

    def field(label, value, note=""):
        if value in (None, "", "unknown", "0", 0):
            return
        note_str = f"  \033[2m({note})\033[0m" if note else ""
        print(f"  {label:<{W}} {value}{note_str}")

    def ratio(raw):
        """'16:9' or fraction string → reduce and return, e.g. '16:9'."""
        try:
            a, b = (int(x) for x in raw.replace(":", "/").split("/"))
            from math import gcd
            g = gcd(a, b)
            return f"{a//g}:{b//g}"
        except Exception:
            return raw

    # ---- File ----
    section("File")
    field("Path",          os.path.abspath(path))
    field("Size",          _fmt_size(stat.st_size),
          f"{stat.st_size:,} bytes")
    field("Modified",      datetime.datetime.fromtimestamp(stat.st_mtime)
                               .strftime("%Y-%m-%d %H:%M:%S"))

    # ---- Container ----
    section("Container")
    field("Format",        fmt.get("format_long_name") or fmt.get("format_name"))
    duration = float(fmt.get("duration") or 0)
    if duration:
        h, rem = divmod(int(duration), 3600)
        m, s   = divmod(rem, 60)
        field("Duration",  f"{h:02d}:{m:02d}:{s:02d}", f"{duration:.3f}s")
    br = int(fmt.get("bit_rate") or 0)
    field("Overall bitrate", f"{br // 1000} kb/s")
    field("Streams",       fmt.get("nb_streams"))
    if tags:
        for k in ("title", "comment", "artist", "album", "copyright",
                  "creation_time", "encoder", "major_brand"):
            v = tags.get(k) or tags.get(k.upper())
            if v:
                field(k.replace("_", " ").title(), v)

    # ---- Streams ----
    vs_count = as_count = ss_count = 0
    for s in streams:
        ctype = s.get("codec_type", "data")
        idx   = s.get("index", "?")
        codec = s.get("codec_name", "?")
        stags = s.get("tags", {})
        lang  = stags.get("language") or stags.get("LANGUAGE") or ""

        if ctype == "video":
            vs_count += 1
            section(f"Video stream #{idx}"
                    + (f"  [{lang}]" if lang else ""))
            field("Codec",         codec)
            field("Profile",       s.get("profile"))
            field("Level",         s.get("level"))
            w, h = s.get("width", 0), s.get("height", 0)
            if w and h:
                field("Resolution",    f"{w}×{h}")
            dar = s.get("display_aspect_ratio", "")
            if dar and dar != "0:1":
                field("Aspect ratio",  ratio(dar))
            field("Pixel format",  s.get("pix_fmt"))
            field("Color space",   s.get("color_space"))
            field("Color range",   s.get("color_range"))
            field("Color primaries",s.get("color_primaries"))
            field("Transfer",      s.get("color_transfer"))
            field("Bit depth",     s.get("bits_per_raw_sample"),
                  "per channel")
            avg = _fmt_fps(s.get("avg_frame_rate", ""))
            r   = _fmt_fps(s.get("r_frame_rate", ""))
            fps_note = f"real base: {r}" if r and r != avg else ""
            field("Frame rate",    f"{avg} fps", fps_note)
            fo = s.get("field_order", "")
            field("Field order",   fo if fo and fo != "unknown" else None)
            if _is_interlaced(s):
                field("Interlaced",    "yes")
            sbr = int(s.get("bit_rate") or 0)
            field("Bitrate",       f"{sbr // 1000} kb/s" if sbr else None)
            frames = s.get("nb_frames") or s.get("nb_read_frames")
            field("Frames",        frames)
            for k in ("title", "handler_name", "encoder"):
                v = stags.get(k) or stags.get(k.upper())
                if v:
                    field(k.replace("_", " ").title(), v)

        elif ctype == "audio":
            as_count += 1
            section(f"Audio stream #{idx}"
                    + (f"  [{lang}]" if lang else ""))
            field("Codec",         codec)
            field("Profile",       s.get("profile"))
            field("Sample rate",   f"{s.get('sample_rate')} Hz"
                  if s.get("sample_rate") else None)
            ch = s.get("channels")
            layout = s.get("channel_layout", "")
            field("Channels",      f"{ch}"
                  + (f"  ({layout})" if layout else ""))
            field("Bit depth",     s.get("bits_per_sample") or
                                   s.get("bits_per_raw_sample"),
                  "per sample")
            abr = int(s.get("bit_rate") or 0)
            field("Bitrate",       f"{abr // 1000} kb/s" if abr else None)
            for k in ("title", "handler_name"):
                v = stags.get(k) or stags.get(k.upper())
                if v:
                    field(k.replace("_", " ").title(), v)

        elif ctype == "subtitle":
            ss_count += 1
            section(f"Subtitle stream #{idx}"
                    + (f"  [{lang}]" if lang else ""))
            field("Codec",  codec)
            t = stags.get("title") or stags.get("TITLE")
            field("Title",  t)

        else:
            section(f"Stream #{idx}  [{ctype}]")
            field("Codec",  codec)

    print()


def cmd_convert(args):
    _require("ffmpeg")

    # All settings: explicit args win, then config, then hardcoded fallbacks
    fmt     = args.format.lower()
    vcodec  = args.vcodec  or _vcfg("video.convert", "video_codec",   "libx264")
    acodec  = args.acodec  or _vcfg("video.convert", "audio_codec",   "aac")
    crf     = str(args.crf    if args.crf    is not None else _vcfg("video.convert", "video_crf",    "20"))
    preset  = args.preset  or _vcfg("video.convert", "video_preset",  "slow")
    abitrate= args.abitrate or _vcfg("video.convert", "audio_bitrate", "160k")

    SUPPORTED = {"mp4", "mkv", "mov", "webm"}
    if fmt not in SUPPORTED:
        sys.exit(f"Error: unsupported format '{fmt}'. Supported: {', '.join(sorted(SUPPORTED))}")

    # webm needs its own codecs regardless of config/args
    if fmt == "webm":
        vcodec = "libvpx-vp9"
        acodec = "libopus"

    output = args.output or _default_output(args.file, f"_.{fmt}")

    cmd = ["ffmpeg", "-i", args.file]

    if args.height:
        cmd += ["-vf", f"scale=-2:{args.height}"]

    cmd += ["-vcodec", vcodec]

    if vcodec in ("libx264", "libx265"):
        cmd += ["-crf", crf, "-preset", preset]

    cmd += ["-acodec", acodec, "-b:a", abitrate, output]
    _run(cmd)
    print(f"Converted: {output}")


# ---------------------------------------------------------------------------
# Formats reference data
# ---------------------------------------------------------------------------

_CONTAINER_INFO = {
    "mp4": {
        "full_name":  "MPEG-4 Part 14",
        "muxer":      "mp4",
        "browser":    "Excellent — supported by every modern browser and device",
        "use_cases":  "Web delivery, general distribution, streaming, archival",
        "notes":      "Default choice. Requires moov atom at start for streaming; "
                      "ffmpeg adds -movflags +faststart automatically when writing to .mp4",
        "vcodecs":    "H.264 (libx264), H.265 (libx265), AV1",
        "acodecs":    "AAC, MP3, AC-3",
    },
    "mkv": {
        "full_name":  "Matroska",
        "muxer":      "matroska",
        "browser":    "Good — Chrome/Firefox; not Safari without plugin",
        "use_cases":  "Archival, multiple audio/subtitle tracks, any codec combination",
        "notes":      "Open container with no codec restrictions. Ideal when you need "
                      "multiple audio tracks or soft subtitles.",
        "vcodecs":    "Any (H.264, H.265, AV1, VP9, …)",
        "acodecs":    "Any (AAC, Opus, FLAC, …)",
    },
    "mov": {
        "full_name":  "QuickTime Movie",
        "muxer":      "mov",
        "browser":    "Good on macOS/Safari; limited elsewhere without codec support",
        "use_cases":  "Apple ecosystem, Final Cut Pro / DaVinci Resolve interchange, ProRes",
        "notes":      "Apple's native container. Shares most of the MP4 spec (both are "
                      "ISO Base Media File Format). Prefer MP4 for distribution.",
        "vcodecs":    "H.264, H.265, ProRes, DNxHD",
        "acodecs":    "AAC, PCM, ALAC",
    },
    "webm": {
        "full_name":  "WebM",
        "muxer":      "webm",
        "browser":    "Excellent in Chrome/Firefox; limited in Safari",
        "use_cases":  "Web video, open-source pipelines, smaller files at equivalent quality",
        "notes":      "Royalty-free container designed for the web. VP9+Opus gives "
                      "competitive quality to H.264+AAC at smaller sizes.",
        "vcodecs":    "VP8, VP9 (libvpx-vp9), AV1",
        "acodecs":    "Vorbis, Opus (libopus)",
    },
}

_VCODEC_INFO = {
    "libx264": {
        "codec":      "H.264 / AVC",
        "standard":   "ITU-T H.264, ISO/IEC 14496-10",
        "quality":    "CRF 18–28 (lower = better; 23 is default)",
        "preset":     "ultrafast → veryslow (speed vs compression; medium is default)",
        "use_cases":  "Universal default. Best compatibility across all devices and browsers.",
        "notes":      "Mature, fast encoder. Use CRF 18–20 for near-lossless archival, "
                      "23 for good web quality, 26–28 for small-but-acceptable files.",
    },
    "libx265": {
        "codec":      "H.265 / HEVC",
        "standard":   "ITU-T H.265, ISO/IEC 23008-2",
        "quality":    "CRF 24–28 (default 28; roughly equivalent quality to H.264 at half the bitrate)",
        "preset":     "ultrafast → veryslow (slower presets give significantly better compression)",
        "use_cases":  "4K/HDR archival, bandwidth-constrained delivery, future-proofing",
        "notes":      "~50% smaller than H.264 at the same quality, but slower to encode "
                      "and decode. Not universally supported (no Safari < macOS 10.13).",
    },
    "libvpx-vp9": {
        "codec":      "VP9",
        "standard":   "Google VP9 (open, royalty-free)",
        "quality":    "CRF 15–35; also supports -b:v 0 -crf N for constrained quality",
        "preset":     "Use -cpu-used 0–5 (0 = slowest/best, 4 = fast/default for web)",
        "use_cases":  "WebM/web delivery, YouTube, open-source pipelines",
        "notes":      "Royalty-free alternative to H.265. Good quality but slower to encode. "
                      "Pair with Opus audio for best results.",
    },
}

_ACODEC_INFO = {
    "aac": {
        "codec":     "Advanced Audio Coding",
        "standard":  "ISO/IEC 13818-7",
        "bitrates":  "96–320 kb/s stereo; 128 kb/s is a solid default",
        "use_cases": "Universal — pairs with H.264/H.265 in MP4/MOV/MKV",
        "notes":     "The most compatible audio codec. AAC-LC is the standard profile; "
                     "ffmpeg uses the built-in aac encoder unless libfdk_aac is available.",
    },
    "libopus": {
        "codec":     "Opus",
        "standard":  "IETF RFC 6716 (open, royalty-free)",
        "bitrates":  "32–320 kb/s; transparent quality at ~128 kb/s stereo",
        "use_cases": "WebM, open-source pipelines, low-bitrate speech/music",
        "notes":     "Best audio codec at low-to-medium bitrates. Royalty-free. "
                     "Required for WebM; also works in MKV.",
    },
    "libmp3lame": {
        "codec":     "MP3 / MPEG-1 Audio Layer III",
        "standard":  "ISO/IEC 11172-3",
        "bitrates":  "128–320 kb/s; 192 kb/s is the common quality threshold",
        "use_cases": "Legacy compatibility, standalone audio files",
        "notes":     "Widely supported but technically inferior to AAC at the same bitrate. "
                     "Use AAC unless MP3 compatibility is specifically required.",
    },
}


def _get_available_encoders():
    """Return a set of encoder names available in the installed ffmpeg."""
    try:
        out = subprocess.check_output(
            ["ffmpeg", "-encoders", "-v", "quiet"],
            stderr=subprocess.DEVNULL,
        ).decode(errors="replace")
        encoders = set()
        for line in out.splitlines():
            parts = line.split()
            # Encoder lines: " V..... libx264   H.264 / AVC ..."
            if len(parts) >= 2 and len(parts[0]) == 6 and parts[0][0] in "VAS":
                encoders.add(parts[1])
        return encoders
    except Exception:
        return set()


def _get_available_muxers():
    """Return a set of muxer names available in the installed ffmpeg."""
    try:
        out = subprocess.check_output(
            ["ffmpeg", "-muxers", "-v", "quiet"],
            stderr=subprocess.DEVNULL,
        ).decode(errors="replace")
        muxers = set()
        for line in out.splitlines():
            parts = line.split()
            if len(parts) >= 2 and len(parts[0]) == 2 and "E" in parts[0]:
                muxers.add(parts[1])
        return muxers
    except Exception:
        return set()


def cmd_formats(args):
    _require("ffmpeg")

    GREEN  = "\033[32m"
    RED    = "\033[31m"
    YELLOW = "\033[33m"
    BOLD   = "\033[1m"
    DIM    = "\033[2m"
    RESET  = "\033[0m"
    HR     = "─" * 60
    W      = 16

    def section(title):
        print(f"\n{BOLD}{title}{RESET}")
        print(HR)

    def field(label, value):
        if value:
            print(f"  {label:<{W}} {value}")

    def avail(name, available):
        mark = f"{GREEN}✓ available{RESET}" if name in available \
               else f"{RED}✗ not in this build{RESET}"
        return mark

    encoders = _get_available_encoders()
    muxers   = _get_available_muxers()

    # ---- Tool versions ----
    section("Tools")
    field("ffmpeg",  _tool_version("ffmpeg"))
    field("ffprobe", _tool_version("ffprobe"))

    # ---- Current config ----
    section("Current config  (~/.bcconfig)")
    field("Default format",  _vcfg("video",         "default_format",  "mp4"))
    field("Video codec",     _vcfg("video.convert", "video_codec",     "libx264"))
    field("Audio codec",     _vcfg("video.convert", "audio_codec",     "aac"))
    field("CRF",             _vcfg("video.convert", "video_crf",       "20"))
    field("Preset",          _vcfg("video.convert", "video_preset",    "slow"))
    field("Audio bitrate",   _vcfg("video.convert", "audio_bitrate",   "160k"))

    # ---- Container formats ----
    section("Container formats")
    for ext, info in _CONTAINER_INFO.items():
        mark = f"{GREEN}✓{RESET}" if info["muxer"] in muxers else f"{RED}✗{RESET}"
        print(f"\n  {BOLD}.{ext}{RESET}  {DIM}{info['full_name']}{RESET}  {mark}")
        print(f"  {'Browser':<{W}} {info['browser']}")
        print(f"  {'Use cases':<{W}} {info['use_cases']}")
        print(f"  {'Video codecs':<{W}} {info['vcodecs']}")
        print(f"  {'Audio codecs':<{W}} {info['acodecs']}")
        print(f"  {'Notes':<{W}} {info['notes']}")

    # ---- Video codecs ----
    section("Video codecs")
    for enc, info in _VCODEC_INFO.items():
        mark = avail(enc, encoders)
        print(f"\n  {BOLD}{enc}{RESET}  {DIM}{info['codec']}{RESET}  {mark}")
        print(f"  {'Standard':<{W}} {info['standard']}")
        print(f"  {'Quality':<{W}} {info['quality']}")
        print(f"  {'Preset':<{W}} {info['preset']}")
        print(f"  {'Use cases':<{W}} {info['use_cases']}")
        print(f"  {'Notes':<{W}} {info['notes']}")

    # ---- Audio codecs ----
    section("Audio codecs")
    for enc, info in _ACODEC_INFO.items():
        mark = avail(enc, encoders)
        print(f"\n  {BOLD}{enc}{RESET}  {DIM}{info['codec']}{RESET}  {mark}")
        print(f"  {'Standard':<{W}} {info['standard']}")
        print(f"  {'Bitrates':<{W}} {info['bitrates']}")
        print(f"  {'Use cases':<{W}} {info['use_cases']}")
        print(f"  {'Notes':<{W}} {info['notes']}")

    if args.all:
        # ---- Full ffmpeg encoder list ----
        section("All available encoders  (ffmpeg -encoders)")
        try:
            out = subprocess.check_output(
                ["ffmpeg", "-encoders", "-v", "quiet"],
                stderr=subprocess.DEVNULL,
            ).decode(errors="replace")
            # Print from the "------" divider onwards
            printing = False
            for line in out.splitlines():
                if line.startswith(" ---"):
                    printing = True
                    continue
                if printing:
                    print(" ", line)
        except Exception as e:
            print(f"  (error: {e})")

    print()


def cmd_concat(args):
    _require("ffmpeg")
    output = args.output or "output.mp4"

    with tempfile.NamedTemporaryFile(mode="w", suffix=".txt", delete=False) as flist:
        for f in args.files:
            flist.write(f"file '{os.path.abspath(f)}'\n")
        flist_path = flist.name

    try:
        _run([
            "ffmpeg", "-f", "concat", "-safe", "0",
            "-i", flist_path,
            "-vcodec", "libx264", "-acodec", "aac",
            output,
        ])
        print(f"Concatenated: {output}")
    finally:
        os.unlink(flist_path)


def cmd_clamp(args):
    _require("ffmpeg")
    output = args.output or _default_output(args.file, "_clamp.mp4")
    cmd = ["ffmpeg", "-i", args.file]
    if args.start:
        cmd += ["-ss", args.start]
    if args.end:
        cmd += ["-to", args.end]
    cmd += ["-vcodec", "libx264", "-acodec", "aac", output]
    _run(cmd)
    print(f"Clamped: {output}")


def cmd_thumb(args):
    _require("ffmpeg")
    output = args.output or _default_output(args.file, "_thumb.png")
    timestamp = args.time or _vcfg("video.thumb", "time", "00:00:01")
    cmd = ["ffmpeg", "-i", args.file, "-ss", timestamp, "-vframes", "1"]
    if args.height:
        # -2 keeps width even and maintains aspect ratio
        cmd += ["-vf", f"scale=-2:{args.height}"]
    cmd.append(output)
    _run(cmd)
    print(f"Thumbnail: {output}")


# ---------------------------------------------------------------------------
# Catalog helpers
# ---------------------------------------------------------------------------

VIDEO_EXTENSIONS = {
    ".mp4", ".mkv", ".mov", ".avi", ".webm", ".m4v", ".wmv",
    ".flv", ".mpg", ".mpeg", ".ts", ".mts", ".m2ts", ".3gp", ".ogv",
}


def _fmt_duration(secs):
    secs = int(secs)
    h, rem = divmod(secs, 3600)
    m, s = divmod(rem, 60)
    return f"{h:02d}:{m:02d}:{s:02d}"


def _fmt_size(nbytes):
    for unit in ("B", "KB", "MB", "GB"):
        if nbytes < 1024:
            return f"{nbytes:.1f} {unit}"
        nbytes /= 1024
    return f"{nbytes:.1f} TB"


def _fmt_fps(raw):
    """Convert '30000/1001' style fraction to a clean decimal string."""
    try:
        num, den = raw.split("/")
        fps = int(num) / int(den)
        return f"{fps:.2f}".rstrip("0").rstrip(".")
    except Exception:
        return raw


def _catalog_probe(full_path, rel_path):
    """Probe one file and return a summary dict. Never raises."""
    entry = {
        "path": rel_path,
        "size": os.path.getsize(full_path),
        "error": None,
        "format": "",
        "duration": 0.0,
        "bitrate": 0,
        "video_codec": "",
        "width": "",
        "height": "",
        "fps": "",
        "audio_codec": "",
        "channels": "",
        "sample_rate": "",
    }
    try:
        data = _probe(full_path)
        fmt = data.get("format", {})
        entry["format"] = fmt.get("format_name", "").split(",")[0]
        entry["duration"] = float(fmt.get("duration") or 0)
        entry["bitrate"] = int(fmt.get("bit_rate") or 0)
        for stream in data.get("streams", []):
            ctype = stream.get("codec_type")
            if ctype == "video" and not entry["video_codec"]:
                entry["video_codec"] = stream.get("codec_name", "")
                entry["width"] = stream.get("width", "")
                entry["height"] = stream.get("height", "")
                entry["fps"] = _fmt_fps(stream.get("avg_frame_rate", ""))
            elif ctype == "audio" and not entry["audio_codec"]:
                entry["audio_codec"] = stream.get("codec_name", "")
                entry["channels"] = stream.get("channels", "")
                entry["sample_rate"] = stream.get("sample_rate", "")
    except Exception as exc:
        entry["error"] = str(exc)
    return entry


def _catalog_html(directory, entries):
    now = datetime.datetime.now().strftime("%Y-%m-%d %H:%M")
    abs_dir = os.path.abspath(directory)
    total_size = sum(e["size"] for e in entries)
    total_duration = sum(e["duration"] for e in entries)
    errors = sum(1 for e in entries if e["error"])

    rows = []
    for e in entries:
        err_cell = f'<td class="err" title="{e["error"]}">error</td>' if e["error"] else ""
        resolution = f'{e["width"]}×{e["height"]}' if e["width"] else "—"
        fps = e["fps"] or "—"
        audio = f'{e["audio_codec"]} {e["channels"]}ch' if e["audio_codec"] else "—"
        bitrate = f'{e["bitrate"] // 1000} kb/s' if e["bitrate"] else "—"
        duration = _fmt_duration(e["duration"]) if e["duration"] else "—"
        size = _fmt_size(e["size"])
        video_cell = f'{e["video_codec"]}<br><span class="sub">{resolution} · {fps} fps</span>' if e["video_codec"] else "—"

        cells = [
            f'<td class="path" title="{e["path"]}">{e["path"]}</td>',
            f'<td class="r">{size}</td>',
            f'<td class="r">{duration}</td>',
            f'<td>{e["format"]}</td>',
            f'<td>{video_cell}</td>',
            f'<td>{audio}</td>',
            f'<td class="r">{bitrate}</td>',
        ]
        if e["error"]:
            cells = [f'<td class="path err" colspan="7" title="{e["error"]}">{e["path"]} — probe error</td>']
        rows.append(f'<tr>{"".join(cells)}</tr>')

    rows_html = "\n".join(rows)

    return f"""<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Video Catalog — {abs_dir}</title>
<style>
  * {{ box-sizing: border-box; margin: 0; padding: 0; }}
  body {{ font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
          font-size: 13px; background: #f5f5f7; color: #1d1d1f; }}
  header {{ background: #1d1d1f; color: #f5f5f7; padding: 20px 28px; }}
  header h1 {{ font-size: 18px; font-weight: 600; }}
  header p {{ font-size: 12px; color: #a1a1a6; margin-top: 4px; }}
  .summary {{ display: flex; gap: 24px; padding: 16px 28px;
              background: #fff; border-bottom: 1px solid #d2d2d7; flex-wrap: wrap; }}
  .stat {{ display: flex; flex-direction: column; }}
  .stat .val {{ font-size: 22px; font-weight: 600; }}
  .stat .lbl {{ font-size: 11px; color: #6e6e73; margin-top: 2px; }}
  .stat.warn .val {{ color: #c0392b; }}
  .wrap {{ padding: 20px 28px; }}
  table {{ width: 100%; border-collapse: collapse; background: #fff;
           border-radius: 8px; overflow: hidden;
           box-shadow: 0 1px 4px rgba(0,0,0,.08); }}
  thead th {{ background: #e8e8ed; padding: 8px 10px; text-align: left;
              font-weight: 600; cursor: pointer; user-select: none;
              white-space: nowrap; font-size: 12px; }}
  thead th:hover {{ background: #d2d2d7; }}
  thead th.r, td.r {{ text-align: right; }}
  tbody tr:nth-child(even) {{ background: #fafafa; }}
  tbody tr:hover {{ background: #eef4ff; }}
  td {{ padding: 7px 10px; border-bottom: 1px solid #f0f0f0;
        vertical-align: middle; max-width: 340px;
        overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }}
  td.path {{ font-family: "SF Mono", "Fira Code", monospace; font-size: 12px; }}
  td.err {{ color: #c0392b; font-style: italic; }}
  .sub {{ font-size: 11px; color: #6e6e73; }}
  footer {{ padding: 12px 28px; font-size: 11px; color: #6e6e73; }}
</style>
</head>
<body>
<header>
  <h1>Video Catalog</h1>
  <p>{abs_dir}</p>
</header>
<div class="summary">
  <div class="stat"><span class="val">{len(entries)}</span><span class="lbl">Files</span></div>
  <div class="stat"><span class="val">{_fmt_size(total_size)}</span><span class="lbl">Total size</span></div>
  <div class="stat"><span class="val">{_fmt_duration(total_duration)}</span><span class="lbl">Total duration</span></div>
  {"" if not errors else f'<div class="stat warn"><span class="val">{errors}</span><span class="lbl">Probe errors</span></div>'}
</div>
<div class="wrap">
<table id="tbl">
  <thead>
    <tr>
      <th onclick="sort(0)">File</th>
      <th onclick="sort(1)" class="r">Size</th>
      <th onclick="sort(2)" class="r">Duration</th>
      <th onclick="sort(3)">Format</th>
      <th onclick="sort(4)">Video</th>
      <th onclick="sort(5)">Audio</th>
      <th onclick="sort(6)" class="r">Bitrate</th>
    </tr>
  </thead>
  <tbody>
{rows_html}
  </tbody>
</table>
</div>
<footer>Generated {now} · video catalog</footer>
<script>
  let _dir = Array(7).fill(1);
  function sort(col) {{
    const tb = document.querySelector('#tbl tbody');
    const rows = Array.from(tb.rows);
    rows.sort((a, b) => {{
      const av = a.cells[col] ? a.cells[col].innerText : '';
      const bv = b.cells[col] ? b.cells[col].innerText : '';
      const an = parseFloat(av), bn = parseFloat(bv);
      const cmp = (!isNaN(an) && !isNaN(bn)) ? an - bn : av.localeCompare(bv);
      return cmp * _dir[col];
    }});
    _dir[col] *= -1;
    rows.forEach(r => tb.appendChild(r));
  }}
</script>
</body>
</html>"""


def cmd_catalog(args):
    _require("ffprobe")
    directory = os.path.realpath(args.directory)
    if not os.path.isdir(directory):
        sys.exit(f"Error: not a directory: {args.directory}")

    output = args.output or "catalog.html"

    print(f"Scanning {directory} ...")
    entries = []
    for root, dirs, files in os.walk(directory):
        dirs.sort()
        for fname in sorted(files):
            if os.path.splitext(fname)[1].lower() in VIDEO_EXTENSIONS:
                full_path = os.path.realpath(os.path.join(root, fname))
                rel_path = os.path.relpath(full_path, directory)
                if rel_path.startswith(".."):
                    # Symlink escaped the target directory — skip it
                    continue
                print(f"  {rel_path}")
                entries.append(_catalog_probe(full_path, rel_path))

    if not entries:
        sys.exit("No video files found.")

    html = _catalog_html(directory, entries)
    with open(output, "w", encoding="utf-8") as fh:
        fh.write(html)

    errors = sum(1 for e in entries if e["error"])
    print(f"\nReport: {output}  ({len(entries)} files"
          + (f", {errors} probe errors" if errors else "") + ")")


# ---------------------------------------------------------------------------
# Normalise
# ---------------------------------------------------------------------------

# ffprobe codec names differ from the ffmpeg encoder names
_VCODEC_PROBE = {"libx264": "h264", "libx265": "hevc", "libvpx-vp9": "vp9"}
_ACODEC_PROBE = {"libmp3lame": "mp3", "libopus": "opus"}


def _is_interlaced(stream):
    field_order = stream.get("field_order", "progressive")
    return field_order not in ("progressive", "unknown", "")


def _scale_filter(target_h):
    """Return an ffmpeg vf scale expression that scales to target_h, with the
    width auto-calculated from the source aspect ratio using lanczos resampling.
    -2 ensures the auto-calculated width is divisible by 2 (required by most
    codecs). Aspect ratio is always preserved — no padding or cropping."""
    return f"scale=-2:{target_h}:flags=lanczos"


def _tool_version(tool):
    """Return the version string for *tool* (e.g. 'ffmpeg 6.1.1'), or 'unknown'."""
    try:
        out = subprocess.check_output(
            [tool, "-version"], stderr=subprocess.STDOUT
        ).decode(errors="replace")
        first = out.splitlines()[0]          # e.g. "ffmpeg version 6.1.1 Copyright ..."
        # grab everything up to the first "Copyright" / "built" clause
        return first.split("Copyright")[0].split(" built")[0].strip()
    except Exception:
        return f"{tool} (unknown version)"


def _fmt_elapsed(secs):
    """Format elapsed seconds as 'Xm Ys' or 'Xs'."""
    secs = int(secs)
    m, s = divmod(secs, 60)
    return f"{m}m {s:02d}s" if m else f"{s}s"


def _norm_assess(before, deinterlace, target_h, want_vc, want_ac, target_fmt):
    """Compare *before* probe data against normalise targets.

    Returns a dict with compliant (bool), reasons (list[str]), and checks
    (list of per-criterion dicts for HTML rendering).

    Resolution is checked by height only — width is derived from the source
    aspect ratio so files at the correct height are never needlessly rescaled.
    """
    needs_deint  = deinterlace == "yes" or (deinterlace == "auto" and before["interlaced"])
    needs_scale  = (before["height"] > target_h)   # clamp only — never upscale
    needs_vcodec = (before["video_codec"] != want_vc)
    needs_acodec = (before["audio_codec"] != want_ac)
    # Use the full comma-separated format_names string for detection so that a
    # file reported as "mov,mp4,m4a,…" by ffprobe is not falsely flagged as
    # needing conversion when the target is already "mp4".
    needs_fmt    = (target_fmt not in before.get("format_names", before["format"]))

    res_current = f'{before["width"]}×{before["height"]}' if before["width"] else "—"
    res_target  = f"h={target_h}"

    checks = [
        {
            "label": "Video codec",
            "ok": not needs_vcodec,
            "current": before["video_codec"] or "—",
            "target": want_vc,
            "fix": f"re-encode video: {before['video_codec']} → {want_vc}",
        },
        {
            "label": "Audio codec",
            "ok": not needs_acodec,
            "current": before["audio_codec"] or "—",
            "target": want_ac,
            "fix": f"re-encode audio: {before['audio_codec'] or 'none'} → {want_ac}",
        },
        {
            "label": "Resolution",
            "ok": not needs_scale,
            "current": res_current,
            "target": res_target,
            "fix": f"scale down to h={target_h} (width auto from aspect): {res_current}",
        },
        {
            "label": "Container",
            "ok": not needs_fmt,
            "current": before["format"] or "—",
            "target": target_fmt,
            "fix": f"remux/transcode: {before['format']} → {target_fmt}",
        },
        {
            "label": "Deinterlace",
            "ok": not needs_deint,
            "current": "interlaced" if before["interlaced"] else "progressive",
            "target": "progressive",
            "fix": "deinterlace (yadif)",
        },
    ]

    reasons = []
    if needs_vcodec:
        reasons.append(f"vcodec {before['video_codec']}→{want_vc}")
    if needs_acodec:
        reasons.append(f"acodec {before['audio_codec'] or 'none'}→{want_ac}")
    if needs_scale:
        reasons.append(f"scale down {res_current}→{res_target}")
    if needs_fmt:
        reasons.append(f"format {before['format']}→{target_fmt}")
    if needs_deint:
        reasons.append("deinterlace")

    compliant = not any([needs_vcodec, needs_acodec, needs_scale, needs_fmt, needs_deint])
    return {"compliant": compliant, "reasons": reasons, "checks": checks}


def _norm_probe(path):
    """Probe *path* and return a compact summary dict for the normalise report."""
    e = {
        "size": 0, "format": "", "format_names": "", "duration": 0.0, "bitrate": 0,
        "video_codec": "", "width": 0, "height": 0, "fps": "",
        "audio_codec": "", "channels": "", "interlaced": False,
    }
    try:
        e["size"] = os.path.getsize(path)
        data = _probe(path)
        fmt = data.get("format", {})
        raw_fmt = fmt.get("format_name", "")
        e["format"]       = raw_fmt.split(",")[0]   # first name for display
        e["format_names"] = raw_fmt                 # all names for detection
        e["duration"] = float(fmt.get("duration") or 0)
        e["bitrate"]  = int(fmt.get("bit_rate")   or 0)
        for s in data.get("streams", []):
            ctype = s.get("codec_type")
            if ctype == "video" and not e["video_codec"]:
                e["video_codec"] = s.get("codec_name", "")
                e["width"]       = int(s.get("width",  0))
                e["height"]      = int(s.get("height", 0))
                e["fps"]         = _fmt_fps(s.get("avg_frame_rate", ""))
                e["interlaced"]  = _is_interlaced(s)
            elif ctype == "audio" and not e["audio_codec"]:
                e["audio_codec"] = s.get("codec_name", "")
                e["channels"]    = s.get("channels", "")
    except Exception:
        pass
    return e


def _run_info_section(run_info):
    """Render the collapsible Run Information section, or empty string if no info."""
    if not run_info:
        return ""

    def row(k, v):
        return f'<tr><td>{k}</td><td>{v}</td></tr>'

    cfg_rows = "".join([
        row("Target format",   run_info.get("target_fmt", "—")),
        row("Video codec",     run_info.get("vcodec", "—")),
        row("Audio codec",     run_info.get("acodec", "—")),
        row("CRF",             run_info.get("crf", "—")),
        row("Preset",          run_info.get("preset", "—")),
        row("Audio bitrate",   run_info.get("abitrate", "—")),
        row("Target resolution", run_info.get("target_res", "—")),
        row("Deinterlace",     run_info.get("deinterlace", "—")),
        row("Originals dir",   run_info.get("orig_dir", "—")),
        row("",                ""),
        row("ffmpeg",          run_info.get("ffmpeg_ver", "—")),
        row("ffprobe",         run_info.get("ffprobe_ver", "—")),
        row("Python",          run_info.get("python_ver", "—")),
        row("",                ""),
        row("Total run time",  run_info.get("total_elapsed", "—")),
        row("Config files",    "<br>".join(run_info.get("config_files", []) or ["(none)"])),
    ])

    return f"""
<details>
  <summary>Run information</summary>
  <br>
  <table class="cfg-table">
    <tbody>{cfg_rows}</tbody>
  </table>
</details>"""


def _norm_check_cell(check):
    """Render one criterion cell for the assessment report."""
    cls = "ok" if check["ok"] else "bad"
    cur = check["current"]
    if check["ok"]:
        return f'<td class="{cls}">{cur}</td>'
    tgt = check["target"]
    return (
        f'<td class="{cls}" title="{check["fix"]}">'
        f'{cur}<br><span class="fix">→ {tgt}</span></td>'
    )


def _normalise_plan_html(directory, entries, target, run_info=None):
    """Render a pre-flight assessment HTML report (no conversion performed)."""
    now  = datetime.datetime.now().strftime("%Y-%m-%d %H:%M")
    absd = os.path.abspath(directory)

    ok_entries  = [e for e in entries if e.get("compliant")]
    bad_entries = [e for e in entries if not e.get("compliant") and not e.get("error")]
    err_entries = [e for e in entries if e.get("error")]

    def _detail_cell(e):
        b = e["before"]
        res = f'{b["width"]}×{b["height"]}' if b["width"] else "—"
        fps = b["fps"] or "—"
        br  = f'{b["bitrate"] // 1000} kb/s' if b["bitrate"] else "—"
        dur = _fmt_duration(b["duration"]) if b["duration"] else "—"
        return (
            f'{_fmt_size(b["size"])} · {dur}<br>'
            f'<span class="sub">{res} · {fps} fps · {br}</span>'
        )

    def _row(e):
        if e.get("error"):
            return (
                f'<tr class="err-row">'
                f'<td class="status err">✗</td>'
                f'<td class="path" title="{e["path"]}">{e["path"]}</td>'
                f'<td colspan="7" class="err">{e["error"]}</td>'
                f'</tr>'
            )

        row_cls = "row-ok" if e["compliant"] else "row-bad"
        status  = "✓" if e["compliant"] else "✗"
        status_cls = "ok" if e["compliant"] else "bad"
        changes = "—" if e["compliant"] else "; ".join(c["fix"] for c in e["checks"] if not c["ok"])
        check_cells = "".join(_norm_check_cell(c) for c in e["checks"])
        return (
            f'<tr class="{row_cls}">'
            f'<td class="status {status_cls}">{status}</td>'
            f'<td class="path" title="{e["path"]}">{e["path"]}</td>'
            f'<td class="detail">{_detail_cell(e)}</td>'
            f'{check_cells}'
            f'<td class="changes">{changes}</td>'
            f'</tr>'
        )

    # Non-compliant first so the work list is at the top
    ordered = bad_entries + ok_entries + err_entries
    rows_html = "\n".join(_row(e) for e in ordered)

    return f"""<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>Normalise Assessment — {absd}</title>
<style>
  *{{box-sizing:border-box;margin:0;padding:0}}
  body{{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;
        font-size:13px;background:#f5f5f7;color:#1d1d1f}}
  header{{background:#1d1d1f;color:#f5f5f7;padding:20px 28px}}
  header h1{{font-size:18px;font-weight:600}}
  header p{{font-size:12px;color:#a1a1a6;margin-top:4px}}
  .summary{{display:flex;gap:20px;padding:16px 28px;background:#fff;
            border-bottom:1px solid #d2d2d7;flex-wrap:wrap}}
  .stat{{display:flex;flex-direction:column;min-width:80px}}
  .stat .val{{font-size:22px;font-weight:600}}
  .stat .lbl{{font-size:11px;color:#6e6e73;margin-top:2px}}
  .stat.ok .val{{color:#27ae60}}
  .stat.bad .val{{color:#c0392b}}
  .stat.warn .val{{color:#e67e22}}
  .wrap{{padding:20px 28px;display:flex;flex-direction:column;gap:24px}}
  h2{{font-size:14px;font-weight:600;margin-bottom:8px;color:#1d1d1f}}
  table{{width:100%;border-collapse:collapse;background:#fff;border-radius:8px;
         overflow:hidden;box-shadow:0 1px 4px rgba(0,0,0,.08)}}
  thead th{{background:#e8e8ed;padding:8px 10px;text-align:left;
            font-weight:600;font-size:12px;white-space:nowrap}}
  tbody tr:nth-child(even){{background:#fafafa}}
  tbody tr:hover{{background:#eef4ff}}
  tr.row-ok{{background:#f0faf4}}
  tr.row-ok:nth-child(even){{background:#e8f5ee}}
  tr.row-bad{{background:#fdf0f0}}
  tr.row-bad:nth-child(even){{background:#fae8e8}}
  tr.row-ok:hover{{background:#e0f5ea}}
  tr.row-bad:hover{{background:#fde8e8}}
  td{{padding:7px 10px;border-bottom:1px solid #f0f0f0;vertical-align:top}}
  td.path{{font-family:"SF Mono","Fira Code",monospace;font-size:12px;
           max-width:280px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}}
  td.detail{{font-size:12px;min-width:140px}}
  td.status{{font-weight:700;text-align:center;width:32px;font-size:14px}}
  td.status.ok{{color:#27ae60}}
  td.status.bad{{color:#c0392b}}
  td.ok{{color:#1e7e34;background:rgba(39,174,96,.08)}}
  td.bad{{color:#c0392b;background:rgba(192,57,43,.08)}}
  td.changes{{font-size:11px;color:#6e6e73;min-width:200px;max-width:360px;
              white-space:normal;line-height:1.4}}
  td.err{{color:#c0392b;font-size:12px}}
  tr.err-row{{background:#fff5f5}}
  .fix{{font-size:11px;font-weight:600}}
  .sub{{color:#6e6e73;font-size:11px}}
  .cfg-table{{width:auto;min-width:400px}}
  .cfg-table td:first-child{{font-weight:600;white-space:nowrap;padding-right:24px}}
  .cfg-table td{{border:none;padding:4px 10px}}
  details summary{{cursor:pointer;font-size:14px;font-weight:600;
                   padding:8px 0;color:#1d1d1f;list-style:none}}
  details summary::-webkit-details-marker{{display:none}}
  details summary::before{{content:"▶ "}}
  details[open] summary::before{{content:"▼ "}}
  footer{{padding:12px 28px;font-size:11px;color:#6e6e73}}
  .legend{{display:flex;gap:16px;font-size:12px;padding:0 28px 12px;color:#6e6e73}}
  .legend span{{display:inline-flex;align-items:center;gap:6px}}
  .swatch{{display:inline-block;width:12px;height:12px;border-radius:2px}}
  .swatch.ok{{background:#27ae60}}
  .swatch.bad{{background:#c0392b}}
</style>
</head>
<body>
<header>
  <h1>Normalise Assessment</h1>
  <p>{absd}</p>
  <p>Target: {target}</p>
</header>
<div class="summary">
  <div class="stat"><span class="val">{len(entries)}</span><span class="lbl">Files scanned</span></div>
  <div class="stat ok"><span class="val">{len(ok_entries)}</span><span class="lbl">Already compliant</span></div>
  <div class="stat bad"><span class="val">{len(bad_entries)}</span><span class="lbl">Need changes</span></div>
  {"" if not err_entries else f'<div class="stat warn"><span class="val">{len(err_entries)}</span><span class="lbl">Probe errors</span></div>'}
</div>
<div class="legend">
  <span><span class="swatch ok"></span> Meets target</span>
  <span><span class="swatch bad"></span> Needs change (fix shown in cell and Changes column)</span>
</div>
<div class="wrap">
<section>
  <h2>All files</h2>
  <table>
    <thead><tr>
      <th></th>
      <th>File</th>
      <th>Size / duration</th>
      <th>Video codec</th>
      <th>Audio codec</th>
      <th>Resolution</th>
      <th>Container</th>
      <th>Scan type</th>
      <th>Changes required</th>
    </tr></thead>
    <tbody>
{rows_html}
    </tbody>
  </table>
</section>
{_run_info_section(run_info)}
</div>
<footer>Generated {now} · video normalise --report</footer>
</body>
</html>"""


def _normalise_html(directory, results, target, orig_dir, dry_run, run_info=None):
    """Render the normalise run results as a self-contained HTML report."""
    now    = datetime.datetime.now().strftime("%Y-%m-%d %H:%M")
    absd   = os.path.abspath(directory)

    conv   = [r for r in results if r["status"] == "converted"]
    skipped= [r for r in results if r["status"] == "skipped"]
    errors = [r for r in results if r["status"] == "error"]

    size_before = sum(r["before"]["size"] for r in conv)
    size_after  = sum(r["after"]["size"]  for r in conv if r["after"])
    saved       = size_before - size_after
    saved_pct   = (saved / size_before * 100) if size_before else 0
    saved_sign  = "+" if saved < 0 else ""   # negative saved = grew

    br_before_vals = [r["before"]["bitrate"] for r in conv if r["before"]["bitrate"]]
    br_after_vals  = [r["after"]["bitrate"]  for r in conv if r["after"] and r["after"]["bitrate"]]
    avg_br_before  = (sum(br_before_vals) // len(br_before_vals)) if br_before_vals else 0
    avg_br_after   = (sum(br_after_vals)  // len(br_after_vals))  if br_after_vals  else 0
    avg_br_saved   = avg_br_before - avg_br_after
    avg_br_pct     = (avg_br_saved / avg_br_before * 100) if avg_br_before else 0

    def _cell(e):
        if not e:
            return "—"
        res = f'{e["width"]}×{e["height"]}' if e["width"] else "—"
        fps = e["fps"] or "—"
        vc  = e["video_codec"] or "—"
        ac  = e["audio_codec"] or "—"
        ch  = f' {e["channels"]}ch' if e["channels"] else ""
        br  = f'{e["bitrate"]//1000} kb/s' if e["bitrate"] else "—"
        dur = _fmt_duration(e["duration"]) if e["duration"] else "—"
        il  = ' <span class="tag">interlaced</span>' if e.get("interlaced") else ""
        return (
            f'<span class="vc">{vc}</span>{il} · {res} · {fps} fps<br>'
            f'<span class="sub">{ac}{ch} · {br} · {dur} · {_fmt_size(e["size"])}</span>'
        )

    def _delta(r):
        if not r["after"]:
            return "—"
        d = r["after"]["size"] - r["before"]["size"]
        pct = (d / r["before"]["size"] * 100) if r["before"]["size"] else 0
        cls = "pos" if d < 0 else "neg"
        sign = "" if d < 0 else "+"
        return f'<span class="{cls}">{sign}{_fmt_size(d)}<br>{sign}{pct:.1f}%</span>'

    def _bitrate_delta(r):
        bb = r["before"]["bitrate"]
        ba = r["after"]["bitrate"] if r["after"] else 0
        if not bb or not ba:
            return "—"
        bb_s = f'{bb // 1000} kb/s'
        ba_s = f'{ba // 1000} kb/s'
        d    = ba - bb
        pct  = (d / bb * 100) if bb else 0
        cls  = "pos" if d < 0 else "neg"
        sign = "" if d < 0 else "+"
        return (
            f'{bb_s} → {ba_s}<br>'
            f'<span class="{cls}">{sign}{pct:.1f}%</span>'
        )

    def _elapsed_cell(r):
        e = r.get("elapsed")
        if e is None:
            return "—"
        spd = ""
        if r["before"]["duration"] and e > 0:
            ratio = r["before"]["duration"] / e
            spd = f'<br><span class="sub">{ratio:.1f}× realtime</span>'
        return f"{_fmt_elapsed(e)}{spd}"

    conv_rows = "\n".join(
        f'<tr>'
        f'<td class="path">{r["path"]}</td>'
        f'<td class="detail">{_cell(r["before"])}</td>'
        f'<td class="detail">{_cell(r["after"])}</td>'
        f'<td class="r delta">{_delta(r)}</td>'
        f'<td class="r bitrate-delta">{_bitrate_delta(r)}</td>'
        f'<td class="r elapsed">{_elapsed_cell(r)}</td>'
        f'<td class="reasons">{", ".join(r["reasons"])}</td>'
        f'</tr>'
        for r in conv
    )
    skip_rows = "\n".join(
        f'<tr><td class="path">{r["path"]}</td><td class="detail">{_cell(r["before"])}</td></tr>'
        for r in skipped
    )
    err_rows = "\n".join(
        f'<tr><td class="path">{r["path"]}</td>'
        f'<td class="err">{r.get("error_msg","")}</td></tr>'
        for r in errors
    )

    dry_banner = '<div class="dry-banner">Dry run — no files were changed</div>' if dry_run else ""

    return f"""<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>Normalise Report — {absd}</title>
<style>
  *{{box-sizing:border-box;margin:0;padding:0}}
  body{{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;
        font-size:13px;background:#f5f5f7;color:#1d1d1f}}
  header{{background:#1d1d1f;color:#f5f5f7;padding:20px 28px}}
  header h1{{font-size:18px;font-weight:600}}
  header p{{font-size:12px;color:#a1a1a6;margin-top:4px}}
  .dry-banner{{background:#c0392b;color:#fff;padding:8px 28px;font-weight:600}}
  .summary{{display:flex;gap:20px;padding:16px 28px;background:#fff;
            border-bottom:1px solid #d2d2d7;flex-wrap:wrap}}
  .stat{{display:flex;flex-direction:column;min-width:80px}}
  .stat .val{{font-size:22px;font-weight:600}}
  .stat .lbl{{font-size:11px;color:#6e6e73;margin-top:2px}}
  .stat.save .val{{color:#27ae60}}
  .stat.grow .val{{color:#c0392b}}
  .stat.warn .val{{color:#e67e22}}
  .wrap{{padding:20px 28px;display:flex;flex-direction:column;gap:24px}}
  h2{{font-size:14px;font-weight:600;margin-bottom:8px;color:#1d1d1f}}
  table{{width:100%;border-collapse:collapse;background:#fff;border-radius:8px;
         overflow:hidden;box-shadow:0 1px 4px rgba(0,0,0,.08)}}
  thead th{{background:#e8e8ed;padding:8px 10px;text-align:left;
            font-weight:600;font-size:12px;white-space:nowrap}}
  th.r,td.r{{text-align:right}}
  tbody tr:nth-child(even){{background:#fafafa}}
  tbody tr:hover{{background:#eef4ff}}
  td{{padding:7px 10px;border-bottom:1px solid #f0f0f0;vertical-align:top}}
  td.path{{font-family:"SF Mono","Fira Code",monospace;font-size:12px;
           max-width:280px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}}
  td.detail{{font-size:12px;min-width:220px}}
  td.delta,td.elapsed,td.bitrate-delta{{font-size:12px;white-space:nowrap}}
  td.reasons{{font-size:11px;color:#6e6e73}}
  .cfg-table{{width:auto;min-width:400px}}
  .cfg-table td:first-child{{font-weight:600;white-space:nowrap;padding-right:24px}}
  .cfg-table td{{border:none;padding:4px 10px}}
  td.err{{color:#c0392b;font-size:12px}}
  .vc{{font-weight:600}}
  .sub{{color:#6e6e73}}
  .pos{{color:#27ae60}}
  .neg{{color:#c0392b}}
  .tag{{display:inline-block;background:#f0e0d0;color:#c0392b;
        border-radius:3px;padding:0 4px;font-size:10px}}
  details summary{{cursor:pointer;font-size:14px;font-weight:600;
                   padding:8px 0;color:#1d1d1f;list-style:none}}
  details summary::-webkit-details-marker{{display:none}}
  details summary::before{{content:"▶ "}}
  details[open] summary::before{{content:"▼ "}}
  footer{{padding:12px 28px;font-size:11px;color:#6e6e73}}
</style>
</head>
<body>
<header>
  <h1>Normalise Report</h1>
  <p>{absd}</p>
  <p>Target: {target} · Originals → {orig_dir}</p>
</header>
{dry_banner}
<div class="summary">
  <div class="stat"><span class="val">{len(results)}</span><span class="lbl">Scanned</span></div>
  <div class="stat"><span class="val">{len(conv)}</span><span class="lbl">Converted</span></div>
  <div class="stat"><span class="val">{len(skipped)}</span><span class="lbl">Skipped</span></div>
  {"" if not errors else f'<div class="stat warn"><span class="val">{len(errors)}</span><span class="lbl">Errors</span></div>'}
  <div class="stat"><span class="val">{_fmt_size(size_before)}</span><span class="lbl">Size before</span></div>
  <div class="stat"><span class="val">{_fmt_size(size_after)}</span><span class="lbl">Size after</span></div>
  <div class="stat {'save' if saved>=0 else 'grow'}">
    <span class="val">{saved_sign}{_fmt_size(abs(saved))}</span>
    <span class="lbl">{'Saved' if saved>=0 else 'Grew'} ({saved_sign}{saved_pct:.1f}%)</span>
  </div>
  {"" if not avg_br_before else f'''
  <div class="stat"><span class="val">{avg_br_before // 1000} kb/s</span><span class="lbl">Avg bitrate before</span></div>
  <div class="stat"><span class="val">{avg_br_after // 1000} kb/s</span><span class="lbl">Avg bitrate after</span></div>
  <div class="stat {'save' if avg_br_saved>=0 else 'grow'}">
    <span class="val">{('' if avg_br_saved>=0 else '+')}{avg_br_saved // 1000} kb/s</span>
    <span class="lbl">{'Reduced' if avg_br_saved>=0 else 'Increased'} ({('' if avg_br_pct>=0 else '+')+f'{avg_br_pct:.1f}'}%)</span>
  </div>'''}
</div>
<div class="wrap">
{"" if not conv else f'''
<section>
  <h2>Converted ({len(conv)})</h2>
  <table>
    <thead><tr>
      <th>File</th><th>Before</th><th>After</th>
      <th class="r">Size Δ</th><th class="r">Bitrate</th><th class="r">Time</th><th>Changes</th>
    </tr></thead>
    <tbody>{conv_rows}</tbody>
  </table>
</section>'''}
{"" if not errors else f'''
<section>
  <h2>Errors ({len(errors)})</h2>
  <table>
    <thead><tr><th>File</th><th>Error</th></tr></thead>
    <tbody>{err_rows}</tbody>
  </table>
</section>'''}
{"" if not skipped else f'''
<details>
  <summary>Already normalised — skipped ({len(skipped)})</summary>
  <br>
  <table>
    <thead><tr><th>File</th><th>Details</th></tr></thead>
    <tbody>{skip_rows}</tbody>
  </table>
</details>'''}
{_run_info_section(run_info)}
</div>
<footer>Generated {now} · video normalise</footer>
</body>
</html>"""


def cmd_normalise(args):
    _require("ffmpeg", "ffprobe")

    directory = args.directory
    if not os.path.isdir(directory):
        sys.exit(f"Error: not a directory: {directory}")

    cfg = _load_config(directory)
    def gcfg(section, key, fallback):
        return _vcfg(section, key, fallback, cfg=cfg)

    target_h    = int(gcfg("video.normalise", "target_height",  "720"))
    target_fmt  = gcfg("video.normalise", "format",         "mp4")
    vcodec      = gcfg("video.normalise", "video_codec",    "libx264")
    acodec      = gcfg("video.normalise", "audio_codec",    "aac")
    preset      = gcfg("video.normalise", "video_preset",   "slow")
    crf         = gcfg("video.normalise", "video_crf",      "20")
    abitrate    = gcfg("video.normalise", "audio_bitrate",  "160k")
    deinterlace = gcfg("video.normalise", "deinterlace",    "auto").lower()
    orig_dir    = os.path.expanduser(gcfg("video.normalise", "original_dir", "/tmp/video-originals"))
    report_path = args.output or os.path.join(directory, "normalise-report.html")

    want_vc = _VCODEC_PROBE.get(vcodec, vcodec)
    want_ac = _ACODEC_PROBE.get(acodec, acodec)
    target_str = f"{vcodec} h={target_h} (auto-width) / {acodec} .{target_fmt}"

    ffmpeg_ver  = _tool_version("ffmpeg")
    ffprobe_ver = _tool_version("ffprobe")
    python_ver  = f"Python {sys.version.split()[0]}"
    cfg_paths   = _find_bcconfig_files(directory)

    run_info = {
        "target_fmt":     target_fmt,
        "vcodec":         vcodec,
        "acodec":         acodec,
        "crf":            crf,
        "preset":         preset,
        "abitrate":       abitrate,
        "target_res":     f"h={target_h} (auto-width)",
        "deinterlace":    deinterlace,
        "orig_dir":       orig_dir,
        "ffmpeg_ver":     ffmpeg_ver,
        "ffprobe_ver":    ffprobe_ver,
        "python_ver":     python_ver,
        "config_files":   cfg_paths,
    }

    # ---- dry-run: assess every file and write the green/red HTML report ----
    if args.dry_run:
        print(f"Assessing  : {os.path.abspath(directory)}  (dry run — no files will be changed)")
        print(f"Target     : {target_str}")
        print()

        entries = []
        for root, dirs, files in os.walk(directory):
            dirs.sort()
            for fname in sorted(files):
                if os.path.splitext(fname)[1].lower() not in VIDEO_EXTENSIONS:
                    continue
                full_path = os.path.join(root, fname)
                rel_path  = os.path.relpath(full_path, directory)
                before = _norm_probe(full_path)
                if not before["video_codec"]:
                    print(f"  [error]   {rel_path}: probe failed or no video stream")
                    entries.append({"path": rel_path, "before": before,
                                      "error": "probe failed or no video stream"})
                    continue
                assess = _norm_assess(before, deinterlace, target_h,
                                      want_vc, want_ac, target_fmt)
                tag = "[ok]" if assess["compliant"] else "[change]"
                detail = "" if assess["compliant"] else f"  ({', '.join(assess['reasons'])})"
                print(f"  {tag:<9} {rel_path}{detail}")
                entries.append({"path": rel_path, "before": before, **assess})

        if not entries:
            sys.exit("No video files found.")

        ok_count  = sum(1 for e in entries if e.get("compliant"))
        bad_count = sum(1 for e in entries if not e.get("compliant") and not e.get("error"))
        err_count = sum(1 for e in entries if e.get("error"))

        html = _normalise_plan_html(directory, entries, target_str, run_info)
        with open(report_path, "w", encoding="utf-8") as fh:
            fh.write(html)

        print()
        print(f"Done: {ok_count} compliant, {bad_count} need changes"
              + (f", {err_count} errors" if err_count else ""))
        print(f"Report: {report_path}")
        if err_count:
            sys.exit(1)
        return

    limit = args.limit
    print(f"Normalizing : {os.path.abspath(directory)}")
    print(f"Target      : {target_str}")
    print(f"Originals   → {orig_dir}")
    print(f"Tools       : {ffmpeg_ver}  |  {ffprobe_ver}")
    if limit:
        print(f"Limit       : {limit} conversion(s)")
    print()

    results = []
    run_start = time.monotonic()
    n_converted = 0
    limit_reached = False

    for root, dirs, files in os.walk(directory):
        if limit_reached:
            break
        dirs.sort()
        for fname in sorted(files):
            if limit_reached:
                break
            if os.path.splitext(fname)[1].lower() not in VIDEO_EXTENSIONS:
                continue

            full_path = os.path.join(root, fname)
            rel_path  = os.path.relpath(full_path, directory)

            before = _norm_probe(full_path)
            if not before["video_codec"]:
                print(f"  [error]   {rel_path}: probe failed or no video stream")
                results.append({"path": rel_path, "status": "error",
                                 "before": before, "after": None, "elapsed": None,
                                 "reasons": [], "error_msg": "probe failed"})
                continue

            assess = _norm_assess(before, deinterlace, target_h,
                                  want_vc, want_ac, target_fmt)
            already_ok = assess["compliant"]

            if already_ok and not args.force:
                print(f"  [ok]      {rel_path}")
                results.append({"path": rel_path, "status": "skipped",
                                 "before": before, "after": before,
                                 "reasons": [], "elapsed": None})
                continue

            reasons = list(assess["reasons"])
            if args.force and already_ok:
                reasons.append("forced")

            remux_candidate = assess["compliant"] is False and len(assess["reasons"]) == 1 \
                              and assess["reasons"][0].startswith("format ")
            tag = "[remux]  " if remux_candidate else "[convert]"
            print(f"  {tag} {rel_path}  ({', '.join(reasons)})")

            backup_path = os.path.join(orig_dir, rel_path)
            os.makedirs(os.path.dirname(os.path.abspath(backup_path)), exist_ok=True)
            stem = _strip_emoji(os.path.splitext(fname)[0])
            out_name = stem + f".{target_fmt}"
            out_path = os.path.join(root, out_name)
            if stem != os.path.splitext(fname)[0]:
                print(f"  [rename]  {fname} → {out_name}")

            try:
                shutil.move(full_path, backup_path)

                needs_deint = any(c["label"] == "Deinterlace" and not c["ok"]
                                  for c in assess["checks"])
                needs_scale = any(c["label"] == "Resolution" and not c["ok"]
                                  for c in assess["checks"])
                needs_vcodec_enc = any(c["label"] == "Video codec" and not c["ok"]
                                       for c in assess["checks"])
                needs_acodec_enc = any(c["label"] == "Audio codec" and not c["ok"]
                                       for c in assess["checks"])

                # Stream copy (remux) when only the container format differs —
                # all streams are already the right codec and resolution.
                # This is lossless and takes seconds instead of minutes.
                remux_only = not any([needs_vcodec_enc, needs_acodec_enc,
                                      needs_scale, needs_deint])

                if remux_only:
                    cmd = ["ffmpeg", "-i", backup_path, "-c", "copy", out_path]
                else:
                    vf_parts = []
                    if needs_deint:
                        vf_parts.append("yadif=mode=0")
                    if needs_scale or needs_deint:
                        vf_parts.append(_scale_filter(target_h))
                    cmd = ["ffmpeg", "-i", backup_path]
                    if vf_parts:
                        cmd += ["-vf", ",".join(vf_parts)]
                    cmd += ["-vcodec", vcodec, "-crf", crf, "-preset", preset,
                            "-acodec", acodec, "-b:a", abitrate, out_path]

                t0 = time.monotonic()
                _run(cmd)
                elapsed = time.monotonic() - t0

                after = _norm_probe(out_path)
                print(f"             → {_fmt_elapsed(elapsed)}", end="")
                if before["duration"] and elapsed > 0:
                    print(f"  ({before['duration'] / elapsed:.1f}× realtime)", end="")
                print()
                results.append({"path": rel_path, "status": "converted",
                                 "before": before, "after": after,
                                 "reasons": reasons, "elapsed": elapsed})
                n_converted += 1
                if limit and n_converted >= limit:
                    limit_reached = True
                    break

            except Exception as exc:
                msg = str(exc)
                print(f"  [error]   {rel_path}: {msg}")
                if os.path.isfile(backup_path) and not os.path.isfile(full_path):
                    shutil.move(backup_path, full_path)
                    print(f"            original restored")
                results.append({"path": rel_path, "status": "error",
                                 "before": before, "after": None,
                                 "reasons": reasons, "elapsed": None, "error_msg": msg})

    total_elapsed = time.monotonic() - run_start
    conv    = sum(1 for r in results if r["status"] == "converted")
    skipped = sum(1 for r in results if r["status"] == "skipped")
    errors  = sum(1 for r in results if r["status"] == "error")

    print()
    if limit_reached:
        print(f"Limit reached ({limit}). Re-run to continue processing remaining files.")
    print(f"Done: {conv} converted, {skipped} skipped, {errors} errors  ({_fmt_elapsed(total_elapsed)})")

    run_info["total_elapsed"] = _fmt_elapsed(total_elapsed)

    html = _normalise_html(directory, results, target_str, orig_dir, args.dry_run, run_info)
    with open(report_path, "w", encoding="utf-8") as fh:
        fh.write(html)
    print(f"Report: {report_path}")

    if errors:
        sys.exit(1)


# ---------------------------------------------------------------------------
# CLI
# ---------------------------------------------------------------------------

def build_parser():
    parser = argparse.ArgumentParser(
        prog="video",
        description=__doc__,
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    sub = parser.add_subparsers(dest="command", metavar="SUBCOMMAND")
    sub.required = True

    # formats
    p = sub.add_parser("formats",
                       help="explain supported formats and codecs, check ffmpeg availability")
    p.add_argument("--all", action="store_true",
                   help="also list every encoder available in the installed ffmpeg")

    # info
    p = sub.add_parser("info", help="print detailed file, container and stream information")
    p.add_argument("file", metavar="FILE")
    p.add_argument("--json", action="store_true",
                   help="dump raw ffprobe JSON instead of formatted output")

    # convert
    default_fmt = _vcfg("video", "default_format", "mp4")
    p = sub.add_parser("convert",
                       help="transcode a file using config defaults (all overridable via args)")
    p.add_argument("file", metavar="FILE")
    p.add_argument("-f", "--format", default=default_fmt, metavar="FORMAT",
                   help=f"container format: mp4, mkv, mov, webm (config: {default_fmt})")
    p.add_argument("-H", "--height", default=None, metavar="PX", type=int,
                   help="scale to this height in pixels, maintaining aspect ratio")
    p.add_argument("--vcodec", default=None, metavar="CODEC",
                   help=f"video codec (config: {_vcfg('video.convert','video_codec','libx264')})")
    p.add_argument("--acodec", default=None, metavar="CODEC",
                   help=f"audio codec (config: {_vcfg('video.convert','audio_codec','aac')})")
    p.add_argument("--crf", default=None, metavar="N", type=int,
                   help=f"CRF quality, lower=better (config: {_vcfg('video.convert','video_crf','20')})")
    p.add_argument("--preset", default=None, metavar="PRESET",
                   help=f"encoding preset (config: {_vcfg('video.convert','video_preset','slow')})")
    p.add_argument("--abitrate", default=None, metavar="RATE",
                   help=f"audio bitrate (config: {_vcfg('video.convert','audio_bitrate','160k')})")
    p.add_argument("-o", "--output", default=None, metavar="OUTPUT")

    # concat
    p = sub.add_parser("concat", help="join videos of the same format and resolution")
    p.add_argument("-o", "--output", default=None, metavar="OUTPUT",
                   help="output filename (default: output.mp4)")
    p.add_argument("files", nargs="+", metavar="FILE")

    # clamp
    p = sub.add_parser("clamp", help="cut to a time range (start and/or end optional)")
    p.add_argument("-s", "--start", default=None, metavar="TIME",
                   help="start time as HH:MM:SS or seconds (default: beginning of file)")
    p.add_argument("-e", "--end", default=None, metavar="TIME",
                   help="end time as HH:MM:SS or seconds (default: end of file)")
    p.add_argument("-o", "--output", default=None, metavar="OUTPUT")
    p.add_argument("file", metavar="FILE")

    # thumb
    p = sub.add_parser("thumb", help="extract a single frame as a PNG image")
    p.add_argument("-t", "--time", default=None, metavar="TIME",
                   help="timestamp to grab (default: 00:00:01)")
    p.add_argument("-H", "--height", default=None, metavar="PX", type=int,
                   help="scale to this height in pixels, maintaining aspect ratio")
    p.add_argument("-o", "--output", default=None, metavar="OUTPUT")
    p.add_argument("file", metavar="FILE")

    # catalog
    p = sub.add_parser("catalog",
                       help="scan a directory tree and write an HTML report")
    p.add_argument("directory", metavar="DIR",
                   help="root directory to scan recursively")
    p.add_argument("-o", "--output", default=None, metavar="OUTPUT",
                   help="output HTML file (default: catalog.html)")

    # normalise
    p = sub.add_parser("normalise",
                       help="batch-normalise a directory tree to a web-friendly format")
    p.add_argument("directory", metavar="DIR",
                   help="root directory to scan and normalise recursively")
    p.add_argument("-n", "--dry-run", action="store_true",
                   help="scan and assess without converting: writes a full HTML report "
                        "showing green/red compliance per criterion for every file")
    p.add_argument("-l", "--limit", type=int, default=None, metavar="N",
                   help="stop after converting N files; re-run to continue "
                        "(skipped/already-ok files do not count toward the limit)")
    p.add_argument("-f", "--force", action="store_true",
                   help="re-process files that already appear normalised")
    p.add_argument("-o", "--output", default=None, metavar="OUTPUT",
                   help="HTML report path (default: DIR/normalise-report.html)")

    return parser


def main():
    if len(sys.argv) == 2 and sys.argv[1] == "--bc-metadata":
        print(json.dumps(bc_metadata(), indent=2, sort_keys=True))
        return

    parser = build_parser()
    args = parser.parse_args()

    dispatch = {
        "catalog":   cmd_catalog,
        "formats":   cmd_formats,
        "concat":    cmd_concat,
        "convert":   cmd_convert,
        "info":      cmd_info,
        "normalise": cmd_normalise,
        "thumb":     cmd_thumb,
        "clamp":     cmd_clamp,
    }
    dispatch[args.command](args)


if __name__ == "__main__":
    main()