avi2atari.py

#!/usr/bin/env python3

# avi2atari.py - Atari 8-bit AVF Video Converter
# Copyright (C) 2026 HanJammer & Lumen
#
# A modern, all-in-one converter for AVF/BIN format on Atari 8-bit computers.
# Supports both PAL (50Hz) and NTSC (60Hz) output standards.
#
# Key Features:
# - Single file processing
# - Batch processing (directory support)
# - URL support (YouTube and direct video links) via yt-dlp
# - URL List processing via text file (--urllist filename.txt)
# - Downloads are saved to 'downloads/' folder and preserved
# - EBU R128 Audio Loudness Normalization (prevents silence or clipping on 8-bit DACs)
# - Error diffusion dithering (Floyd-Steinberg derivative)
# - Strict file structure integrity checks (prevents sync drift)
# - Auto-generation of silence for video-only inputs
# - Built-in test signal generator
#
# Original Concept: phaeron encvideo/encaudio/mux C++ sources)
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <https://www.gnu.org/licenses/>.

import sys
import os
import subprocess
import argparse
import glob
import time
import shutil
import numpy as np
import math
try:
    from numba import jit, prange
    NUMBA_OK = True
except ImportError:
    # Numba is an accelerator, not a requirement: fall back to plain Python
    # (an order of magnitude slower, but correct) so mismatched numpy/numba
    # installs never block a conversion outright. EXCEPTION: the c80btc
    # exhaustive search is ~1000x slower un-jitted (~7.5 s/frame = 6+ hours
    # per minute of PAL video) - main() refuses it without --allow-slow.
    NUMBA_OK = False
    def jit(*_args, **_kwargs):
        def _deco(fn):
            return fn
        return _deco
    prange = range
    print("WARNING: numba unavailable - encoding runs unaccelerated (slow).")

__version__ = "0.9"

import avf_format as avf

# Try importing yt_dlp for URL support
try:
    import yt_dlp
    YT_DLP_AVAILABLE = True
except ImportError:
    YT_DLP_AVAILABLE = False

# --- AVF FORMAT CONFIGURATION ---
# All container constants now live in avf_format (the shared PC-suite lib);
# these are aliases so the converter body reads the same as before.
HEIGHT = avf.HEIGHT
WIDTH = avf.WIDTH
FRAME_SIZE_BYTES = avf.FRAME_SIZE_APAC   # 17 sectors; byte-aligned or it drifts
C80_FRAME_SIZE = avf.FRAME_SIZE_C80      # 7680 video + 512 linear audio
PROFILE_APAC = avf.PROFILE_APAC
PROFILE_C80M3 = avf.PROFILE_C80M3
PROFILE_C80M4 = avf.PROFILE_C80M4
C80_HALFBLOCK = avf.C80_HALFBLOCK
SECONDS_PER_FRAME_PAL = avf.SECONDS_PER_FRAME_PAL
SECONDS_PER_FRAME_NTSC = avf.SECONDS_PER_FRAME_NTSC


# --- C80/BTC ORDERED DITHER -------------------------------------------------
# Standard 8x8 Bayer ranks.  A 4x4 tile resonates with the 2x4 BTC cell:
# every cell row sees the same vertical phase and only two horizontal cell
# fragments repeat across the screen.  8x8 gives eight distinct aligned 2x4
# fragments (4 cell phases horizontally x 2 vertically), reducing that grid.
BTC_BAYER8 = np.array([
    [ 0, 32,  8, 40,  2, 34, 10, 42],
    [48, 16, 56, 24, 50, 18, 58, 26],
    [12, 44,  4, 36, 14, 46,  6, 38],
    [60, 28, 52, 20, 62, 30, 54, 22],
    [ 3, 35, 11, 43,  1, 33,  9, 41],
    [51, 19, 59, 27, 49, 17, 57, 25],
    [15, 47,  7, 39, 13, 45,  5, 37],
    [63, 31, 55, 23, 61, 29, 53, 21],
], dtype=np.float32)
BTC_BAYER8_CENTERED = (BTC_BAYER8 + 0.5) / 64.0 - 0.5


# Variance gate ramp: cells whose internal detail (mean per-channel std over
# the 8 subpixels) is below GATE_LO get the full dither (they are flat -
# gradients, sky - where banding lives); above GATE_HI they get none (the
# masks are busy encoding REAL detail there and dither grain would only
# compete with it); in between the amplitude ramps down linearly, so there
# is no visible seam between gated and ungated cells.
BTC_GATE_LO = 8.5               # half a quant step of internal variation
BTC_GATE_HI = 34.0              # two quant steps -> clearly detailed


def apply_btc_ordered_dither(rgb, mode="none", frame_index=0, strength=1.0,
                             gate=False):
    """Return the C80/BTC target with an absolute-coordinate Bayer offset.

    ``strength=1`` spans one RGB444 quantisation step peak-to-peak: the
    midpoint-normalised 8x8 ranks produce offsets just inside +/-8.5.  The
    SAME scalar offset is added to R/G/B, avoiding independent-channel chroma
    speckle.  Static ``bayer`` is screen-anchored; ``bayer-t`` shifts the tile
    one subpixel right per frame and repeats after eight frames.

    ``gate=True`` enables the variance gate: the offset is attenuated per
    2x4 cell by how much real detail the CLEAN cell already carries (see
    BTC_GATE_LO/HI), resolving the masks-vs-dither trade - flat areas get
    smooth gradients, detailed areas keep their masks crisp.

    Dithering happens after FFmpeg scale/denoise/contrast/saturation and before
    the exhaustive BTC search, so masks and both RGB444 colours are judged
    against the same dithered target.  The caller keeps the clean target for
    the classic AVF2 poster.
    """
    if mode == "none" or strength <= 0.0:
        return rgb
    if mode not in ("bayer", "bayer-t"):
        raise ValueError(f"unknown BTC dither mode: {mode}")
    h, w = rgb.shape[:2]
    phase = (int(frame_index) & 7) if mode == "bayer-t" else 0
    yy = np.arange(h, dtype=np.int32)[:, None] & 7
    # np.roll(tile, +phase): the old x sample moves one pixel right/frame.
    xx = (np.arange(w, dtype=np.int32)[None, :] - phase) & 7
    offset = BTC_BAYER8_CENTERED[yy, xx] * (17.0 * float(strength))
    if gate:
        # per-cell detail of the clean target: (24,4,80,2,3) std over the
        # 8 subpixels, averaged across channels -> (24,80)
        cells = rgb.reshape(24, 4, 80, 2, 3)
        detail = cells.std(axis=(1, 3)).mean(axis=-1)
        att = np.clip((BTC_GATE_HI - detail) / (BTC_GATE_HI - BTC_GATE_LO),
                      0.0, 1.0)
        offset = offset * np.repeat(np.repeat(att, 4, 0), 2, 1)
    return np.clip(rgb + offset[:, :, None], 0.0, 255.0).astype(np.float32)


def build_settings_comment(config):
    """Default AVF2 comment: the conversion settings, compactly.

    Used when the user gives no --comment, so every file self-documents
    how it was made. Defaults (1.0 gains, stretch, no denoise) are
    omitted to keep it short; the audio mode is always included."""
    parts = []
    if config.get('profile') == PROFILE_C80M4:
        parts.append('c80btc' if config.get('c80_btc') else 'c80m4')
    else:
        parts.append('apac')
    if config.get('c80_btc'):
        parts.append(f"stab={float(config.get('btc_stability', 0.0)):.2f}")
        dither = config.get('btc_dither', 'none')
        if dither != 'none':
            s = float(config.get('btc_dither_strength', 0.5))
            parts.append(f"dither={dither}@{s:g}"
                         + ("+gate" if config.get('btc_dither_gate') else ""))
    if config.get('denoise'):
        parts.append('denoise')
    if float(config.get('saturation', 1.0)) != 1.0:
        parts.append(f"sat={float(config['saturation']):g}")
    if float(config.get('contrast', 1.0)) != 1.0:
        parts.append(f"con={float(config['contrast']):g}")
    if config.get('aspect') == 'fit':
        parts.append('fit')
    if config.get('loudnorm'):
        parts.append('loudnorm')
    else:
        parts.append(f"vol={float(config.get('volume', 0.0)):g}dB")
    return " ".join(parts)


# --- AVF2 METADATA HEADER --- (built by the shared avf_format lib)
def build_avf2_header(is_pal, frame_count, poster_data, meta,
                      profile=PROFILE_APAC, c80_btc=False):
    # Thin wrapper over avf_format; the converter stamps its own version.
    m = dict(meta or {})
    m["converter"] = f"avi2atari {__version__}"
    return avf.build_avf2_header(is_pal, frame_count, poster_data, m, profile,
                                 c80_btc)


def probe_duration_seconds(input_file):
    # Best-effort media duration via ffprobe (ships with FFmpeg). None on failure.
    try:
        out = subprocess.run(
            ['ffprobe', '-v', 'error', '-show_entries', 'format=duration',
             '-of', 'csv=p=0', input_file],
            capture_output=True, text=True, check=True
        ).stdout.strip()
        return float(out)
    except (subprocess.CalledProcessError, FileNotFoundError, ValueError):
        return None

# --- PHASE TABLES (Precomputed) ---
# Atari generates colors via phase shift (Hue) and amplitude (Saturation).
# These tables map the digital color space to Atari's analog I/Q signal.
ITAB_PAL = np.zeros(16, dtype=np.float32)
QTAB_PAL = np.zeros(16, dtype=np.float32)
ITAB_NTSC = np.zeros(16, dtype=np.float32)
QTAB_NTSC = np.zeros(16, dtype=np.float32)

def init_tables():
    # Generates lookup tables for color conversion (Phase Shift).
    # PAL: 14 color cycles
    for i in range(15):
        ITAB_PAL[i+1] = 40.0 * math.cos(3.1415926535 * (float(i) + 0.5) / 7.0)
        QTAB_PAL[i+1] = 40.0 * math.sin(3.1415926535 * (float(i) + 0.5) / 7.0)
    # NTSC: 15 color cycles
    for i in range(15):
        ITAB_NTSC[i+1] = 40.0 * math.cos(3.1415926535 * float(i) / 7.5)
        QTAB_NTSC[i+1] = 40.0 * math.sin(3.1415926535 * float(i) / 7.5)

init_tables()

# --- AUDIO KERNEL (Numba JIT) ---
@jit(nopython=True, fastmath=True)
def encode_audio_chunk(audio_data):
    # Converts raw audio (8-bit Unsigned) to Atari POKEY format (4-bit PWM-ish).
    # Mapping: PC 0..255 -> Atari 0..100.
    # Uses simple linear scaling consistent with the original C++ encoder.
    out = np.zeros(len(audio_data), dtype=np.uint8)
    for i in range(len(audio_data)):
        val = int(audio_data[i])
        # Scaling: input 0-255 -> output 0-100
        out_val = (val * 100) // 255
        out[i] = out_val
    return out

# --- C80M4 VIDEO KERNEL (Numba JIT) ---
@jit(nopython=True, fastmath=True)
def encode_c80m4_frame(rgb):
    # rgb: float32 (48, 80, 3), 0..255. Serpentine Floyd-Steinberg dither
    # down to RGB444, then packed into the 24-row cell layout.
    q = np.zeros((48, 80, 3), dtype=np.uint8)
    work = rgb.copy()
    for y in range(48):
        if y % 2 == 0:
            xs, xe, xd = 0, 80, 1
        else:
            xs, xe, xd = 79, -1, -1
        for x in range(xs, xe, xd):
            for c in range(3):
                v = work[y, x, c]
                qq = int(round(v / 17.0))
                if qq < 0:
                    qq = 0
                if qq > 15:
                    qq = 15
                q[y, x, c] = qq
                e = v - qq * 17.0
                if 0 <= x + xd < 80:
                    work[y, x + xd, c] += e * 0.4375        # 7/16
                if y + 1 < 48:
                    work[y + 1, x, c] += e * 0.3125         # 5/16
                    if 0 <= x - xd < 80:
                        work[y + 1, x - xd, c] += e * 0.1875  # 3/16
                    if 0 <= x + xd < 80:
                        work[y + 1, x + xd, c] += e * 0.0625  # 1/16
    out = np.zeros(7680, dtype=np.uint8)
    for r in range(24):
        base = r * 320
        top = 2 * r          # top pixel -> BG (high nibble)
        bot = 2 * r + 1      # bottom pixel -> FG (low nibble)
        for x in range(80):
            out[base + x] = C80_HALFBLOCK
            out[base + 80 + x] = (q[top, x, 0] << 4) | q[bot, x, 0]
            out[base + 160 + x] = (q[top, x, 1] << 4) | q[bot, x, 1]
            out[base + 240 + x] = (q[top, x, 2] << 4) | q[bot, x, 2]
    return out.reshape((192, 40))

# --- C80/BTC VIDEO KERNEL (Numba JIT, parallel over cell rows) ---
@jit(nopython=True, fastmath=True, parallel=True)
def encode_c80btc_frame(rgb, leg_bg, leg_fg, prev_mask, prev_bg, prev_fg,
                        prev_valid, stability):
    # rgb: float32 (96, 160, 3), 0..255 - the 160x96 subpixel source.
    # leg_bg/leg_fg: uint8 (24, 80, 3) RGB444 - the HALFBLOCK BASELINE for
    # the same 160x96 target (the classic encoder run on a box-2x2 downscale
    # of it). NOTE: this is NOT byte-identical to a direct `--profile c80m4`
    # run, whose ffmpeg scales the source straight to 80x48 with lanczos -
    # the guarantee below is relative to the 160x96 reference, not to the
    # old pipeline's bytes (Codex implementation review, P1).
    #
    # Per 2x4-subpixel cell: exhaustive search over the 128 unique
    # partitions (mask and complement describe the same split), colours =
    # per-side means QUANTISED to RGB444 before the error is measured
    # (SSE in 0..255 RGB). The halfblock baseline (mask $F0 + its colours)
    # seeds the search, so the result can never score worse than that
    # baseline under this error function. Finally the free complement+swap
    # picks the BG/FG orientation that the legacy half-block fallback
    # (old players: BG top / FG bottom) renders best.
    # Stateless by design (Codex review: temporal damping is phase 2).
    #
    # PHASE 2 - temporal hysteresis (encoder-only; the format, decoders and
    # the Atari player are untouched): prev_mask (24,80) u8 + prev_bg/fg
    # (24,80,3) u8 carry the previous frame's chosen cells. When
    # prev_valid == 1 and the previous cell's error on the CURRENT block is
    # <= best_err * (1 + stability), the previous cell is kept verbatim -
    # static areas stop flickering, and the spatial regression is bounded
    # by the stability factor per cell. prev_valid == 0 (or stability <= 0
    # at the call site) disables the path entirely = the stateless v1.
    # A scene cut self-heals: the old cell's error explodes past the bound
    # and the stateless winner replaces it. The arrays are updated in
    # place with each cell's final choice.
    #
    # Working state lives in small typed arrays (best/cand), not scalar
    # locals: numba 0.60's scalar SSA unification mistyped the scalar
    # version (or_(float64, int64) at the nibble pack).
    out = np.zeros(7680, dtype=np.uint8)
    for cy in prange(24):
        # per-iteration (= per-thread) work buffers: cells are fully
        # independent, so rows parallelise cleanly - each cell only reads
        # and writes its own prev_* slot
        px = np.zeros((8, 3), dtype=np.float32)
        best = np.zeros(6, dtype=np.int32)    # bg r,g,b | fg r,g,b
        cand = np.zeros(6, dtype=np.int32)
        base = cy * 320
        for cx in range(80):
            for r in range(4):
                for c in range(2):
                    for k in range(3):
                        px[r * 2 + c, k] = rgb[cy * 4 + r, cx * 2 + c, k]

            # seed: the classic C80 cell (mask $F0, legacy colours)
            best_mask = 0xF0
            for k in range(3):
                best[k] = leg_bg[cy, cx, k]
                best[3 + k] = leg_fg[cy, cx, k]
            best_err = 0.0
            for i in range(8):
                o = 3 if i >= 4 else 0     # $F0: bits 4-7 = FG
                for k in range(3):
                    d = px[i, k] - best[o + k] * 17.0
                    best_err += d * d

            # exhaustive: masks 0..127 cover every partition exactly once
            # (bit 7 clear -> subpixel 7 always on the "clear" side)
            for m in range(128):
                ns = 0
                s0 = 0.0; s1 = 0.0; s2 = 0.0
                c0 = 0.0; c1 = 0.0; c2 = 0.0
                for i in range(8):
                    if (m >> i) & 1:
                        s0 += px[i, 0]; s1 += px[i, 1]; s2 += px[i, 2]
                        ns += 1
                    else:
                        c0 += px[i, 0]; c1 += px[i, 1]; c2 += px[i, 2]
                nc = 8 - ns
                if nc > 0:
                    c0 /= nc; c1 /= nc; c2 /= nc
                if ns > 0:
                    s0 /= ns; s1 /= ns; s2 /= ns
                else:
                    s0 = c0; s1 = c1; s2 = c2
                # quantise both colours to RGB444 first, judge after
                cand[3] = min(15, max(0, int(s0 / 17.0 + 0.5)))
                cand[4] = min(15, max(0, int(s1 / 17.0 + 0.5)))
                cand[5] = min(15, max(0, int(s2 / 17.0 + 0.5)))
                cand[0] = min(15, max(0, int(c0 / 17.0 + 0.5)))
                cand[1] = min(15, max(0, int(c1 / 17.0 + 0.5)))
                cand[2] = min(15, max(0, int(c2 / 17.0 + 0.5)))
                err = 0.0
                for i in range(8):
                    o = 3 if (m >> i) & 1 else 0
                    for k in range(3):
                        d = px[i, k] - cand[o + k] * 17.0
                        err += d * d
                    if err >= best_err:
                        break
                if err < best_err:
                    best_err = err
                    best_mask = m
                    for k in range(6):
                        best[k] = cand[k]

            # orientation: complement+swap is free for BTC-aware playback;
            # pick the one the legacy half-block fallback renders better
            # (old players show BG on the top rows, FG on the bottom rows)
            fa = 0.0
            fb = 0.0
            for i in range(8):
                oa = 0 if i < 4 else 3
                ob = 3 if i < 4 else 0
                for k in range(3):
                    d = px[i, k] - best[oa + k] * 17.0
                    e = px[i, k] - best[ob + k] * 17.0
                    fa += d * d
                    fb += e * e
            if fb < fa:
                best_mask = best_mask ^ 0xFF
                for k in range(3):
                    t = best[k]
                    best[k] = best[3 + k]
                    best[3 + k] = t

            # temporal hysteresis: keep the previous frame's cell when it
            # still explains the current block within the stability bound
            if prev_valid == 1:
                pm = prev_mask[cy, cx]
                perr = 0.0
                for i in range(8):
                    if (pm >> i) & 1:
                        for k in range(3):
                            d = px[i, k] - prev_fg[cy, cx, k] * 17.0
                            perr += d * d
                    else:
                        for k in range(3):
                            d = px[i, k] - prev_bg[cy, cx, k] * 17.0
                            perr += d * d
                if perr <= best_err * (1.0 + stability):
                    best_mask = pm
                    for k in range(3):
                        best[k] = prev_bg[cy, cx, k]
                        best[3 + k] = prev_fg[cy, cx, k]

            prev_mask[cy, cx] = best_mask
            for k in range(3):
                prev_bg[cy, cx, k] = best[k]
                prev_fg[cy, cx, k] = best[3 + k]

            out[base + cx] = best_mask
            out[base + 80 + cx] = (best[0] << 4) | best[3]
            out[base + 160 + cx] = (best[1] << 4) | best[4]
            out[base + 240 + cx] = (best[2] << 4) | best[5]
    return out.reshape((192, 40))

# --- VIDEO KERNEL (Numba JIT) ---
@jit(nopython=True, fastmath=True)
def encode_video_frame(y_plane, u_plane, v_plane, errfi, errfq, errfy, is_pal):
    # Main video encoding engine.
    # Performs:
    # 1. YUV -> Atari I/Q conversion (Phase/Amplitude)
    # 2. GTIA palette matching (16 hues / 16 luma levels)
    # 3. Dithering (Error diffusion)
    # 4. Bit packing (2 pixels per byte)
    output = np.zeros((HEIGHT, 40), dtype=np.uint8)

    # Local error buffers for dithering (reset per frame/line logic)
    perr = np.zeros(82, dtype=np.int32)
    nerr = np.zeros(82, dtype=np.int32)
    pcerr = np.zeros(82, dtype=np.float32)
    ncerr = np.zeros(82, dtype=np.float32)
    pserr = np.zeros(82, dtype=np.float32)
    nserr = np.zeros(82, dtype=np.float32)

    ITAB = ITAB_PAL if is_pal else ITAB_NTSC
    QTAB = QTAB_PAL if is_pal else QTAB_NTSC

    for y in range(HEIGHT):
        # Atari in AVF mode interleaves Chroma (Color) and Luma (Brightness) lines.
        # PAL: Even=Chroma, Odd=Luma
        # NTSC: Odd=Chroma, Even=Luma (due to different signal structure)
        is_chroma = (y % 2 == 0) if is_pal else (y % 2 != 0)

        if is_chroma:
            # --- CHROMA PROCESSING (COLOR) ---
            ncerr[:] = 0
            nserr[:] = 0
            # Serpentine scanning (left-to-right, then right-to-left) reduces dither artifacts
            direction = -1 if (y & 2) else 1
            start_x = 0 if direction == 1 else 79
            chroma_y = y // 2
            accum = 0

            # IMPORTANT - two distinct index spaces are in play here:
            #   i = scan index  (0..79, always advances in scan order)
            #   x = screen column (i counted from the left or the right)
            # The error buffers are indexed by SCAN index, never by column. That is
            # what makes the mirrored write pattern below correct: because the next
            # line is scanned in the opposite direction, "the pixel below" is at
            # scan index 79-i there, so 80-i is where its weight-5 share must land.
            # Indexing these buffers by column instead silently diffuses every
            # line's error onto the horizontally mirrored part of the next line.
            for i in range(80):
                x = start_x + (i * direction)
                u_val = int(u_plane[chroma_y, x]) - 128
                v_val = int(v_plane[chroma_y, x]) - 128
                fu = float(u_val)
                fv = float(v_val)

                # YUV to I/Q conversion matrix
                if is_pal:
                    red = 1.596 * fv
                    grn = -0.391 * fu - 0.813 * fv
                    blu = 2.017 * fu
                else:
                    red = 1.396 * fv
                    grn = -0.342 * fu - 0.711 * fv
                    blu = 1.765 * fu

                fi = (0.595*red - 0.274*grn - 0.321*blu) + pcerr[i + 1] / 25.0 + errfi[y, x]
                fq = (0.211*red - 0.522*grn + 0.311*blu) + pserr[i + 1] / 25.0 + errfq[y, x]

                satsq = fi*fi + fq*fq

                # Phase calculation (Hue)
                if is_pal:
                    rawhue = math.atan2(fq, fi) * (7.0 / 3.1415926535) - 0.5
                else:
                    rawhue = math.atan2(fq, fi) * (7.5 / 3.1415926535) + 2.0

                ihue = int(math.floor(rawhue + 0.5))
                cycle = 14 if is_pal else 15
                offset = 14000 if is_pal else 15000
                color = ((ihue + offset) % cycle) + 1
                out_color = 0

                # Saturation threshold (40.0^2 = 1600). Below this, color is rendered as gray.
                # This prevents excessive color noise in dark areas.
                if satsq > 1600.0:
                    out_color += color
                    sc = 40.0 / math.sqrt(satsq)
                    fi *= sc
                    fq *= sc

                # Quantization error calculation
                ierror = fi - ITAB[out_color]
                qerror = fq - QTAB[out_color]

                # Error propagation to next pixels and lines (Floyd-Steinberg variant).
                # errf* is the TEMPORAL term (9/25 of the error carried to the same
                # pixel in the next frame), so it is keyed by column - a given line
                # always scans the same way, so column and scan index stay in step
                # from frame to frame either way.
                errfi[y, x] = ierror * 0.36
                errfq[y, x] = qerror * 0.36

                pcerr[i + 2] += ierror * 7.0
                ncerr[81 - i] += ierror * 3.0
                ncerr[80 - i] += ierror * 5.0
                ncerr[79 - i] += ierror

                pserr[i + 2] += qerror * 7.0
                nserr[81 - i] += qerror * 3.0
                nserr[80 - i] += qerror * 5.0
                nserr[79 - i] += qerror

                # Packing 4-bit nibbles into a byte
                if direction < 0:
                    accum = ((accum >> 4) + (out_color << 4)) & 0xFF
                else:
                    accum = ((accum << 4) + out_color) & 0xFF

                if (i % 2) == 1:
                    output[y, x // 2] = accum

            pcerr[:] = ncerr
            pserr[:] = nserr

        else:
            # --- LUMA PROCESSING (BRIGHTNESS) ---
            nerr[:] = 0
            direction = -1 if (y & 2) else 1
            start_x = 0 if direction == 1 else 79
            accum = 0

            # Luma/chroma registration. Output line pair number n is carried by the
            # chroma line at 2n and the luma line at 2n+1 (PAL) or by the luma line
            # at 2n and the chroma line at 2n+1 (NTSC). The 4:2:0 chroma plane row n
            # covers source rows 2n and 2n+1, so the luma line must average that
            # SAME row pair or the two planes drift apart by one source line.
            # PAL luma rows are odd, so they have to look one row back.
            base_y = (y - 1) if is_pal else y
            if base_y < 0:
                base_y = 0
            if base_y > HEIGHT - 2:
                base_y = HEIGHT - 2

            # See the note in the chroma branch: error buffers use the SCAN index i,
            # pixel and output access use the screen column x.
            for i in range(80):
                x = start_x + (i * direction)
                base_x = x * 2

                # Luma sampling (2x2 averaging for stability)
                p0 = int(y_plane[base_y, base_x])
                p1 = int(y_plane[base_y, base_x + 1])
                p2 = int(y_plane[base_y + 1, base_x])
                p3 = int(y_plane[base_y + 1, base_x + 1])

                # Scale YUV range (16-235) to full range (0-255)
                val_a = (((p0 + p1 + p2 + p3 - 64) * 255 + 438) // 876)

                diff = (perr[i + 1] + errfy[y, x]) / 25.0
                val_a += int(diff)

                if val_a < 0: val_a = 0
                if val_a > 255: val_a = 255

                # Quantize to 16 brightness levels (4-bit)
                val_b = int((val_a + 8) // 17)
                if val_b < 0: val_b = 0
                if val_b > 15: val_b = 15

                val_c = val_b * 17
                err = val_a - val_c

                errfy[y, x] = float(err * 9)
                perr[i + 2] += int(err * 7)
                nerr[81 - i] += int(err * 3)
                nerr[80 - i] += int(err * 5)
                nerr[79 - i] += int(err)

                if direction < 0:
                    accum = ((accum >> 4) + (val_b << 4)) & 0xFF
                else:
                    accum = ((accum << 4) + val_b) & 0xFF

                if (i % 2) == 1:
                    output[y, x // 2] = accum

            temp = perr
            perr = nerr
            nerr = temp

    return output

# --- MUXING (STREAM INTERLEAVING) ---
def mux_frame(fout, vbuf, abuf, is_pal):
    # Writes one video and audio frame in the interleaved AVF format.
    # The format is rigid - 8704 bytes per frame.
    # Video is split into blocks of 3 lines, interleaved with audio data.
    v_flat = vbuf.flatten()

    # 1. VIDEO PART (Video Blocks)
    # Video: 192 lines / 3 = 64 blocks.
    # Each video block is padded with zeroes.
    for y in range(0, 192, 3):
        fout.write(b'\x00')
        fout.write(v_flat[y*40 : (y+1)*40])
        fout.write(b'\x00\x00\x00')
        fout.write(b'\x00')
        fout.write(v_flat[(y+1)*40 : (y+2)*40])
        fout.write(b'\x00\x00\x00')
        fout.write(v_flat[(y+2)*40 : (y+3)*40])

    # 2. AUDIO PART (Audio Blocks at the end of the frame)
    # Audio data is "smeared" in a specific pattern so the CPU can read it in time.
    off1 = 120 if is_pal else 70
    off2 = 52

    # Audio Loop 1 (32 audio lines)
    for y in range(32):
        fout.write(bytes([abuf[y]]))
        fout.write(bytes([abuf[y + 0*32 + off1]]))
        fout.write(bytes([abuf[y + 1*32 + off1]]))
        fout.write(bytes([abuf[y + 2*32 + off1]]))
        fout.write(bytes([abuf[y + 3*32 + off1]]))
        fout.write(bytes([abuf[y + 4*32 + off1]]))
        fout.write(bytes([abuf[y + 5*32 + off1]]))
        fout.write(bytes([abuf[y + 0*32 + off2]]))
        fout.write(bytes([abuf[y + 1*32 + off2]]))
        fout.write(b'\x00')

    # Audio Loop 2 (19 audio lines)
    # NOTE: The padding difference between PAL and NTSC is critical for sync!
    for y in range(19):
        fout.write(bytes([abuf[y+32]]))
        if is_pal:
            # PAL: 1 byte data + 1 byte data + 8 zeroes = 10 bytes
            fout.write(bytes([abuf[y + 2*32 + off2]]))
            fout.write(b'\x00' * 8)
        else:
            # NTSC: 1 byte data + 9 zeroes = 10 bytes
            fout.write(b'\x00' * 9)

    # End (Padding to fill the sector)
    fout.write(bytes([abuf[51]]))
    fout.write(b'\x00')

# --- DOWNLOADER UTILS ---
def download_media(url):
    # Downloads video from URL using yt-dlp.
    # Saves to 'downloads' directory.
    # Returns the path to the downloaded file and the video title.
    if not YT_DLP_AVAILABLE:
        print("ERROR: yt-dlp is not installed. Please install it with: pip install yt-dlp")
        sys.exit(1)

    print(f"--- Downloading from URL: {url} ---")

    # Ensure downloads directory exists
    download_dir = os.path.join(os.getcwd(), "downloads")
    os.makedirs(download_dir, exist_ok=True)

    # Prefer a single muxed MP4 and force an mp4 container. Modern YouTube
    # serves DASH (separate video+audio) whose merged file often does NOT
    # match prepare_filename()'s guessed extension - the classic "downloaded
    # but no file" trap. merge_output_format pins it, and we also fall back
    # to the newest file actually written to the download dir.
    ydl_opts = {
        'format': 'bestvideo[ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]/best',
        'merge_output_format': 'mp4',
        'outtmpl': os.path.join(download_dir, '%(title)s.%(ext)s'),
        'quiet': False,
        'no_warnings': True,
        'restrictfilenames': True,   # ASCII-only filenames
    }

    before = set(os.listdir(download_dir))
    with yt_dlp.YoutubeDL(ydl_opts) as ydl:
        try:
            info = ydl.extract_info(url, download=True)
            title = info.get('title', 'video')
            filename = ydl.prepare_filename(info)
            if not os.path.exists(filename):
                # merge/postprocess changed the extension: take the newest
                # file that appeared in the download dir during this call.
                fresh = [os.path.join(download_dir, f)
                         for f in os.listdir(download_dir) if f not in before]
                cand = fresh or [os.path.join(download_dir, f)
                                 for f in os.listdir(download_dir)]
                if not cand:
                    print("Error downloading URL: no file was written")
                    return None, None
                filename = max(cand, key=os.path.getmtime)
            sanitized_title = "".join(
                c for c in title
                if c.isalpha() or c.isdigit() or c in ' .-_').strip()
            return filename, sanitized_title
        except Exception as e:
            print(f"Error downloading URL: {e}")
            return None, None

# --- MAIN PROCESSING LOGIC ---
def process_single_file(input_file, system, output_file, config):
    print(f"\n>>> Converting: {input_file} -> {output_file}")

    is_pal = (system == "PAL")
    fps = "49.86" if is_pal else "59.92"
    audio_rate = "15557" if is_pal else "15700" # Sample rates consistent with VirtualDub
    audio_chunk_size = 312 if is_pal else 262

    # Using temporary files instead of pipes for stability.
    pid = os.getpid()
    temp_vid = f"temp_v_{pid}.raw"
    temp_aud = f"temp_a_{pid}.raw"

    # --- 1. FFMPEG FILTERS ---
    # Force the output colour matrix to BT.601 ("smpte170m"). The downstream
    # YUV->I/Q conversion in encode_video_frame is hard-coded to BT.601
    # coefficients; modern HD content is usually tagged BT.709 and would yield
    # subtly off greens/skin tones if fed through unconverted. Letting libswscale
    # do the matrix conversion during the scale stage costs nothing extra.
    c80 = config['profile'] == PROFILE_C80M4
    c80_btc = c80 and config.get('c80_btc', False)
    # --denoise: temporal-only hqdn3d AFTER the scaler (at 160x96-class
    # resolution the temporal pass costs next to nothing; running it at
    # source resolution made "Extracting Video" crawl on HD material).
    # Spatial strengths are 0 (no blur) - static detail stays sharp; the
    # temporal pass averages what does not move, killing the noise that
    # drives per-frame cell re-decisions (glyph shimmer) in C80/BTC and
    # APAC dither crawl alike.
    denoise_filter = "hqdn3d=0:0:6:6," if config.get('denoise') else ""
    if c80:
        # C80M4: true-colour cells; the FPGA renders RGB directly, so no
        # BT.601 trip - plain RGB from the scaler. BTC feeds the encoder a
        # 160x96 subpixel grid, classic C80 an 80x48 pixel grid.
        c80_w, c80_h = (160, 96) if c80_btc else (80, 48)
        if config['aspect'] == 'fit':
            scale_filter = (f"scale={c80_w}:{c80_h}:force_original_aspect_ratio=decrease:flags=lanczos,"
                            f"pad={c80_w}:{c80_h}:(ow-iw)/2:(oh-ih)/2:black")
        else:
            scale_filter = f"scale={c80_w}:{c80_h}:flags=lanczos"
        vf_chain = (f"{scale_filter},"
                    f"{denoise_filter}"
                    f"eq=contrast={config['contrast']},"
                    f"hue=s={config['saturation']},"
                    f"fps={fps},format=rgb24")
        if c80_btc:
            print("    Profile: AVF-C80 M4 + BTC subcell masks "
                  "(GTIA2RGB COL80, 160x96 / 2x RGB444 per cell)")
        else:
            print("    Profile: AVF-C80 M4 (GTIA2RGB COL80, 80x48 RGB444)")
    common_scale_opts = "flags=lanczos:in_color_matrix=auto:out_color_matrix=bt601"
    if config['aspect'] == 'fit':
        # Preserve source aspect ratio, pad with black to 160x192 (letter/pillarbox).
        # Note: assumes square pixels for the source; ignores Atari's non-square
        # pixel aspect on a CRT (a known compromise - acceptable on modern displays).
        scale_filter = (
            f"scale=160:192:force_original_aspect_ratio=decrease:{common_scale_opts},"
            f"pad=160:192:(ow-iw)/2:(oh-ih)/2:black"
        )
    else:
        # Stretch (legacy behaviour): fill the frame regardless of source AR.
        scale_filter = f"scale=160:192:{common_scale_opts}"

    # Saturation is applied via the `hue` filter rather than `eq=saturation=`,
    # because `eq` saturates very weakly above 1.0 (clamp/curve in libavfilter)
    # while `hue=s=` scales chroma linearly - so values like 1.5 actually do
    # something visible. Contrast still goes through `eq` (no equivalent in `hue`).
    # Both filters are no-ops at 1.0, so default behaviour is preserved.
    if not c80:
        vf_chain = (
            f"{scale_filter},"
            f"{denoise_filter}"
            f"eq=contrast={config['contrast']},"
            f"hue=s={config['saturation']},"
            f"fps={fps},format=yuv420p"
        )

    # Audio Filters: Loudnorm (EBU R128) or Manual Gain
    if config['loudnorm']:
        # EBU R128 normalization
        af_chain = "loudnorm=I=-16:TP=-1.5:LRA=11"
        print(f"    Audio: Loudness Normalization (I=-16 LUFS)")
    else:
        # Manual volume gain
        af_chain = f"volume={config['volume']}dB"
        print(f"    Audio: Manual Gain {config['volume']}dB")

    # --- 2. RAW EXTRACTION (FFmpeg) ---
    try:
        # Dump Video
        print(f"    [1/3] Extracting Video...")
        subprocess.run([
            'ffmpeg', '-y', '-hide_banner', '-loglevel', 'error',
            '-i', input_file,
            '-vf', vf_chain,
            '-f', 'rawvideo', temp_vid
        ], check=True)

        # Dump Audio (Forced PCM Unsigned 8-bit)
        # Added TRY/EXCEPT to handle video-only files
        print(f"    [2/3] Extracting Audio...")
        use_dummy_audio = False
        try:
            subprocess.run([
                'ffmpeg', '-y', '-hide_banner', '-loglevel', 'error',
                '-i', input_file,
                '-vn',
                '-af', af_chain,
                '-ar', audio_rate,
                '-ac', '1',
                '-c:a', 'pcm_u8',
                '-f', 'u8',
                temp_aud
            ], check=True)
        except subprocess.CalledProcessError:
            print("    WARNING: No audio stream detected (or extraction failed).")
            print("             Generating digital silence for compatibility.")
            use_dummy_audio = True

    except subprocess.CalledProcessError as e:
        print(f"Error during FFmpeg extraction: {e}")
        return

    # --- 3. ENCODING & MUXING ---
    print(f"    [3/3] Encoding & Muxing... "
          f"(numba: {'ON' if NUMBA_OK else 'OFF - SLOW, pure Python'})")

    fout = open(output_file, "wb")

    # The 8KB header is enabled by default. It is required for correct synchronization
    # by the "movplay" player, which always skips the first 16 sectors (regardless of media).
    if not config['no_header']:
        fout.write(b'\x00' * (16 * 512))

    # Dithering buffers
    errfi = np.zeros((HEIGHT, 80), dtype=np.float32)
    errfq = np.zeros((HEIGHT, 80), dtype=np.float32)
    errfy = np.zeros((HEIGHT, 80), dtype=np.float32)

    # C80/BTC temporal-hysteresis state (per file; see encode_c80btc_frame)
    btc_stability = float(config.get('btc_stability', 0.0) or 0.0)
    btc_dither = config.get('btc_dither', 'none')
    btc_dither_strength = float(config.get('btc_dither_strength', 0.5))
    btc_dither_gate = bool(config.get('btc_dither_gate', False))
    btc_prev_mask = np.zeros((24, 80), dtype=np.uint8)
    btc_prev_bg = np.zeros((24, 80, 3), dtype=np.uint8)
    btc_prev_fg = np.zeros((24, 80, 3), dtype=np.uint8)
    btc_prev_valid = 0
    if c80_btc and btc_stability > 0.0:
        print(f"    BTC temporal stability: {btc_stability:.2f}")
    if c80_btc and btc_dither != 'none':
        temporal = "temporal, +1 px/frame" if btc_dither == 'bayer-t' else "static"
        print(f"    BTC dither: Bayer 8x8 ({temporal}, strength "
              f"{btc_dither_strength:.2f}{', variance-gated' if btc_dither_gate else ''})")
        if btc_dither == 'bayer-t' and btc_stability > 0.0:
            print("    WARNING: bayer-t with BTC hysteresis attenuates the "
                  "deliberate frame-to-frame dither cycle")

    f_vid = open(temp_vid, "rb")

    # Open audio file only if it exists, otherwise we'll generate silence in loop
    f_aud = None
    if not use_dummy_audio:
        f_aud = open(temp_aud, "rb")

    frame_count = 0
    start_time = time.time()

    # AVF2: pick the poster frame index up front. Explicit --poster wins;
    # otherwise 10% of the source duration (ffprobe), otherwise 10 s.
    poster_idx = 0
    poster_data = None
    avf2_meta = None
    if config['avf2']:
        if config['poster'] is not None:
            poster_time = config['poster']
        else:
            duration = probe_duration_seconds(input_file)
            poster_time = duration * 0.10 if duration else 10.0
        poster_idx = max(0, int(round(poster_time * float(fps))))
        # Per-file metadata; untitled files fall back to the source basename
        # so batch conversions still produce self-describing AVF2 files.
        avf2_meta = {
            'title': config['title'] or os.path.splitext(os.path.basename(input_file))[0],
            'author': config['author'],
            # no explicit comment -> self-document the conversion settings
            'comment': config['comment'] or build_settings_comment(config),
        }

    try:
        while True:
            if c80_btc:
                rgb_data = f_vid.read(160 * 96 * 3)
                if len(rgb_data) != 46080: break
            elif c80:
                rgb_data = f_vid.read(80 * 48 * 3)
                if len(rgb_data) != 11520: break
            else:
                y_data = f_vid.read(160 * 192)
                if len(y_data) != 30720: break

                u_data = f_vid.read(80 * 96)
                v_data = f_vid.read(80 * 96)

            # Read audio chunk or generate silence
            if not use_dummy_audio:
                a_data = f_aud.read(audio_chunk_size)
            else:
                a_data = b'' # Will be padded below

            if len(a_data) < audio_chunk_size:
                # Padding with silence (128 = silence in Unsigned 8-bit)
                # This handles both end-of-file and dummy-audio scenarios
                a_data += b'\x80' * (audio_chunk_size - len(a_data))

            a_chunk = np.frombuffer(a_data, dtype=np.uint8)

            if c80_btc:
                rgb96_clean = np.frombuffer(rgb_data, dtype=np.uint8).reshape((96, 160, 3)).astype(np.float32)
                # Ordered dither is a target pre-pass.  Static Bayer remains
                # compatible with temporal hysteresis; bayer-t deliberately
                # changes the target phase every frame.
                rgb96 = apply_btc_ordered_dither(
                    rgb96_clean, btc_dither, frame_count,
                    btc_dither_strength, btc_dither_gate)
                # Halfblock-baseline pass first: box-2x2 the 160x96 target to
                # 80x48 and run the classic encoder (with its serpentine FS
                # dither) on THAT - an optimal-halfblock baseline for the
                # 160x96 reference, not a byte-identical `--profile c80m4`
                # result (which scales the source straight to 80x48). Its
                # output doubles as the search seed AND the classic-encoded
                # poster (the poster is never BTC - spec section 5).
                rgb48 = rgb96.reshape(48, 2, 80, 2, 3).mean(axis=(1, 3))
                classic_vid = encode_c80m4_frame(rgb48)
                ca = classic_vid.reshape(24, 8, 40)
                leg = np.stack([ca[:, 2:4, :].reshape(24, 80),
                                ca[:, 4:6, :].reshape(24, 80),
                                ca[:, 6:8, :].reshape(24, 80)], -1)
                leg_bg = ((leg >> 4) & 0xF).astype(np.uint8)
                leg_fg = (leg & 0xF).astype(np.uint8)
                encoded_vid = encode_c80btc_frame(
                    rgb96, leg_bg, leg_fg,
                    btc_prev_mask, btc_prev_bg, btc_prev_fg,
                    btc_prev_valid if btc_stability > 0.0 else 0,
                    btc_stability)
                btc_prev_valid = 1
            elif c80:
                rgb = np.frombuffer(rgb_data, dtype=np.uint8).reshape((48, 80, 3)).astype(np.float32)
                encoded_vid = encode_c80m4_frame(rgb)
            else:
                y_plane = np.frombuffer(y_data, dtype=np.uint8).reshape((192, 160))
                u_plane = np.frombuffer(u_data, dtype=np.uint8).reshape((96, 80))
                v_plane = np.frombuffer(v_data, dtype=np.uint8).reshape((96, 80))
                encoded_vid = encode_video_frame(y_plane, u_plane, v_plane, errfi, errfq, errfy, is_pal)
            encoded_aud = encode_audio_chunk(a_chunk)

            # AVF2 poster: keep overwriting until the chosen frame is reached,
            # so a clip shorter than the poster time still gets its last frame.
            # BTC streams store the CLASSIC C80 encoding as the poster
            # (spec section 5: thumbnails need no BTC awareness).
            if config['avf2'] and frame_count <= poster_idx:
                if c80_btc and btc_dither != 'none':
                    # The AVF2 poster is classic C80 and intentionally remains
                    # clean: do not bake the stream's Bayer texture into a
                    # static information-screen image.
                    poster_rgb48 = rgb96_clean.reshape(48, 2, 80, 2, 3).mean(axis=(1, 3))
                    poster_vid = encode_c80m4_frame(poster_rgb48)
                    poster_data = poster_vid.flatten().tobytes()
                else:
                    poster_data = (classic_vid if c80_btc else encoded_vid).flatten().tobytes()

            # Both profiles share the exact APAC container (8704-byte
            # frames, same block/pad + audio mux). C80 differs ONLY in the
            # video CONTENT (COL80 M4 cells vs APAC luma/chroma) - so the
            # proven movplay streaming kernel and audio path are reused as
            # is, and the player just enables Mode 4 for a C80 profile.
            mux_frame(fout, encoded_vid, encoded_aud, is_pal)

            # --- INTEGRITY CHECK ---
            # Verifies if the file size matches the expected byte count exactly.
            # If not, aborts immediately to prevent generating a corrupted file.
            # Uses an explicit raise rather than assert so that running with
            # python -O does not silently disable the safety net.
            current_pos = fout.tell()
            header_offset = (16 * 512) if not config['no_header'] else 0
            expected_pos = header_offset + (frame_count + 1) * FRAME_SIZE_BYTES

            if current_pos != expected_pos:
                raise RuntimeError(
                    f"CRITICAL: byte size mismatch at frame {frame_count} "
                    f"(got {current_pos}, expected {expected_pos}). "
                    f"AVF stream is misaligned and would desync on hardware."
                )

            frame_count += 1
            if frame_count % 100 == 0:
                elapsed = time.time() - start_time
                fps_proc = frame_count / elapsed
                print(f"    Encoding... Frame {frame_count} ({fps_proc:.1f} fps)", end='\r', flush=True)

    except KeyboardInterrupt:
        print("\nAborted.")
    finally:
        f_vid.close()
        if f_aud: f_aud.close()

        # AVF2: patch the metadata header into the (so far zeroed) first
        # 16 sectors, now that frame_count and the poster are known.
        if config['avf2'] and frame_count > 0:
            header = build_avf2_header(is_pal, frame_count, poster_data, avf2_meta,
                                       config['profile'],
                                       config.get('c80_btc', False))
            fout.seek(0)
            fout.write(header)
            print(f"    AVF2 header: title='{avf2_meta['title']}', "
                  f"poster frame {min(poster_idx, frame_count - 1)}, "
                  f"{frame_count} frames")

        fout.close()

        # Clean up temporary files
        if os.path.exists(temp_vid): os.remove(temp_vid)
        if os.path.exists(temp_aud): os.remove(temp_aud)

        # NOTE: We do NOT remove the input file (even if downloaded), as per new requirements.

    print(f"\n    Done. Saved to {output_file}")


def generate_test_file(filename):
    # Generates a synthetic video file (SMPTE bars + 440Hz sine wave).
    print(f"--- Generating Test Signal: {filename} ---")
    cmd = [
        'ffmpeg', '-y', '-hide_banner', '-loglevel', 'error',
        '-f', 'lavfi', '-i', 'testsrc=duration=10:size=160x192:rate=50',
        '-f', 'lavfi', '-i', 'sine=frequency=440:duration=10',
        '-c:v', 'libx264', '-pix_fmt', 'yuv420p',
        '-c:a', 'aac', '-ar', '44100', '-ac', '1',
        filename
    ]
    subprocess.run(cmd, check=True)
    print("    Test file created successfully.")

def main():
    avf.print_banner("Converter", __version__)
    parser = argparse.ArgumentParser(description="Atari 8-bit AVF Converter")

    # Input Options
    parser.add_argument("input", nargs='?', help="Input file, directory, or URL")
    parser.add_argument("--test-gen", action="store_true", help="Generate and convert a test signal")
    parser.add_argument("--urllist", action="store_true", help="Treat input argument as a text file containing URLs")

    # System Options
    parser.add_argument("--system", choices=['PAL', 'NTSC', 'BOTH'], default='BOTH', help="Target TV system")
    parser.add_argument("--out", help="Output base name; '-PAL.avf'/'-NTSC.avf' is appended "
                                      "(ignored in batch/list mode)")
    parser.add_argument("--version", action="version", version=f"avi2atari {__version__}")
    parser.add_argument("--no-header", action="store_true", help="Disable 8KB header (not recommended!)")
    parser.add_argument("--profile", choices=['apac', 'c80m4', 'c80btc'], default='apac',
                        help="Video profile: 'apac' (classic, every Atari), 'c80m4' "
                             "(AVF-C80: GTIA2RGB COL80 Mode 4, 80x48 true-colour RGB444) "
                             "or 'c80btc' (AVF-C80 + BTC subcell masks: 160x96 detail, "
                             "two RGB444 colours per cell; EXPERIMENTAL). Both C80 "
                             "profiles imply --avf2, need a GTIA2RGB and the AV2PLAY "
                             "player (https://github.com/HanJammer/av2play) for true "
                             "colour; they also play in legacy AVF players, but the "
                             "colours will be wrong.")

    # AVF2 metadata header (see docs/AVF2_HEADER.md). Fully backward
    # compatible: existing players skip the header region unconditionally.
    parser.add_argument("--avf", type=int, choices=[1, 2], default=None,
                        metavar="N",
                        help="Container version: 2 = AVF2 metadata header "
                             "(the default), 1 = plain legacy AVF v1 (zeroed "
                             "header, no metadata). --no-header implies 1.")
    parser.add_argument("--avf2", action="store_true",
                        help=argparse.SUPPRESS)  # deprecated alias for --avf 2
    parser.add_argument("--title", default=None, help="AVF2: video title (ASCII, max 64 chars)")
    parser.add_argument("--author", default=None, help="AVF2: author of the conversion (ASCII, max 64 chars)")
    parser.add_argument("--comment", default=None, help="AVF2: free-text comment (ASCII, max 128 chars)")
    parser.add_argument("--poster", type=float, default=None, metavar="SECONDS",
                        help="AVF2: source timestamp of the poster frame "
                             "(default: 10%% of duration, or 10s if unknown)")

    # Image Options
    parser.add_argument("--saturation", type=float, default=1.0, help="Color saturation (0 = black & white, 1.0 = original, 2.0 = boosted; default: 1.0)")
    parser.add_argument("--contrast", type=float, default=1.0, help="Contrast adjustment (default: 1.0)")
    parser.add_argument("--allow-slow", action="store_true",
                        help="Allow --profile c80btc without numba (the pure-Python "
                             "exhaustive search takes HOURS per minute of video)")
    parser.add_argument("--denoise", action="store_true",
                        help="Temporal-only denoise of the SOURCE (hqdn3d, no "
                             "spatial blur) before scaling. Reduces glyph "
                             "shimmer on noisy/grainy material for every "
                             "profile; static detail stays sharp.")
    parser.add_argument("--btc-stability", type=float, default=None, metavar="K",
                        help="c80btc temporal hysteresis: keep a cell's previous "
                             "mask+colours while their error stays within "
                             "(1+K) of the per-frame optimum. Kills mask "
                             "flicker in static areas at a bounded cost; "
                             "0 = off (stateless). Default: 0.10, except "
                             "bayer-t defaults to 0. "
                             "Encoder-side only - files stay fully compatible.")
    parser.add_argument("--btc-dither", choices=['none', 'bayer', 'bayer-t'],
                        default='none',
                        help="c80btc ordered dither: none (default), static "
                             "screen-anchored Bayer 8x8, or Bayer shifted one "
                             "subpixel right per frame (bayer-t - the best-"
                             "looking variant in hardware tests). Encoder-side "
                             "only.")
    parser.add_argument("--btc-dither-gate", action="store_true",
                        help="c80btc: attenuate the Bayer pattern in cells "
                             "that already carry real detail (per-cell "
                             "variance gate), so dither smooths gradients "
                             "without eating mask detail. Off by default.")
    parser.add_argument("--btc-dither-strength", type=float, default=0.5,
                        metavar="S",
                        help="Bayer strength for c80btc: 1.0 spans one RGB444 "
                             "step peak-to-peak (about +/-8.37); 0.5 is a "
                             "gentler half-strength pattern that keeps more "
                             "mask detail. Range 0..1, default 0.5 (hardware-"
                             "tested sweet spot).")
    parser.add_argument("--aspect", choices=['stretch', 'fit'], default='stretch',
                        help="How to fit source into 160x192: 'stretch' (legacy default, "
                             "fills the frame) or 'fit' (preserves source aspect ratio with "
                             "black bars). Use 'fit' for 16:9 content to avoid squashing.")

    # Audio Options
    audio_group = parser.add_mutually_exclusive_group()
    audio_group.add_argument("--volume", type=float, default=12.0, help="Manual volume gain in dB (default: 12.0)")
    audio_group.add_argument("--loudnorm", action="store_true", help="Use EBU R128 loudness normalization (Recommended)")

    args = parser.parse_args()

    # If no arguments provided (and not test-gen), print help and exit
    if not args.input and not args.test_gen:
        parser.print_help()
        sys.exit(1)

    # Every mode shells out to FFmpeg, so fail here with a useful message rather
    # than a bare FileNotFoundError traceback from the first subprocess call.
    if shutil.which('ffmpeg') is None:
        print("ERROR: 'ffmpeg' was not found on your PATH.")
        print("       Install it and make sure the 'bin' folder is on PATH - see the README.")
        sys.exit(1)

    # Container version: AVF2 is the suite default. --avf2 is a deprecated
    # alias for --avf 2; --no-header implies plain v1 unless --avf 2 was
    # asked for explicitly (that combination is an error).
    avf_ver = args.avf
    if args.avf2 and avf_ver is None:
        avf_ver = 2
    if avf_ver is None:
        avf_ver = 1 if args.no_header else 2
    if avf_ver == 2 and args.no_header:
        print("ERROR: AVF2 requires the 8KB header; --avf 2 cannot be combined "
              "with --no-header.")
        sys.exit(1)

    if args.profile in ('c80m4', 'c80btc'):
        if args.no_header:
            print(f"ERROR: --profile {args.profile} requires the AVF2 header (players must "
                  "be able to identify the profile); it cannot be combined with --no-header.")
            sys.exit(1)
        if avf_ver != 2:
            print(f"NOTE: --profile {args.profile} implies AVF2 (the profile id lives in the header).")
            avf_ver = 2

    if avf_ver == 1 and (args.title or args.author or args.comment
                         or args.poster is not None):
        print("NOTE: --title/--author/--comment/--poster need AVF2 and are "
              "IGNORED with --avf 1 (legacy files carry no metadata).")

    if args.profile == 'c80btc' and not NUMBA_OK and not args.allow_slow:
        print("ERROR: --profile c80btc needs numba - the un-jitted exhaustive "
              "search runs at ~7.5 s per FRAME (6+ hours per minute of PAL "
              "video). Install the pinned dependencies:")
        print("           pip install -r requirements.txt")
        print("       or pass --allow-slow if you really mean it.")
        sys.exit(1)

    if not 0.0 <= args.btc_dither_strength <= 1.0:
        print("ERROR: --btc-dither-strength must be between 0 and 1.")
        sys.exit(1)
    if args.btc_dither != 'none' and args.profile != 'c80btc':
        print("ERROR: --btc-dither is only valid with --profile c80btc.")
        sys.exit(1)

    # Temporal Bayer wants to complete its eight-frame phase cycle.  Keep
    # explicitly requested hysteresis legal for experiments, but make the
    # temporal mode's default stateless instead of silently fighting it.
    if args.btc_stability is None:
        btc_stability = 0.0 if args.btc_dither == 'bayer-t' else 0.10
    else:
        btc_stability = max(0.0, args.btc_stability)
    if args.profile == 'c80btc' and args.btc_dither == 'bayer-t' \
            and args.btc_stability is None:
        print("NOTE: --btc-dither bayer-t defaults BTC stability to 0; "
              "pass an explicit --btc-stability value to "
              "experiment with their interaction.")

    # Config dictionary
    config = {
        'no_header': args.no_header,
        'saturation': args.saturation,
        'contrast': args.contrast,
        'aspect': args.aspect,
        'volume': args.volume,
        'loudnorm': args.loudnorm,
        'avf2': avf_ver == 2,
        'profile': PROFILE_C80M4 if args.profile in ('c80m4', 'c80btc') else PROFILE_APAC,
        'c80_btc': args.profile == 'c80btc',
        'btc_stability': btc_stability,
        'btc_dither': args.btc_dither,
        'btc_dither_gate': args.btc_dither_gate,
        'btc_dither_strength': args.btc_dither_strength,
        'denoise': args.denoise,
        'title': args.title,
        'author': args.author,
        'comment': args.comment,
        'poster': args.poster
    }

    # MODE 1: Test Generator
    if args.test_gen:
        test_file = "test_tone.mp4"
        generate_test_file(test_file)
        if args.system in ['BOTH', 'PAL']:
            process_single_file(test_file, 'PAL', "test_tone-PAL.avf", config)
        if args.system in ['BOTH', 'NTSC']:
            process_single_file(test_file, 'NTSC', "test_tone-NTSC.avf", config)
        return

    # Determine input type
    input_arg = args.input

    # MODE 2: URL List File
    if args.urllist:
        if not os.path.exists(input_arg):
            print(f"ERROR: URL list file '{input_arg}' not found.")
            return

        print(f"--- Processing URL List: {input_arg} ---")
        with open(input_arg, 'r', encoding='utf-8') as f:
            lines = [l.strip() for l in f if l.strip()]

        for line in lines:
            parts = line.split('\t')
            url = parts[0]
            custom_name = parts[1] if len(parts) > 1 else None

            dl_path, title = download_media(url)
            if dl_path:
                base_name = custom_name if custom_name else title
                if args.system in ['BOTH', 'PAL']:
                    process_single_file(dl_path, 'PAL', f"{base_name}-PAL.avf", config)
                if args.system in ['BOTH', 'NTSC']:
                    process_single_file(dl_path, 'NTSC', f"{base_name}-NTSC.avf", config)
        return

    # MODE 3: Direct URL (YouTube or File)
    if input_arg.startswith("http://") or input_arg.startswith("https://"):
        dl_path, title = download_media(input_arg)
        if dl_path:
            base_name = args.out if args.out else title
            if args.system in ['BOTH', 'PAL']:
                process_single_file(dl_path, 'PAL', f"{base_name}-PAL.avf", config)
            if args.system in ['BOTH', 'NTSC']:
                process_single_file(dl_path, 'NTSC', f"{base_name}-NTSC.avf", config)
        return

    # MODE 4: Directory Batch
    if os.path.isdir(input_arg):
        # Expanded extension list for batch processing
        extensions = ['*.mp4', '*.mkv', '*.avi', '*.flv', '*.webm', '*.wmv', '*.mov', '*.mpg', '*.mpeg', '*.m4v']
        files = []
        for ext in extensions:
            files.extend(glob.glob(os.path.join(input_arg, ext)))

        print(f"--- Batch Mode: Found {len(files)} video files in '{input_arg}' ---")

        for f in files:
            base = os.path.splitext(os.path.basename(f))[0]
            if args.system in ['BOTH', 'PAL']:
                process_single_file(f, 'PAL', os.path.join(input_arg, f"{base}-PAL.avf"), config)
            if args.system in ['BOTH', 'NTSC']:
                process_single_file(f, 'NTSC', os.path.join(input_arg, f"{base}-NTSC.avf"), config)
        return

    # MODE 5: Single Local File
    if os.path.exists(input_arg):
        base = args.out if args.out else os.path.splitext(os.path.basename(input_arg))[0]
        if args.system in ['BOTH', 'PAL']:
            process_single_file(input_arg, 'PAL', f"{base}-PAL.avf", config)
        if args.system in ['BOTH', 'NTSC']:
            process_single_file(input_arg, 'NTSC', f"{base}-NTSC.avf", config)
    else:
        print(f"ERROR: Input '{input_arg}' not found.")

if __name__ == "__main__":
    main()