ot.py

import cv2
from ultralytics import YOLO
import argparse
from tqdm import tqdm
import torch
import os
import sys
import subprocess
import threading
import time
import queue
import json
import signal
import re # Added for ffprobe output parsing
import numpy as np
from collections import Counter
from recon_integration import (
    append_recon_index_row,
    build_recon_index_row,
    build_recon_messages,
    cleanup_temp_file,
    ensure_recon_log_structure,
    get_recon_flags,
    needs_normalization_fallback,
    normalize_video,
    run_recon,
    save_recon_json,
)

# Attempt to import psutil for CPU/Memory monitoring
try:
    import psutil
    PSUTIL_AVAILABLE = True
except ImportError:
    PSUTIL_AVAILABLE = False
    print("⚠️ [WARNING] psutil library not found. RAM usage limiting and CPU/Memory utilization display will not be available.")

# Attempt to import GPUtil for GPU monitoring
try:
    import GPUtil
    GPUTIL_AVAILABLE = True
except (ImportError, Exception):
    GPUTIL_AVAILABLE = False


# --- FFMPEG Check ---
FFMPEG_AVAILABLE = False

def check_ffmpeg():
    global FFMPEG_AVAILABLE
    try:
        subprocess.run(["ffmpeg", "-version"], capture_output=True, text=True, check=True)
        print("[INFO] ffmpeg found and seems to be working.")
        FFMPEG_AVAILABLE = True
    except Exception:
        print("⚠️ [WARNING] ffmpeg command not found or not working. Audio processing will be skipped.")
        FFMPEG_AVAILABLE = False
    return FFMPEG_AVAILABLE


def detect_nvenc():
    """Detect if NVENC hevc_nvenc encoder is available in FFmpeg."""
    global NVENC_AVAILABLE
    if not USE_NVENC:
        print("[INFO] NVENC disabled by config (USE_NVENC = False).")
        return False
    try:
        result = subprocess.run(
            ["ffmpeg", "-hide_banner", "-encoders"],
            capture_output=True, text=True, timeout=10
        )
        if "hevc_nvenc" in result.stdout:
            NVENC_AVAILABLE = True
            print("✅ [SUCCESS] NVENC H.265 encoder (hevc_nvenc) detected. Will use hardware encoding.")
            return True
        else:
            print("⚠️ [WARNING] hevc_nvenc not found in FFmpeg. Falling back to libx264.")
            return False
    except Exception as e:
        print(f"⚠️ [WARNING] Could not detect NVENC: {e}. Falling back to libx264.")
        return False

def get_video_rotation(video_path: str) -> int:
    """
    Uses ffprobe to get the rotation metadata of a video.
    Returns the rotation angle (0, 90, 180, 270). Returns 0 if no rotation found or on error.
    """
    try:
        command = [
            "ffprobe",
            "-v", "error",
            "-select_streams", "v:0",
            "-show_entries", "stream_tags=rotate",
            "-of", "default=nokey=1:noprint_wrappers=1",
            video_path
        ]
        result = subprocess.run(command, capture_output=True, text=True, check=True, timeout=10)
        rotation_str = result.stdout.strip()
        if rotation_str and rotation_str.isdigit():
            rotation_angle = int(rotation_str)
            if rotation_angle in [0, 90, 180, 270]:
                print(f"[INFO] Detected video rotation: {rotation_angle} degrees.")
                return rotation_angle
        print("[INFO] No rotation metadata found or invalid rotation value, assuming 0 degrees.")
        return 0
    except subprocess.CalledProcessError as e:
        print(f"⚠️ [WARNING] ffprobe failed to get rotation for '{video_path}': {e.stderr.strip()}")
        return 0
    except FileNotFoundError:
        print("⚠️ [WARNING] ffprobe command not found. Cannot determine video rotation.")
        return 0
    except subprocess.TimeoutExpired:
        print(f"⚠️ [WARNING] ffprobe timed out while getting rotation for '{video_path}'.")
        return 0
    except Exception as e:
        print(f"⚠️ [WARNING] An unexpected error occurred while getting video rotation: {e}")
        return 0


# --- Configuration & Setup ---
DEFAULT_MODEL_PATH = "yolov8m.pt"
DEFAULT_OUTPUT_VIDEO_PATH_MARKER = "auto"
DEFAULT_ALLOWED_CLASSES = [
    "person", "car", "truck", "bus", "motorcycle", "bicycle", "airplane", "bird", "cat", "dog",
    "train", "boat", "bench", "backpack", "umbrella", "handbag", "suitcase", "sports ball",
    "bottle", "wine glass", "cup", "fork", "knife", "spoon", "bowl",
    "chair", "couch", "potted plant", "bed", "dining table",
    "tv", "laptop", "mouse", "remote", "keyboard", "cell phone",
    "microwave", "refrigerator", "book", "clock", "vase", "scissors"
]
DEFAULT_CONFIDENCE_THRESHOLD = 0.25
TEMP_VIDEO_BASENAME = "temp_video_processed_silent.mp4" # This will now be the silent video generated by ffmpeg
OUTPUT_SUBDIRECTORY = "output"
FRAME_QUEUE_SIZE = 30
UTILIZATION_UPDATE_INTERVAL = 1.0 # Interval for updating CPU/Mem/GPU stats in progress bar
# Increased MAX_RAM_USAGE_PERCENT slightly to reduce frequent pausing, use with caution.
MAX_RAM_USAGE_PERCENT = 100 # Percentage of total RAM to trigger pause in frame reading

# +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# +++ User Configuration +++
ENABLE_PREVIEW_IN_SCRIPT = False # Set to True to show a live preview window during processing
USE_GPU_IN_SCRIPT = True # Set to True to attempt using GPU (CUDA) for processing if available

# TARGET_PROCESSING_WIDTH: This is the width used for INTERNAL object tracking.
# Set to a lower resolution (e.g., 1920 for 1080p equivalent) to reduce RAM usage and speed up tracking.
# The final output video will be upscaled back to its original resolution.
# Set to None to perform tracking at the original video resolution (higher RAM/slower).
TARGET_PROCESSING_WIDTH = 1920

# FFmpeg Quality Settings (Crucial for High Quality and Reasonable File Size)
# CRF (Constant Rate Factor):
#   0 = truly lossless (pixel-perfect, but results in very large files)
#   16-23 = visually lossless for H.264 (recommended for excellent quality with good compression)
#   Lower CRF means higher quality and larger file size.
FFMPEG_CRF_VALUE = 24 # Production default aligned with Adaptive_Temporal benchmark profile.
FFMPEG_VIDEO_CODEC = "libx264" # Recommended for wide compatibility. Use "libx265" for HEVC (smaller files, requires x265 encoder).
FFMPEG_PRESET = "ultrafast" # Production default aligned with Adaptive_Temporal benchmark profile.

# --- NVENC H.265 Hardware Encoding ---
# When True, pipeline will use NVIDIA NVENC hevc_nvenc if available for 40-50% smaller files.
# Falls back silently to libx264 if NVENC is unavailable.
USE_NVENC = True
NVENC_AVAILABLE = False  # Runtime flag, set by detect_nvenc() at startup

# --- Watermark Configuration ---
# ENABLE_WATERMARK: Master switch to turn watermark on/off
# Set to True to add "Processed by projectglyphmotion.studio" watermark to output videos
# Set to False to disable watermark completely
ENABLE_WATERMARK = False # ON by default - change to False to disable

# Watermark text - displayed in bottom-right corner
WATERMARK_TEXT = "Processed by projectglyphmotion.studio"

# Watermark appearance settings (dynamic - scales with video resolution)
# Font size is calculated as: video_height / WATERMARK_FONT_DIVISOR
# Higher divisor = smaller text, Lower divisor = larger text
WATERMARK_FONT_DIVISOR = 40  # Results in ~27px for 1080p, ~54px for 4K, ~18px for 720p

# Watermark opacity (0.0 = invisible, 1.0 = fully opaque)
# Recommended: 0.6-0.8 for visible but non-distracting
WATERMARK_OPACITY = 0.7

# Margin from edge (as fraction of video height)
# 0.02 = 2% margin from bottom-right corner
WATERMARK_MARGIN_FRACTION = 0.02

# --- ROI (Region of Interest) Configuration ---
# ROI allows users to select a specific area of the video for object tracking
# Objects outside the ROI will be ignored (not drawn/tracked)

# Default ROI settings (can be overridden by command-line arguments)
# When ENABLE_ROI is False, the entire frame is used for tracking
DEFAULT_ROI_ENABLED = False

# ROI overlay settings
# When enabled, draws a semi-transparent overlay outside the ROI area
DEFAULT_ROI_SHOW_OVERLAY = True
DEFAULT_ROI_OVERLAY_OPACITY = 30  # Percentage (0-100)

# ROI overlay color (BGR format for OpenCV)
ROI_OVERLAY_COLOR = (20, 20, 30)  # Dark gray-blue, matches the website theme

# --- Adaptive HFDR Production Defaults (always-on by design) ---
ADAPTIVE_HFDR_ENABLED = True
ADAPTIVE_TARGET_FPS = 20.0
ADAPTIVE_INITIAL_ALPHA = 0.30
ADAPTIVE_HFDR_SIGMA = 2.0
ADAPTIVE_HFDR_CACHE_INTERVAL = 3
ADAPTIVE_TEMPORAL_THRESHOLD = 0.003
ADAPTIVE_TEMPORAL_KEYFRAME_INTERVAL = 30
ADAPTIVE_TEMPORAL_BLEND_ALPHA = 0.85  # Blend ratio (0=prev, 1=current) — keep mostly current
ADAPTIVE_MOTION_GATE_THRESHOLD = 0.025
ADAPTIVE_ROI_MARGIN_PX = 24
ADAPTIVE_UNIFIED_MOTION_THRESHOLD = 0.02
ADAPTIVE_UNIFIED_OBJECT_THRESHOLD = 3
ADAPTIVE_UNIFIED_HYSTERESIS = 5
ADAPTIVE_ROI_MIN_CACHE = 1
ADAPTIVE_ROI_MAX_CACHE = 8
ADAPTIVE_ROI_MOTION_HIGH = 0.025
ADAPTIVE_ROI_MOTION_LOW = 0.005
ADAPTIVE_FFMPEG_UNSHARP_ENABLED = True
ADAPTIVE_FFMPEG_UNSHARP_AMOUNT = 1.5
ADAPTIVE_FFMPEG_UNSHARP_MSIZE = 5
ADAPTIVE_PROFILE_NAME = "Adaptive_Temporal"

# --- Motion-Aware Adaptive FFmpeg Filtering Tiers ---
ADAPTIVE_FILTER_TIERS = {
    "low":    {"threshold": 0.008, "la": 1.0, "label": "Static"},
    "medium": {"threshold": 0.025, "la": 1.5, "label": "Medium"},
    "high":   {"threshold": 999.0, "la": 2.0, "label": "Dynamic"},
}

# --- Semantic Class-Based Priority ---
ADAPTIVE_SEMANTIC_MAP = {
    "person": 3, "car": 3, "truck": 3, "bus": 3,
    "motorcycle": 2, "bicycle": 2, "dog": 2, "cat": 2, "bird": 2,
    "backpack": 1, "umbrella": 1, "handbag": 1, "suitcase": 1,
}
ADAPTIVE_SEMANTIC_ALPHA_MAP = {3: 1.0, 2: 0.7, 1: 0.4, 0: 0.15}
# +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

_termination_signal_received = False


def _handle_termination_signal(signum, _frame):
    global _termination_signal_received
    _termination_signal_received = True
    print(f"\n[INFO] Received termination signal ({signum}). Stopping processing...")
    raise KeyboardInterrupt


def get_watermark_filter():
    """
    Generates an FFmpeg drawtext filter for the watermark.
    Uses dynamic expressions so it scales with any video resolution/aspect ratio.
    Portrait videos get smaller text to avoid being too intrusive.
    
    Returns:
        str: FFmpeg filter string for watermark, or empty string if disabled.
    """
    if not ENABLE_WATERMARK:
        return ""
    
    # Escape special characters in the text for FFmpeg
    # FFmpeg drawtext requires escaping colons and backslashes
    escaped_text = WATERMARK_TEXT.replace("\\", "\\\\").replace(":", "\\:")
    
    # Dynamic FFmpeg expressions:
    # h = video height, w = video width, th = text height, tw = text width
    # gt(h,w) = 1 if portrait (height > width), 0 if landscape
    # Font size scales with video dimensions for consistent appearance across resolutions
    # Portrait videos use smaller text (1.5x larger divisor) to be less intrusive
    
    # Calculate divisors for portrait vs landscape
    portrait_divisor = WATERMARK_FONT_DIVISOR * 1.5  # Smaller text for portrait
    landscape_divisor = WATERMARK_FONT_DIVISOR       # Normal text for landscape
    
    # For portrait: use width as reference (since it's smaller dimension)
    # For landscape: use height as reference
    # This ensures watermark is proportional to the smaller dimension
    
    watermark_filter = (
        f"drawtext="
        f"text='{escaped_text}':"
        # Dynamic font size: smaller for portrait, normal for landscape
        # Portrait: min(w,h) / (divisor * 1.5), Landscape: h / divisor
        f"fontsize=if(gt(h\\,w)\\,min(w\\,h)/{portrait_divisor}\\,h/{landscape_divisor}):"
        f"fontcolor=white@{WATERMARK_OPACITY}:"  # White text with configured opacity
        f"x=w-tw-(h*{WATERMARK_MARGIN_FRACTION}):"  # Right-aligned with dynamic margin
        f"y=h-th-(h*{WATERMARK_MARGIN_FRACTION}):"  # Bottom-aligned with dynamic margin
        f"box=1:"  # Enable background box
        f"boxcolor=black@{WATERMARK_OPACITY * 0.5}:"  # Semi-transparent black background
        # Dynamic padding: smaller for portrait
        f"boxborderw=if(gt(h\\,w)\\,min(w\\,h)/{portrait_divisor}/4\\,h/{landscape_divisor}/4)"
    )
    
    print(f"[INFO] Watermark ENABLED: \"{WATERMARK_TEXT}\"")
    print(f"[INFO] Watermark sizing: Landscape={landscape_divisor}, Portrait={portrait_divisor} (smaller)")
    return watermark_filter


def get_system_utilization(device_to_use):
    """
    Retrieves current system utilization statistics (CPU, Memory, GPU).
    Uses torch.cuda for GPU monitoring when GPUtil is not available.
    """
    global GPUTIL_AVAILABLE

    util_stats = {}
    if PSUTIL_AVAILABLE:
        util_stats['cpu'] = psutil.cpu_percent()
        mem_info = psutil.virtual_memory()
        util_stats['mem_used_gb'] = mem_info.used / (1024**3)
        util_stats['mem_total_gb'] = mem_info.total / (1024**3)
        util_stats['mem'] = mem_info.percent

    if device_to_use == "cuda":
        gpu_stats_collected = False
        # Try GPUtil first (more accurate load reporting)
        if GPUTIL_AVAILABLE:
            try:
                gpus = GPUtil.getGPUs()
                if gpus:
                    gpu = gpus[0]
                    util_stats['gpu_load'] = gpu.load * 100
                    util_stats['gpu_mem_mb'] = gpu.memoryUsed  # Actual MB used
                    gpu_stats_collected = True
            except Exception:
                print("⚠️ [WARNING] GPUtil failed to get GPU stats.")
                GPUTIL_AVAILABLE = False

        # Fallback: use torch.cuda built-in monitoring (always works when CUDA is available)
        if not gpu_stats_collected and torch.cuda.is_available():
            try:
                # VRAM usage from PyTorch (reliable, no extra dependency)
                vram_used_mb = torch.cuda.memory_allocated(0) / (1024 * 1024)
                vram_reserved_mb = torch.cuda.memory_reserved(0) / (1024 * 1024)
                util_stats['gpu_mem_mb'] = round(vram_reserved_mb, 1)  # Reserved is more accurate for peak tracking

                # GPU utilization from torch (available in PyTorch 2.0+)
                try:
                    gpu_util = torch.cuda.utilization(0)  # Returns 0-100 int
                    util_stats['gpu_load'] = float(gpu_util)
                except Exception:
                    # torch.cuda.utilization not available in older PyTorch — estimate from activity
                    util_stats['gpu_load'] = 50.0 if vram_used_mb > 100 else 0.0
            except Exception:
                pass

    return util_stats

def format_utilization_string(stats):
    """
    Formats system utilization statistics into a human-readable string.
    """
    parts = []
    if 'cpu' in stats: parts.append(f"CPU:{stats['cpu']:.1f}%")
    if 'mem' in stats:
        parts.append(f"Mem:{stats['mem']:.1f}% ({stats.get('mem_used_gb',0):.1f}/{stats.get('mem_total_gb',0):.1f}GB)")
    if 'gpu_load' in stats: parts.append(f"GPU-L:{stats['gpu_load']:.1f}%")
    if 'gpu_mem_mb' in stats: parts.append(f"VRAM:{stats['gpu_mem_mb']:.0f}MB")
    return " | ".join(parts) if parts else "Stats N/A"


def frame_reader_thread_func(cap, frame_input_queue, stop_event, original_width, original_height, target_processing_width=None, pass_original=False):
    """
    Thread function to read frames from video, resize for processing, and put into a queue.
    Includes a RAM usage check to pause reading if memory is high.
    Args:
        cap (cv2.VideoCapture): OpenCV VideoCapture object.
        frame_input_queue (queue.Queue): Queue to put read/resized frames into.
        stop_event (threading.Event): Event to signal thread to stop.
        original_width (int): Original width of the video as reported by OpenCV.
        original_height (int): Original height of the video as reported by OpenCV.
        target_processing_width (int, optional): Target width for internal processing.
                                                  If None, original resolution is used.
    """
    print("[INFO] Frame reader thread started.")
    count = 0

    # Determine the resolution for internal tracking
    # Note: original_width/height here are the raw dimensions from cap.get(), not necessarily display dimensions.
    processing_width = original_width
    processing_height = original_height
    do_resize_for_processing = False

    if target_processing_width and target_processing_width > 0 and target_processing_width < original_width:
        aspect_ratio = original_height / original_width
        processing_width = target_processing_width
        # Calculate height to maintain aspect ratio, ensuring it's an even number for codecs
        processing_height = int(processing_width * aspect_ratio)
        if processing_height % 2 != 0:
            processing_height = processing_height - 1 if processing_height > 1 else 2 # Ensure even height
        do_resize_for_processing = True
        print(f"[INFO] Frame reader: Resizing frames from {original_width}x{original_height} to {processing_width}x{processing_height} for internal processing.")
    else:
        # If no target_processing_width is set, ensure original dimensions are even for processing compatibility
        if processing_width % 2 != 0: processing_width = processing_width - 1 if processing_width > 1 else 2
        if processing_height % 2 != 0: processing_height = processing_height - 1 if processing_height > 1 else 2
        if original_width != processing_width or original_height != processing_height:
             print(f"⚠️ [WARNING] Frame reader: Adjusted original resolution to {processing_width}x{processing_height} for processing codec compatibility (even dimensions).")
        print(f"[INFO] Frame reader: Processing at original resolution {processing_width}x{processing_height}.")


    while not stop_event.is_set() and cap.isOpened():
        if PSUTIL_AVAILABLE:
            current_ram_usage = psutil.virtual_memory().percent
            ram_check_loops = 0
            # Pause frame reading if RAM usage is too high
            while current_ram_usage > MAX_RAM_USAGE_PERCENT and not stop_event.is_set():
                if ram_check_loops % 5 == 0: # Print warning every 5 seconds of pause
                    print(f"⚠️ [WARNING] [FRAME_READER] High RAM usage: {current_ram_usage:.1f}%. Pausing frame reading for 1s...")
                time.sleep(1.0)
                current_ram_usage = psutil.virtual_memory().percent
                ram_check_loops +=1
                if stop_event.is_set():
                    print("[INFO] [FRAME_READER] Stop event received during RAM pause.")
                    # Fix: Ensure stop signal is consistent (2 values)
                    if not frame_input_queue.full(): frame_input_queue.put((False, None, None))
                    return

        # Only read frame if there's space in the queue
        if frame_input_queue.qsize() < FRAME_QUEUE_SIZE:
            ret, frame = cap.read()
            if not ret: # End of video or error reading frame
                print(f"[INFO] Frame reader: End of video or cannot read frame after {count} frames.")
                # Fix: Ensure end signal is consistent (2 values)
                frame_input_queue.put((False, None, None))
                break

            # Resize frame for internal processing if target_processing_width is set
            if do_resize_for_processing:
                try:
                    processed_frame = cv2.resize(frame, (processing_width, processing_height), interpolation=cv2.INTER_AREA)
                except Exception as e:
                    print(f"❌ [ERROR] [FRAME_READER] Failed to resize frame for processing: {e}. Using original frame.")
                    processed_frame = frame # Fallback to original if resize fails
            else:
                processed_frame = frame

            # Put the processed frame and (optionally) the original full-res frame into queue
            original_to_pass = frame if pass_original else None
            frame_input_queue.put((True, processed_frame, original_to_pass))
            count += 1
        else:
            time.sleep(0.005) # Small delay to prevent busy-waiting if queue is full

    # Ensure stop signal is sent if loop finishes naturally
    if not stop_event.is_set() and not frame_input_queue.full():
        frame_input_queue.put((False, None, None))
    print(f"[INFO] Frame reader thread finished after reading {count} frames.")


def frame_writer_thread_func(ffmpeg_stdin_pipe, frame_output_queue, stop_event):
    """
    Writes processed and (upscaled) frames from queue directly to FFmpeg's stdin pipe.
    Args:
        ffmpeg_stdin_pipe (subprocess.PIPE): stdin pipe of the FFmpeg process.
        frame_output_queue (queue.Queue): Queue to get (upscaled) frames from.
        stop_event (threading.Event): Event to signal thread to stop.
    """
    print("[INFO] Frame writer thread started for FFmpeg pipe.")
    count = 0
    try:
        while not stop_event.is_set():
            try:
                # Get frame from queue with a timeout to allow checking stop_event
                ret, frame_to_write = frame_output_queue.get(timeout=0.1)
                if not ret: # End signal received
                    print(f"[INFO] Frame writer: End signal received after writing {count} frames.")
                    break # Exit loop

                if frame_to_write is not None:
                    # Convert frame to raw bytes for FFmpeg (BGR is OpenCV default)
                    ffmpeg_stdin_pipe.write(frame_to_write.tobytes())
                    count += 1
                frame_output_queue.task_done()
            except queue.Empty:
                # If queue is empty, check stop_event and if the main loop finished
                if stop_event.is_set() and frame_output_queue.empty():
                    print("[INFO] Frame writer: Stop event set and queue empty.")
                    break
                continue # Keep waiting for frames
            except BrokenPipeError:
                print("❌ [ERROR] [FRAME_WRITER] Broken pipe to FFmpeg. FFmpeg likely exited unexpectedly.")
                break
            except Exception as e:
                print(f"❌ [ERROR] [FRAME_WRITER] Error writing frame to FFmpeg pipe: {e}")
                break
    finally:
        # Crucially, close the pipe to signal FFmpeg that no more frames are coming
        if ffmpeg_stdin_pipe:
            try:
                ffmpeg_stdin_pipe.close()
                print("[INFO] FFmpeg stdin pipe closed.")
            except Exception as e:
                print(f"⚠️ [WARNING] Error closing FFmpeg stdin pipe: {e}")

        # Mark remaining tasks as done if any are left (e.g. if an error occurred)
        while not frame_output_queue.empty():
            try:
                frame_output_queue.get_nowait()
                frame_output_queue.task_done()
            except queue.Empty:
                break # Queue is now truly empty

    print(f"[INFO] Frame writer thread finished. Total frames written to FFmpeg: {count}")


def parse_arguments():
    """Parses command-line arguments for the script."""
    parser = argparse.ArgumentParser(description="Object Tracking: YOLOv8, Threaded I/O, GPU/CPU, Progress, ffmpeg Audio, Utilization")
    parser.add_argument("--model",type=str,default=DEFAULT_MODEL_PATH,help="Path to YOLOv8 model.")
    parser.add_argument("--output_video",type=str,default=DEFAULT_OUTPUT_VIDEO_PATH_MARKER,help="Path for final video. Default: 'auto' (derived from input name, saved in 'output/' subdir).")
    parser.add_argument("--allowed_classes",nargs="+",default=DEFAULT_ALLOWED_CLASSES,help=f"Classes to track.")
    parser.add_argument("--confidence_threshold",type=float,default=DEFAULT_CONFIDENCE_THRESHOLD,help=f"Min confidence.")
    parser.add_argument("--input_video", type=str, required=True, help="Path to the input video file.")
    parser.add_argument("--codec", type=str, default=FFMPEG_VIDEO_CODEC, help="FFmpeg video codec (e.g. libx264, libx265).")
    parser.add_argument("--preset", type=str, default=FFMPEG_PRESET, help="FFmpeg preset (ultrafast, fast, medium, etc.).")
    parser.add_argument("--crf", type=int, default=FFMPEG_CRF_VALUE, help="FFmpeg CRF value (lower = higher quality).")
    
    # ROI (Region of Interest) arguments
    parser.add_argument("--roi_enabled", type=str, default="false", help="Enable ROI filtering (true/false).")
    parser.add_argument("--roi_x", type=float, default=0.0, help="ROI X position (0-1 normalized).")
    parser.add_argument("--roi_y", type=float, default=0.0, help="ROI Y position (0-1 normalized).")
    parser.add_argument("--roi_width", type=float, default=1.0, help="ROI width (0-1 normalized).")
    parser.add_argument("--roi_height", type=float, default=1.0, help="ROI height (0-1 normalized).")
    parser.add_argument("--roi_show_overlay", type=str, default="true", help="Show semi-transparent overlay outside ROI (true/false).")
    parser.add_argument("--roi_overlay_opacity", type=int, default=DEFAULT_ROI_OVERLAY_OPACITY, help="ROI overlay opacity (0-100).")
    parser.add_argument("--gdrive_auto_transcoded", type=str, default="false", help="Whether uploaded output auto-transcoded on Google Drive (true/false).")
    
    return parser.parse_args()


def is_box_in_roi(box_coords, roi_coords, frame_width, frame_height):
    """
    Check if a bounding box center is within the ROI.
    
    Args:
        box_coords: Tuple of (x1, y1, x2, y2) - bounding box pixel coordinates
        roi_coords: Dict with 'x', 'y', 'width', 'height' - normalized ROI (0-1)
        frame_width: Width of the frame in pixels
        frame_height: Height of the frame in pixels
    
    Returns:
        bool: True if box center is within ROI, False otherwise
    """
    if roi_coords is None:
        return True  # No ROI means all boxes are valid
    
    x1, y1, x2, y2 = box_coords
    
    # Calculate box center
    box_center_x = (x1 + x2) / 2
    box_center_y = (y1 + y2) / 2
    
    # Convert ROI from normalized to pixel coordinates
    roi_x1 = roi_coords['x'] * frame_width
    roi_y1 = roi_coords['y'] * frame_height
    roi_x2 = (roi_coords['x'] + roi_coords['width']) * frame_width
    roi_y2 = (roi_coords['y'] + roi_coords['height']) * frame_height
    
    # Check if box center is within ROI
    return (roi_x1 <= box_center_x <= roi_x2) and (roi_y1 <= box_center_y <= roi_y2)


def draw_roi_overlay(frame, roi_coords, opacity):
    """
    Draw a semi-transparent overlay outside the ROI area.
    
    Args:
        frame: The frame to draw on (will be modified in-place)
        roi_coords: Dict with 'x', 'y', 'width', 'height' - normalized ROI (0-1)
        opacity: Overlay opacity (0-100)
    
    Returns:
        The modified frame with ROI overlay
    """
    if roi_coords is None or opacity <= 0:
        return frame
    
    h, w = frame.shape[:2]
    
    # Convert normalized ROI to pixel coordinates
    roi_x1 = int(roi_coords['x'] * w)
    roi_y1 = int(roi_coords['y'] * h)
    roi_x2 = int((roi_coords['x'] + roi_coords['width']) * w)
    roi_y2 = int((roi_coords['y'] + roi_coords['height']) * h)
    
    # Clamp values to frame bounds
    roi_x1 = max(0, min(roi_x1, w))
    roi_y1 = max(0, min(roi_y1, h))
    roi_x2 = max(0, min(roi_x2, w))
    roi_y2 = max(0, min(roi_y2, h))
    
    # Create overlay
    overlay = frame.copy()
    alpha = opacity / 100.0
    
    # Fill areas outside ROI with dark overlay
    # Top region
    if roi_y1 > 0:
        cv2.rectangle(overlay, (0, 0), (w, roi_y1), ROI_OVERLAY_COLOR, -1)
    # Bottom region
    if roi_y2 < h:
        cv2.rectangle(overlay, (0, roi_y2), (w, h), ROI_OVERLAY_COLOR, -1)
    # Left region (between top and bottom)
    if roi_x1 > 0:
        cv2.rectangle(overlay, (0, roi_y1), (roi_x1, roi_y2), ROI_OVERLAY_COLOR, -1)
    # Right region (between top and bottom)
    if roi_x2 < w:
        cv2.rectangle(overlay, (roi_x2, roi_y1), (w, roi_y2), ROI_OVERLAY_COLOR, -1)
    
    # Draw ROI border (orange to match theme)
    border_color = (54, 161, 253)  # BGR for #FDA136 (orange)
    cv2.rectangle(overlay, (roi_x1, roi_y1), (roi_x2, roi_y2), border_color, 2)
    
    # Blend overlay with original frame
    cv2.addWeighted(overlay, alpha, frame, 1 - alpha, 0, frame)
    
    return frame


class PipelineController:
    """
    Feedback-driven PID controller for adaptive parameter tuning.
    Monitors real-time pipeline signals (FPS, motion, queue depth, tracking
    confidence) and continuously adjusts filter strength and HFDR alpha.
    """
    def __init__(self, target_fps=20.0, initial_filter_strength=2.0, initial_alpha=0.3):
        self.target_fps = target_fps
        self.filter_strength = initial_filter_strength
        self.hfdr_alpha = initial_alpha
        self._fps_window = []
        self._adjustment_count = 0
        self._window_size = 10

    def update(self, current_fps, motion_score, queue_depth, tracking_confidence):
        self._fps_window.append(current_fps)
        if len(self._fps_window) > self._window_size:
            self._fps_window.pop(0)

        avg_fps = sum(self._fps_window) / len(self._fps_window)
        fps_error = avg_fps - self.target_fps

        if fps_error < -3:
            self.filter_strength = max(0.5, self.filter_strength - 0.3)
            self.hfdr_alpha = max(0.1, self.hfdr_alpha - 0.05)
            self._adjustment_count += 1
        elif fps_error < -1:
            self.filter_strength = max(0.8, self.filter_strength - 0.1)
            self.hfdr_alpha = max(0.15, self.hfdr_alpha - 0.02)
            self._adjustment_count += 1
        elif fps_error > 5:
            self.filter_strength = min(3.0, self.filter_strength + 0.2)
            self.hfdr_alpha = min(0.5, self.hfdr_alpha + 0.03)
            self._adjustment_count += 1
        elif fps_error > 2:
            self.filter_strength = min(2.5, self.filter_strength + 0.1)
            self.hfdr_alpha = min(0.4, self.hfdr_alpha + 0.01)
            self._adjustment_count += 1

        # Motion override: high-motion scenes need full filter strength
        if motion_score > 0.05:
            self.filter_strength = max(self.filter_strength, 1.5)

        # Queue pressure: if output queue is backing up, reduce work
        queue_ratio = queue_depth / max(1, FRAME_QUEUE_SIZE)
        if queue_ratio > 0.8:
            self.filter_strength = max(0.5, self.filter_strength - 0.2)
            self.hfdr_alpha = max(0.1, self.hfdr_alpha - 0.05)
            self._adjustment_count += 1

        # Tracking confidence: if tracker is struggling, boost detail
        if tracking_confidence < 0.4 and tracking_confidence > 0:
            self.hfdr_alpha = min(0.5, self.hfdr_alpha + 0.1)
            self._adjustment_count += 1

        return self.filter_strength, self.hfdr_alpha

    @property
    def adjustment_count(self):
        return self._adjustment_count

    @property
    def avg_fps(self):
        return sum(self._fps_window) / max(1, len(self._fps_window))

    def compute_roi_refresh_interval(self, motion_score):
        if motion_score >= ADAPTIVE_ROI_MOTION_HIGH:
            return ADAPTIVE_ROI_MIN_CACHE
        elif motion_score <= ADAPTIVE_ROI_MOTION_LOW:
            return ADAPTIVE_ROI_MAX_CACHE
        else:
            ratio = (motion_score - ADAPTIVE_ROI_MOTION_LOW) / max(0.001, (ADAPTIVE_ROI_MOTION_HIGH - ADAPTIVE_ROI_MOTION_LOW))
            interval = ADAPTIVE_ROI_MAX_CACHE - ratio * (ADAPTIVE_ROI_MAX_CACHE - ADAPTIVE_ROI_MIN_CACHE)
            return max(ADAPTIVE_ROI_MIN_CACHE, int(round(interval)))


class UnifiedModeController:
    def __init__(self, motion_threshold=0.02, object_threshold=3, hysteresis=5):
        self.motion_threshold = motion_threshold
        self.object_threshold = object_threshold
        self.hysteresis = hysteresis
        self.current_mode = "A"
        self._hold_counter = 0
        self._mode_switches = 0

    def decide_mode(self, motion_score, object_count, avg_confidence=0.5):
        wants_mode_b = (motion_score > self.motion_threshold or
                        object_count >= self.object_threshold or
                        avg_confidence < 0.4)  # Low confidence = need more detail
        desired_mode = "B" if wants_mode_b else "A"

        if desired_mode != self.current_mode:
            self._hold_counter += 1
            if self._hold_counter >= self.hysteresis:
                self.current_mode = desired_mode
                self._hold_counter = 0
                self._mode_switches += 1
        else:
            self._hold_counter = 0

        return self.current_mode

    @property
    def mode_switches(self):
        return self._mode_switches


def should_reuse_frame(current_gray, reference_gray, threshold=0.003):
    if reference_gray is None:
        return False, 1.0, False
    diff = cv2.absdiff(current_gray, reference_gray)
    diff_ratio = float(np.mean(diff)) / 255.0
    skip_hfdr = diff_ratio < threshold * 0.3  # Ultra-static only (<0.1% change)
    should_blend = diff_ratio < threshold and not skip_hfdr  # Slight change → blend
    return skip_hfdr, diff_ratio, should_blend


def extract_hf_detail_only(frame, alpha=0.3, sigma=2.0):
    blurred = cv2.GaussianBlur(frame, (0, 0), sigmaX=sigma, sigmaY=sigma)
    return cv2.addWeighted(frame, alpha, blurred, -alpha, 128.0)


def apply_hf_detail(frame, hf_detail):
    return cv2.addWeighted(frame, 1.0, hf_detail, 1.0, -128.0)


def build_roi_mask(frame_shape, detections, margin=24, priorities=None):
    """
    Create a uint8 mask from YOLO bounding boxes.
    If priorities dict given, returns per-pixel priority map instead of binary mask.
    """
    h, w = frame_shape[:2]
    mask = np.zeros((h, w), dtype=np.uint8)
    for det in detections:
        x1, y1, x2, y2 = int(det[0]), int(det[1]), int(det[2]), int(det[3])
        class_name = det[4] if len(det) > 4 else ""
        x1 = max(0, x1 - margin)
        y1 = max(0, y1 - margin)
        x2 = min(w, x2 + margin)
        y2 = min(h, y2 + margin)
        if priorities is not None:
            priority = priorities.get(class_name, 0)
            region = mask[y1:y2, x1:x2]
            mask[y1:y2, x1:x2] = np.maximum(region, priority)
        else:
            mask[y1:y2, x1:x2] = 255
    return mask


def apply_roi_hfdr(frame, hf_detail, roi_mask, alpha_multipliers=None, priority_mask=None):
    """
    Apply HFDR only inside ROI regions. Supports semantic mode with per-class alpha scaling.
    """
    result = frame.copy()
    if priority_mask is not None and alpha_multipliers is not None:
        for priority_level, alpha_scale in alpha_multipliers.items():
            if alpha_scale <= 0.05:
                continue
            level_mask = (priority_mask == priority_level)
            if not np.any(level_mask):
                continue
            blended = cv2.addWeighted(frame, 1.0, hf_detail, alpha_scale, -128.0 * alpha_scale)
            result[level_mask] = blended[level_mask]
    else:
        roi_bool = roi_mask > 0
        if np.any(roi_bool):
            blended = apply_hf_detail(frame, hf_detail)
            result[roi_bool] = blended[roi_bool]
    return result


def get_adaptive_filter_tier(motion_score):
    """Map a spatial_complexity score to a 3-tier FFmpeg filter strength."""
    tiers = ADAPTIVE_FILTER_TIERS
    if motion_score < tiers["low"]["threshold"]:
        return tiers["low"]["la"], tiers["low"]["label"]
    elif motion_score < tiers["medium"]["threshold"]:
        return tiers["medium"]["la"], tiers["medium"]["label"]
    else:
        return tiers["high"]["la"], tiers["high"]["label"]


def get_semantic_priority(class_name, priority_map=None):
    """Get the semantic priority level for a detected object class."""
    if priority_map is None:
        priority_map = ADAPTIVE_SEMANTIC_MAP
    return priority_map.get(class_name, 0)

def start_ffmpeg_video_encoder(output_path, width, height, fps, vf_filter_string=""):
    """
    Starts an FFmpeg subprocess to encode raw video frames from stdin.
    Uses NVENC H.265 if available, otherwise falls back to libx264.
    """
    ffmpeg_cmd = [
        "ffmpeg",
        "-y",
        "-hide_banner",
        "-loglevel", "error",
        "-stats",
        "-f", "rawvideo",
        "-pix_fmt", "bgr24",
        "-s", f"{width}x{height}",
        "-r", str(fps),
        "-i", "-",
    ]

    if vf_filter_string:
        ffmpeg_cmd.extend(["-vf", vf_filter_string])

    # Choose encoder: NVENC H.265 or libx264 fallback
    if NVENC_AVAILABLE:
        ffmpeg_cmd.extend([
            "-c:v", "hevc_nvenc",
            "-preset", "p4",
            "-rc", "vbr",
            "-cq", str(FFMPEG_CRF_VALUE),
            "-b:v", "0",
            "-pix_fmt", "yuv420p",
            "-metadata", "major_brand=mp42",
            "-metadata", "compatible_brands=isomiso2avc1mp41",
            output_path
        ])
    else:
        ffmpeg_cmd.extend([
            "-c:v", FFMPEG_VIDEO_CODEC,
            "-preset", FFMPEG_PRESET,
            "-crf", str(FFMPEG_CRF_VALUE),
            "-pix_fmt", "yuv420p",
            "-metadata", "major_brand=mp42",
            "-metadata", "compatible_brands=isomiso2avc1mp41",
            output_path
        ])

    encoder_name = "hevc_nvenc" if NVENC_AVAILABLE else FFMPEG_VIDEO_CODEC
    print(f"[INFO] Starting FFmpeg encoder ({encoder_name}). Command: {' '.join(ffmpeg_cmd)}")
    process = subprocess.Popen(ffmpeg_cmd, stdin=subprocess.PIPE, stderr=subprocess.PIPE)
    return process


def process_audio_ffmpeg(video_source_path, temp_silent_video_path, final_output_video_path):
    """
    Copies audio from original video and merges it with the processed silent video.
    Args:
        video_source_path (str): Path to the original input video (for audio).
        temp_silent_video_path (str): Path to the processed video (without audio, but now correctly oriented).
        final_output_video_path (str): Desired path for the final video with audio.
    Returns:
        bool: True if audio merge was successful, False otherwise.
    """
    if not FFMPEG_AVAILABLE:
        print("⚠️ [WARNING] [AUDIO_MERGE] ffmpeg not available. Skipping audio merge.")
        # If no ffmpeg, and silent video is the direct output from tracking, rename it.
        if os.path.exists(temp_silent_video_path) and not os.path.exists(final_output_video_path):
            try:
                os.rename(temp_silent_video_path, final_output_video_path)
                print(f"✅ [SUCCESS] Processed silent video saved as final output: '{final_output_video_path}'.")
            except OSError as e:
                print(f"❌ [ERROR] Could not rename temp silent file: {e}.")
        return False

    if not os.path.exists(temp_silent_video_path):
        print(f"❌ [ERROR] [AUDIO_MERGE] Temporary silent video '{temp_silent_video_path}' not found. Cannot merge audio.")
        return False

    print(f"\n[AUDIO_MERGE] Attempting to extract and merge audio using ffmpeg.")
    if os.path.exists(final_output_video_path):
        print(f"⚠️ [WARNING] Output file {final_output_video_path} exists. Overwriting for audio merge.")

    # Use a temporary name for the audio-merged file
    final_output_video_temp = final_output_video_path + ".temp_audio_merged.mp4"

    # Command to copy video stream and audio stream (if present)
    # -map 0:v:0 ensures only the video stream from the first input (temp_silent_video_path) is used
    # -map 1:a:0? tries to use the first audio stream from the second input (video_source_path), '?' makes it optional
    # -shortest ensures output duration is limited by the shortest input stream
    # -c:v copy copies the video stream without re-encoding (since it was just encoded by FFmpeg pipe)
    # -c:a aac re-encodes audio to AAC for wide compatibility
    # No -vf filter needed here as the temp_silent_video_path is already correctly oriented.
    ffmpeg_audio_merge_cmd = [
        "ffmpeg", "-y", "-i", temp_silent_video_path, "-i", video_source_path,
        "-map", "0:v:0", "-map", "1:a:0?", # Map video from first input, audio from second
        "-c:v", "copy",
        "-c:a", "aac",
        "-strict", "experimental", # Needed for some AAC encoders
        "-b:a", "192k", # Audio bitrate, adjust as needed
        "-metadata", "major_brand=mp42",
        "-metadata", "compatible_brands=isomiso2avc1mp41",
        "-shortest",
        final_output_video_temp
    ]

    try:
        print(f"[AUDIO_MERGE] Executing audio merge: {' '.join(ffmpeg_audio_merge_cmd)}")
        # Capture output but don't print unless there's an error
        result = subprocess.run(ffmpeg_audio_merge_cmd, check=True, capture_output=True, text=True)
        # If check=True, CalledProcessError is raised for non-zero exit codes.
        # So, if we reach here, it was successful, no need to print stdout/stderr.

        if os.path.exists(final_output_video_temp):
            # If the temporary file was created, move it to the final destination
            if os.path.exists(final_output_video_path):
                os.remove(final_output_video_path)
            os.rename(final_output_video_temp, final_output_video_path)
            print(f"✅ [SUCCESS] Audio merged and final video saved: '{final_output_video_path}'")
            return True
        else:
            print(f"❌ [ERROR] [AUDIO_MERGE] FFmpeg did not create expected output file '{final_output_video_temp}'.")
            return False

    except subprocess.CalledProcessError as e:
        print(f"❌ [ERROR] [AUDIO_MERGE] FFmpeg audio merge failed with exit code {e.returncode}.")
        print(f"STDOUT:\n{e.stdout}")
        print(f"STDERR:\n{e.stderr}")
    except Exception as e_ffmpeg:
        print(f"❌ [ERROR] [AUDIO_MERGE] An unexpected error occurred during FFmpeg audio merge: {e_ffmpeg}")

    return False

def main():
    global FFMPEG_VIDEO_CODEC, FFMPEG_PRESET, FFMPEG_CRF_VALUE
    start_time_total = time.time()
    signal.signal(signal.SIGTERM, _handle_termination_signal)
    signal.signal(signal.SIGINT, _handle_termination_signal)
    project_root = os.path.dirname(os.path.abspath(__file__))
    recon_report = None
    recon_flags = {}
    fallback_mode_used = False
    recon_normalized_temp_path = None

    # Define the absolute path for the temporary silent video output
    temp_silent_video_abs_path = os.path.abspath(os.path.join(OUTPUT_SUBDIRECTORY, TEMP_VIDEO_BASENAME))

    # Initialize all critical variables at the top to prevent UnboundLocalError
    processing_loop_active = True
    frame_count = 0
    last_printed_percentage = -1 # Not used with tqdm
    original_width = 0
    original_height = 0
    fps = 0.0
    total_frames = 0
    model = None # Initialize model to None, assigned later in try/except
    telemetry = {
        "mode_a_frames": 0,
        "mode_b_frames": 0,
        "hfdr_fresh_count": 0,
        "hfdr_cached_count": 0,
        "hfdr_gated_count": 0,
        "ffmpeg_unsharp_amount": ADAPTIVE_FFMPEG_UNSHARP_AMOUNT if ADAPTIVE_FFMPEG_UNSHARP_ENABLED else 0.0,
    }
    # --- Stats tracking for .stats.json (matches ot_benchmark.py format) ---
    tracking_stats = {
        "total_detections": 0,
        "sum_confidence": 0.0,
        "unique_ids": set(),
        "id_appearances": {},
        "motion_vectors": [],
        "frame_latencies": [],
        "objects_per_frame": [],
        "spatial_complexities": [],
    }
    prev_centers_for_motion = {}  # track_id -> (cx, cy) for motion vector calculation
    peak_cpu = 0.0
    peak_ram_mb = 0.0
    peak_gpu_util = 0.0
    peak_vram_mb = 0.0


    # --- PyTorch CPU Threading Configuration ---
    # Attempts to optimize PyTorch's CPU operations by setting the number of threads.
    try:
        cpu_cores = os.cpu_count()
        if cpu_cores:
            num_threads_to_set = max(1, cpu_cores // 2) # Use half of logical cores for balance
            torch.set_num_threads(num_threads_to_set)
            print(f"[INFO] Suggested {num_threads_to_set} threads for PyTorch CPU operations.")
        else:
            print("[INFO] Could not determine CPU core count for PyTorch thread setting.")
    except Exception as e:
        print(f"⚠️ [WARNING] Could not set PyTorch CPU threads: {e}")

    # Initial checks for FFmpeg and monitoring libraries
    print("--- FFMPEG Check ---"); check_ffmpeg(); print("--------------------")
    print("--- NVENC Check ---"); detect_nvenc(); print("--------------------")
    if PSUTIL_AVAILABLE: print("[DEBUG] Priming psutil.cpu_percent()..."); psutil.cpu_percent()
    if GPUTIL_AVAILABLE:
        print("[DEBUG] Attempting to prime GPUtil.getGPUs()...")
        try: GPUtil.getGPUs(); print("[DEBUG] GPUtil.getGPUs() primed.")
        except Exception as e: print(f"[DEBUG] Error GPUtil priming: {e}")

    args = parse_arguments()
    gdrive_auto_transcoded = args.gdrive_auto_transcoded.lower() == 'true'

    FFMPEG_VIDEO_CODEC = str(args.codec or FFMPEG_VIDEO_CODEC).strip() or FFMPEG_VIDEO_CODEC
    FFMPEG_PRESET = str(args.preset or FFMPEG_PRESET).strip() or FFMPEG_PRESET
    try:
        FFMPEG_CRF_VALUE = max(0, min(51, int(args.crf)))
    except Exception:
        pass

    current_input_video = args.input_video

    # --- Parse ROI (Region of Interest) arguments ---
    roi_enabled = args.roi_enabled.lower() == 'true'
    roi_coords = None
    roi_show_overlay = args.roi_show_overlay.lower() == 'true'
    roi_overlay_opacity = max(0, min(100, args.roi_overlay_opacity))  # Clamp 0-100
    
    if roi_enabled:
        roi_coords = {
            'x': max(0.0, min(1.0, args.roi_x)),
            'y': max(0.0, min(1.0, args.roi_y)),
            'width': max(0.0, min(1.0, args.roi_width)),
            'height': max(0.0, min(1.0, args.roi_height))
        }
        # Validate ROI makes sense
        if roi_coords['width'] <= 0 or roi_coords['height'] <= 0:
            print("⚠️ [WARNING] Invalid ROI dimensions. Disabling ROI.")
            roi_enabled = False
            roi_coords = None
        else:
            roi_pct_x = roi_coords['x'] * 100
            roi_pct_y = roi_coords['y'] * 100
            roi_pct_w = roi_coords['width'] * 100
            roi_pct_h = roi_coords['height'] * 100
            print(f"[INFO] ROI ENABLED: Position ({roi_pct_x:.1f}%, {roi_pct_y:.1f}%) Size ({roi_pct_w:.1f}% x {roi_pct_h:.1f}%)")
            if roi_show_overlay:
                print(f"[INFO] ROI overlay enabled with {roi_overlay_opacity}% opacity")
            else:
                print("[INFO] ROI overlay disabled")
    else:
        print("[INFO] ROI disabled - tracking entire frame")

    # Adjust input video path if it's not absolute and not found in current dir (for Telegram bot)
    if not os.path.exists(current_input_video) and not os.path.isabs(current_input_video):
        potential_input_path = os.path.join("input", current_input_video)
        if os.path.exists(potential_input_path) and os.path.isfile(potential_input_path):
            current_input_video = potential_input_path
            print(f"[INFO] Input path adjusted to: {current_input_video}")

    # Validate input video file
    if not current_input_video:
        print("❌ [ERROR] No input video path provided. Exiting."); return
    if not os.path.exists(current_input_video) or not os.path.isfile(current_input_video):
        print(f"❌ [ERROR] Input video file not found or is not a file: {current_input_video}"); return

    # --- Recon intake + normalization gate (before model/capture/threads) ---
    try:
        ensure_recon_log_structure(project_root)
        recon_report = run_recon(current_input_video, project_root)
        if recon_report is not None:
            intake_json_path = save_recon_json(project_root, current_input_video, recon_report)
            print(f"[RECON] Intake analysis saved: {intake_json_path}")

            recon_flags = get_recon_flags(recon_report)
            for message in build_recon_messages(recon_flags):
                print(message)

            if recon_flags.get("normalization_triggered"):
                recon_normalized_temp_path = normalize_video(current_input_video, ffmpeg_bin="ffmpeg", target_fps=30)
                print(f"[RECON] Normalized input created: {recon_normalized_temp_path}")

                normalized_recon_report = run_recon(recon_normalized_temp_path, project_root)
                if normalized_recon_report is not None:
                    normalized_json_path = save_recon_json(
                        project_root,
                        current_input_video,
                        normalized_recon_report,
                        suffix="normalized",
                    )
                    print(f"[RECON] Normalized verification saved: {normalized_json_path}")
                current_input_video = recon_normalized_temp_path

            intake_row = build_recon_index_row(
                recon_report,
                stage="intake",
                video_filename=os.path.basename(args.input_video),
                normalization_triggered=bool(recon_flags.get("normalization_triggered")),
                normalization_reasons=recon_flags.get("normalization_reasons", []),
                gdrive_auto_transcoded=gdrive_auto_transcoded,
            )
            append_recon_index_row(project_root, intake_row)
        else:
            fallback_mode_used = True
            print("⚠️ [WARNING] [RECON] recon.py failed or unavailable. Using ffprobe fallback for normalization gate.")
            if needs_normalization_fallback(current_input_video):
                print("[RECON] Fallback ffprobe detected normalization need - normalizing input.")
                recon_normalized_temp_path = normalize_video(current_input_video, ffmpeg_bin="ffmpeg", target_fps=30)
                current_input_video = recon_normalized_temp_path
            else:
                print("[RECON] Fallback ffprobe: input looks clean - normalization skipped.")
    except Exception as recon_error:
        fallback_mode_used = True
        print(f"⚠️ [WARNING] [RECON] Input analysis failed: {recon_error}. Proceeding without recon logging.")

    show_preview = ENABLE_PREVIEW_IN_SCRIPT
    use_gpu = USE_GPU_IN_SCRIPT

    # Create output directory if it doesn't exist
    os.makedirs(OUTPUT_SUBDIRECTORY, exist_ok=True)

    # Determine the final output video path and name
    final_output_video_path = args.output_video
    if args.output_video == DEFAULT_OUTPUT_VIDEO_PATH_MARKER:
        input_basename_only = os.path.basename(current_input_video)
        name, ext = os.path.splitext(input_basename_only)
        # Always output as .mp4 for consistency and compatibility
        base_name = f"{name}_processed.mp4"
        final_output_video_path = os.path.join(OUTPUT_SUBDIRECTORY, base_name)
    else:
        if not os.path.isabs(args.output_video):
            final_output_video_path = os.path.join(OUTPUT_SUBDIRECTORY, os.path.basename(args.output_video))
        # Ensure output is .mp4 if a custom extension was provided (otherwise FFmpeg might default to .mkv)
        if not final_output_video_path.lower().endswith('.mp4'):
            final_output_video_path = os.path.splitext(final_output_video_path)[0] + '.mp4'

    print(f"[INFO] Final output video will be saved as: {final_output_video_path}")

    # Determine which device (CPU/GPU) to use for YOLO model
    device_to_use = "cpu"
    if use_gpu and torch.cuda.is_available():
        device_to_use = "cuda"
        gpu_name = torch.cuda.get_device_name(0)
        gpu_mem_total = torch.cuda.get_device_properties(0).total_memory / (1024**2)
        print(f"✅ [SUCCESS] CUDA GPU available: {gpu_name} ({gpu_mem_total:.0f}MB VRAM)")
        print(f"   PyTorch CUDA: {torch.version.cuda} | GPUtil monitoring: {'YES' if GPUTIL_AVAILABLE else 'NO (using torch.cuda fallback)'}")
    elif use_gpu:
        print("⚠️ [WARNING] CUDA GPU not found. Falling back to CPU.")
        print(f"   torch.cuda.is_available() = False | PyTorch build: {torch.__version__}")
    else:
        print("ℹ️ [INFO] Using CPU.")

    # Load YOLO model
    print(f"[INFO] Loading model: {args.model} on {device_to_use}")
    try:
        model = YOLO(args.model)
        model.to(device_to_use)
        print(f"✅ [SUCCESS] Model loaded.")
    except Exception as e:
        print(f"❌ [ERROR] Failed to load model: {e}")
        cleanup_temp_file(recon_normalized_temp_path)
        return

    print(f"[INFO] Tracking classes: {args.allowed_classes}")

    # Open video capture
    cap = cv2.VideoCapture(current_input_video)
    if not cap.isOpened():
        print(f"❌ [ERROR] Failed to open input video file: {current_input_video}")
        cleanup_temp_file(recon_normalized_temp_path)
        return

    # Get original video properties and assign to initialized variables
    original_width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
    original_height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
    fps = cap.get(cv2.CAP_PROP_FPS)
    if fps == 0.0 or fps is None: # Fallback for unreadable FPS
        fps = 30.0; print(f"⚠️ [WARNING] FPS not readable, defaulting to {fps} FPS.")
    total_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT)) # Assign total_frames here

    # --- Determine Rotation and Final Output Dimensions ---
    rotation_angle = get_video_rotation(current_input_video)
    vf_filter = "" # FFmpeg video filter for rotation correction

    # These are the dimensions that FFmpeg will output *after* applying the rotation filter.
    # So, if original is 1920x1080 (landscape) but needs to be 1080x1920 (portrait),
    # ffmpeg_output_width should be 1080 and ffmpeg_output_height should be 1920.
    # OpenCV's cap.get() returns the raw encoded dimensions.
    ffmpeg_output_width = original_width
    ffmpeg_output_height = original_height

    if rotation_angle == 90:
        vf_filter = "transpose=1" # Rotate 90 degrees clockwise (for portrait videos encoded landscape with rotate 90)
        ffmpeg_output_width = original_height # Swap for display dimensions
        ffmpeg_output_height = original_width
        print(f"[INFO] Applying FFmpeg rotation filter: {vf_filter}. Output dimensions will be {ffmpeg_output_width}x{ffmpeg_output_height}.")
    elif rotation_angle == 270:
        vf_filter = "transpose=2" # Rotate 90 degrees counter-clockwise
        ffmpeg_output_width = original_height # Swap for display dimensions
        ffmpeg_output_height = original_width
        print(f"[INFO] Applying FFmpeg rotation filter: {vf_filter}. Output dimensions will be {ffmpeg_output_width}x{ffmpeg_output_height}.")
    elif rotation_angle == 180:
        vf_filter = "transpose=2,transpose=2" # Rotate 180 degrees
        # Dimensions remain the same as 180 degree rotation doesn't swap width/height
        print(f"[INFO] Applying FFmpeg rotation filter: {vf_filter}. Output dimensions will remain {ffmpeg_output_width}x{ffmpeg_output_height}.")

    # --- Add Watermark Filter ---
    # Watermark is applied AFTER rotation so it appears correctly positioned in final video
    watermark_filter = get_watermark_filter()
    if watermark_filter:
        if vf_filter:
            # Chain filters: rotation first, then watermark
            vf_filter = f"{vf_filter},{watermark_filter}"
        else:
            vf_filter = watermark_filter
        print(f"[INFO] Final FFmpeg filter chain: {vf_filter[:80]}..." if len(vf_filter) > 80 else f"[INFO] Final FFmpeg filter chain: {vf_filter}")
    else:
        print("[INFO] Watermark DISABLED.")

    if ADAPTIVE_FFMPEG_UNSHARP_ENABLED:
        unsharp_filter = f"unsharp={ADAPTIVE_FFMPEG_UNSHARP_MSIZE}:{ADAPTIVE_FFMPEG_UNSHARP_MSIZE}:{ADAPTIVE_FFMPEG_UNSHARP_AMOUNT}:{ADAPTIVE_FFMPEG_UNSHARP_MSIZE}:{ADAPTIVE_FFMPEG_UNSHARP_MSIZE}:0"
        vf_filter = f"{vf_filter},{unsharp_filter}" if vf_filter else unsharp_filter
        print(f"[INFO] Adaptive FFmpeg hybrid unsharp enabled: {ADAPTIVE_FFMPEG_UNSHARP_AMOUNT}")

    # Ensure FFmpeg output dimensions are even for codec compatibility.
    if ffmpeg_output_width % 2 != 0:
        ffmpeg_output_width -= 1
        print(f"⚠️ [WARNING] Adjusted final output width to {ffmpeg_output_width} for FFmpeg codec compatibility (even dimension).")
    if ffmpeg_output_height % 2 != 0:
        ffmpeg_output_height -= 1
        print(f"⚠️ [WARNING] Adjusted final output height to {ffmpeg_output_height} for FFmpeg codec compatibility (even dimension).")

    # --- Internal Tracking Resolution (for YOLO model processing) ---
    # This is what the frame_reader_thread_func will resize frames to.
    # These internal dimensions are derived from original_width/height as reported by OpenCV,
    # because the actual frames read by OpenCV are still in their raw encoded orientation.
    effective_tracking_width = original_width
    effective_tracking_height = original_height
    target_width_for_reader = None

    if TARGET_PROCESSING_WIDTH and TARGET_PROCESSING_WIDTH > 0 and TARGET_PROCESSING_WIDTH < original_width:
        aspect_ratio = original_height / original_width
        target_width_for_reader = TARGET_PROCESSING_WIDTH # Reader will resize to this width
        effective_tracking_width = TARGET_PROCESSING_WIDTH
        effective_tracking_height = int(effective_tracking_width * aspect_ratio)
        if effective_tracking_height % 2 != 0:
            effective_tracking_height = effective_tracking_height - 1 if effective_tracking_height > 1 else 2
        print(f"[INFO] Internal object tracking will be performed on frames resized to {effective_tracking_width}x{effective_tracking_height}.")
    else:
        if effective_tracking_width % 2 != 0: effective_tracking_width = effective_tracking_width - 1 if effective_tracking_width > 1 else 2
        if effective_tracking_height % 2 != 0: effective_tracking_height = effective_tracking_height - 1 if effective_tracking_height > 1 else 2
        print(f"[INFO] Internal object tracking will be performed on frames at raw original resolution: {effective_tracking_width}x{effective_tracking_height}.")


    print(f"[INFO] FFmpeg final output video will be {ffmpeg_output_width}x{ffmpeg_output_height} at {fps:.2f} FPS (after rotation correction).")
    print(f"[INFO] FFmpeg encoding with codec: {FFMPEG_VIDEO_CODEC}, CRF: {FFMPEG_CRF_VALUE}, Preset: {FFMPEG_PRESET}.")

    # Start FFmpeg subprocess for encoding processed frames at the FINAL output resolution
    # Pass the determined filter string and the target final output dimensions
    ffmpeg_process = start_ffmpeg_video_encoder(temp_silent_video_abs_path, original_width, original_height, fps, vf_filter_string=vf_filter)
    if not ffmpeg_process:
        print("❌ [ERROR] Failed to start FFmpeg video encoder. Exiting.")
        cap.release()
        cleanup_temp_file(recon_normalized_temp_path)
        return
    print(f"✅ [SUCCESS] FFmpeg encoder started (PID: {ffmpeg_process.pid}).")


    # Setup threading queues and events
    stop_event = threading.Event()
    frame_input_queue = queue.Queue(maxsize=FRAME_QUEUE_SIZE) # Queue for frames read from video (at tracking resolution)
    frame_output_queue = queue.Queue(maxsize=FRAME_QUEUE_SIZE) # Queue for processed frames (upscaled to final output resolution)

    # Start frame reader thread (reads and resizes to tracking resolution)
    reader_thread = threading.Thread(
        target=frame_reader_thread_func,
        args=(cap, frame_input_queue, stop_event, original_width, original_height, target_width_for_reader, True)
    )
    reader_thread.daemon = True # Allows program to exit even if this thread is still running
    reader_thread.start()

    # Start frame writer thread (writes frames to FFmpeg pipe)
    writer_thread = threading.Thread(
        target=frame_writer_thread_func,
        args=(ffmpeg_process.stdin, frame_output_queue, stop_event)
    )
    writer_thread.daemon = True
    writer_thread.start()

    # Setup tqdm progress bar for main processing loop
    pbar_desc = f"Processing Frames ({device_to_use.upper()})"
    pbar = tqdm(total=total_frames, unit="frame",
                desc=pbar_desc,
                bar_format="{l_bar}{bar}| {n_fmt}/{total_fmt} [{elapsed}<{remaining}, {rate_fmt}{postfix}]",
                mininterval=0) # mininterval=0 for instant updates. No '\n' in bar_format for single line.

    print(f"🚀 Starting video frame processing on {device_to_use.upper()}...")

    adaptive_controller = PipelineController(
        target_fps=ADAPTIVE_TARGET_FPS,
        initial_filter_strength=ADAPTIVE_FFMPEG_UNSHARP_AMOUNT,
        initial_alpha=ADAPTIVE_INITIAL_ALPHA
    )
    unified_controller = UnifiedModeController(
        motion_threshold=ADAPTIVE_UNIFIED_MOTION_THRESHOLD,
        object_threshold=ADAPTIVE_UNIFIED_OBJECT_THRESHOLD,
        hysteresis=ADAPTIVE_UNIFIED_HYSTERESIS
    )
    class_counts = Counter()
    total_detections = 0
    sum_confidence = 0.0
    frame_fps_samples = []
    prev_gray_for_motion = None
    prev_gray_for_temporal = None
    cached_hf_detail = None
    cached_hf_frame_index = -9999
    cached_roi_mask = None
    roi_mask_last_rebuild = -9999
    prev_loop_time = time.perf_counter()
    prev_output_frame = None
    temporal_blended = False

    try:
        while processing_loop_active:
            if _termination_signal_received:
                raise KeyboardInterrupt
            try:
                # Get frame from input queue (this frame is at effective_tracking_width/height)
                ret, frame_to_process, original_frame = frame_input_queue.get(timeout=1.0)
                if not ret: # End signal or error from reader thread
                    processing_loop_active = False
                    break
                frame_input_queue.task_done()
            except queue.Empty:
                # If queue is empty and reader thread is no longer active, then processing is done
                if not reader_thread.is_alive() and frame_input_queue.empty():
                    processing_loop_active = False;
                    break
                continue # Keep waiting for frames

            frame_count += 1

            # Update utilization stats and progress bar
            util_stats = get_system_utilization(device_to_use)
            pbar.set_postfix_str(format_utilization_string(util_stats), refresh=True)
            pbar.update(1) # Update the tqdm progress bar for each frame processed

            # Track peak hardware utilization for stats.json
            if 'cpu' in util_stats and util_stats['cpu'] > peak_cpu:
                peak_cpu = util_stats['cpu']
            if 'mem' in util_stats:
                ram_mb = util_stats.get('mem_used_gb', 0) * 1024
                if ram_mb > peak_ram_mb:
                    peak_ram_mb = ram_mb
            if 'gpu_load' in util_stats and util_stats['gpu_load'] > peak_gpu_util:
                peak_gpu_util = util_stats['gpu_load']
            if 'gpu_mem_mb' in util_stats and util_stats['gpu_mem_mb'] > peak_vram_mb:
                peak_vram_mb = util_stats['gpu_mem_mb']

            now_loop_time = time.perf_counter()
            instant_fps = 1.0 / max(0.001, (now_loop_time - prev_loop_time))
            prev_loop_time = now_loop_time
            frame_fps_samples.append(instant_fps)

            motion_score = 1.0
            current_gray = None
            try:
                current_gray = cv2.cvtColor(cv2.resize(frame_to_process, (320, 180)), cv2.COLOR_BGR2GRAY)
                if prev_gray_for_motion is not None:
                    motion_score = float(np.mean(cv2.absdiff(current_gray, prev_gray_for_motion))) / 255.0
                prev_gray_for_motion = current_gray
            except Exception:
                pass


            # Perform object tracking on the (potentially lower resolution) frame
            inference_start = time.perf_counter()
            results = model.track(frame_to_process, persist=True, verbose=False, conf=args.confidence_threshold)
            inference_time_ms = (time.perf_counter() - inference_start) * 1000.0
            # Exclude first 5 frames from latency stats (CUDA JIT warmup causes massive spikes)
            if frame_count > 5:
                tracking_stats["frame_latencies"].append(inference_time_ms)

            # Create a copy of the frame to draw annotations on
            annotated_frame = frame_to_process.copy()
            
            # Get frame dimensions for ROI calculations
            frame_h, frame_w = annotated_frame.shape[:2]
            frame_detections = []
            detections_in_frame = 0
            current_centers = {}

            # Draw bounding boxes and labels if objects are detected
            if results and results[0].boxes:
                for box in results[0].boxes:
                    if box.id is None: continue # Skip if no tracking ID
                    cls_id = int(box.cls[0])
                    class_name = model.names[cls_id]
                    track_id = int(box.id[0])

                    # Only draw for allowed classes
                    if class_name in args.allowed_classes:
                        x1,y1,x2,y2=map(int,box.xyxy[0]) # Bounding box coordinates
                        
                        # ROI filtering: skip objects outside the region of interest
                        if roi_enabled and roi_coords:
                            if not is_box_in_roi((x1, y1, x2, y2), roi_coords, frame_w, frame_h):
                                continue  # Skip this detection - outside ROI
                        
                        conf=box.conf[0] # Confidence score
                        conf_float = float(conf)
                        detections_in_frame += 1
                        total_detections += 1
                        sum_confidence += conf_float
                        tracking_stats["total_detections"] += 1
                        tracking_stats["sum_confidence"] += conf_float
                        tracking_stats["unique_ids"].add(track_id)
                        tracking_stats["id_appearances"][track_id] = tracking_stats["id_appearances"].get(track_id, 0) + 1
                        class_counts[class_name] += 1
                        frame_detections.append((x1, y1, x2, y2, class_name, conf_float))

                        # Track motion vectors per object
                        cx, cy = (x1 + x2) / 2.0, (y1 + y2) / 2.0
                        if track_id in prev_centers_for_motion:
                            prev_cx, prev_cy = prev_centers_for_motion[track_id]
                            import math
                            tracking_stats["motion_vectors"].append(math.hypot(cx - prev_cx, cy - prev_cy))
                        current_centers[track_id] = (cx, cy)
                        label=f"ID:{track_id} {class_name} {conf:.2f}"

                        cv2.rectangle(annotated_frame,(x1,y1),(x2,y2),(0,255,0),2) # Green rectangle
                        (tw,th),_=cv2.getTextSize(label,cv2.FONT_HERSHEY_SIMPLEX,0.5,1)
                        cv2.rectangle(annotated_frame,(x1,y1-th-10),(x1+tw,y1-5),(0,255,0),-1) # Background for text
                        cv2.putText(annotated_frame,label,(x1,y1-5),cv2.FONT_HERSHEY_SIMPLEX,0.5,(0,0,0),1) # Black text

            # Update motion vector tracking
            prev_centers_for_motion = current_centers
            tracking_stats["objects_per_frame"].append(detections_in_frame)
            if motion_score < 1.0:  # valid score (not initial)
                tracking_stats["spatial_complexities"].append(motion_score)

            # Draw ROI overlay if enabled
            if roi_enabled and roi_coords and roi_show_overlay:
                annotated_frame = draw_roi_overlay(annotated_frame, roi_coords, roi_overlay_opacity)

            avg_conf_for_mode = (sum_confidence / max(1, total_detections)) if total_detections > 0 else 0.5
            active_mode = unified_controller.decide_mode(motion_score, detections_in_frame, avg_conf_for_mode)
            if active_mode == "A":
                telemetry["mode_a_frames"] += 1
            else:
                telemetry["mode_b_frames"] += 1

            _filter_strength, pid_alpha = adaptive_controller.update(
                instant_fps,
                motion_score,
                frame_output_queue.qsize(),
                avg_conf_for_mode
            )

            # --- Upscale the annotated frame to the final output resolution ---
            annotated_frame_for_output = annotated_frame
            # Only resize if the current frame's dimensions don't match the desired FFmpeg input dimensions.
            # FFmpeg is told to expect `original_width` x `original_height` raw frames.
            if annotated_frame.shape[1] != original_width or annotated_frame.shape[0] != original_height:
                annotated_frame_for_output = cv2.resize(
                    annotated_frame,
                    (original_width, original_height), # Resize to raw dimensions for FFmpeg input
                    interpolation=cv2.INTER_CUBIC
                )
                # print(f"[DEBUG] Resized frame from {annotated_frame.shape[1]}x{annotated_frame.shape[0]} to {original_width}x{original_height} for FFmpeg input.")

            hfdr_state = "NONE"
            should_gate = motion_score >= ADAPTIVE_MOTION_GATE_THRESHOLD
            if should_gate:
                telemetry["hfdr_gated_count"] += 1
                hfdr_state = "GATED"
            else:
                skip_temporal = False
                temporal_blended = False
                if current_gray is not None and (frame_count % ADAPTIVE_TEMPORAL_KEYFRAME_INTERVAL != 0):
                    skip_temporal, _, temporal_blended = should_reuse_frame(current_gray, prev_gray_for_temporal, ADAPTIVE_TEMPORAL_THRESHOLD)

                if current_gray is not None:
                    prev_gray_for_temporal = current_gray

                need_recompute_hf = True
                if skip_temporal and cached_hf_detail is not None:
                    need_recompute_hf = False
                elif cached_hf_detail is not None and (frame_count - cached_hf_frame_index) < max(1, ADAPTIVE_HFDR_CACHE_INTERVAL):
                    need_recompute_hf = False

                if original_frame is not None:
                    try:
                        if annotated_frame_for_output.shape[1] != original_frame.shape[1] or annotated_frame_for_output.shape[0] != original_frame.shape[0]:
                            original_for_hf = cv2.resize(original_frame, (annotated_frame_for_output.shape[1], annotated_frame_for_output.shape[0]), interpolation=cv2.INTER_AREA)
                        else:
                            original_for_hf = original_frame

                        if need_recompute_hf:
                            cached_hf_detail = extract_hf_detail_only(original_for_hf, alpha=pid_alpha, sigma=ADAPTIVE_HFDR_SIGMA)
                            cached_hf_frame_index = frame_count
                            telemetry["hfdr_fresh_count"] += 1
                            hfdr_state = "FRESH"
                        else:
                            telemetry["hfdr_cached_count"] += 1
                            hfdr_state = "CACHED"

                        if cached_hf_detail is not None:
                            if active_mode == "B" and len(frame_detections) > 0:
                                roi_refresh_interval = adaptive_controller.compute_roi_refresh_interval(motion_score)
                                if cached_roi_mask is None or (frame_count - roi_mask_last_rebuild) >= roi_refresh_interval:
                                    cached_roi_mask = build_roi_mask(annotated_frame_for_output.shape, frame_detections, margin=ADAPTIVE_ROI_MARGIN_PX)
                                    roi_mask_last_rebuild = frame_count
                                annotated_frame_for_output = apply_roi_hfdr(annotated_frame_for_output, cached_hf_detail, cached_roi_mask)
                            else:
                                annotated_frame_for_output = apply_hf_detail(annotated_frame_for_output, cached_hf_detail)
                    except Exception as hfdr_error:
                        if frame_count <= 5:
                            print(f"⚠️ [WARNING] HFDR application failed on frame {frame_count}: {hfdr_error}")

            # --- TEMPORAL BLENDING ---
            # If temporal blend is recommended, mix with previous output for smoother transitions
            if temporal_blended and prev_output_frame is not None:
                try:
                    if prev_output_frame.shape == annotated_frame_for_output.shape:
                        annotated_frame_for_output = cv2.addWeighted(
                            annotated_frame_for_output, ADAPTIVE_TEMPORAL_BLEND_ALPHA,
                            prev_output_frame, 1.0 - ADAPTIVE_TEMPORAL_BLEND_ALPHA, 0)
                except Exception:
                    pass

            # Store reference for temporal reuse
            prev_output_frame = annotated_frame_for_output

            print(f"[ADAPTIVE] Mode:{active_mode} | Motion:{motion_score:.4f} | HFDR:{hfdr_state} | FPS:{instant_fps:.2f} | Alpha:{pid_alpha:.3f} | Detections:{detections_in_frame}")

            # Put the upscaled annotated frame into the output queue for the writer thread
            frame_output_queue.put((True, annotated_frame_for_output))

            # Show preview window if enabled
            if show_preview:
                # The preview window should show the final, correctly oriented output.
                # So we need to apply the rotation filter here *for display only*.
                preview_frame_display = annotated_frame_for_output.copy()
                if rotation_angle == 90:
                    preview_frame_display = cv2.rotate(preview_frame_display, cv2.ROTATE_90_CLOCKWISE)
                elif rotation_angle == 270:
                    preview_frame_display = cv2.rotate(preview_frame_display, cv2.ROTATE_90_COUNTERCLOCKWISE)
                elif rotation_angle == 180:
                    preview_frame_display = cv2.rotate(preview_frame_display, cv2.ROTATE_180)
                
                cv2.imshow("Object Tracking", preview_frame_display)
                if cv2.waitKey(1)&0xFF==ord("q"):
                    processing_loop_active=False;
                    break
            del results # Free up memory from YOLO results

    except KeyboardInterrupt:
        print("\n[INFO] KeyboardInterrupt. Stopping processing...");
        processing_loop_active = False
    except Exception as e:
        # Crucially, set processing_loop_active to False IMMEDIATELY when an error occurs in this outer except block.
        processing_loop_active = False # Ensure this is the first thing in the except block
        print(f"❌ [ERROR] An unexpected error occurred in main processing loop: {e}")
    finally:
        print("\n[INFO] Main loop finished. Signaling I/O threads to stop...") # Added newline for cleaner output
        if stop_event: stop_event.set() # Signal reader/writer threads to stop

        # Ensure reader thread finishes
        if reader_thread is not None and reader_thread.is_alive():
            print("[INFO] Waiting for frame reader thread...");
            reader_thread.join(timeout=5.0) # Give it some time to finish
            if reader_thread.is_alive(): print("⚠️ [WARNING] Frame reader didn't finish in time.")

        # Explicitly put a stop signal for the writer, then join it.
        # The writer will close the pipe when it gets this signal or finishes.
        if frame_output_queue is not None:
             frame_output_queue.put((False, None)) # Ensure writer gets the stop signal

        # Ensure writer thread finishes
        if writer_thread is not None and writer_thread.is_alive():
            print("[INFO] Waiting for frame writer thread...");
            writer_thread.join(timeout=10.0) # Give it more time as it might be writing to disk
            if writer_thread.is_alive(): print("⚠️ [WARNING] Frame writer didn't finish in time.")

        pbar.close() # Close tqdm progress bar properly
        if cap.isOpened(): cap.release()
        if show_preview: cv2.destroyAllWindows()

        # Wait for FFmpeg process to finish and check its return code
        # The writer thread should have closed stdin, but ensure it here too for robustness
        try:
            if ffmpeg_process.stdin:
                ffmpeg_process.stdin.close()
        except Exception as e:
            print(f"⚠️ [WARNING] Error closing ffmpeg_process stdin in finally block: {e}")

        ffmpeg_stderr_output = ffmpeg_process.stderr.read().decode('utf-8', errors='ignore')
        ffmpeg_return_code = ffmpeg_process.wait() # Wait for FFmpeg to complete encoding

        if ffmpeg_return_code == 0:
            print(f"✅ [SUCCESS] FFmpeg video encoding completed to '{temp_silent_video_abs_path}'.")
        else:
            print(f"❌ [ERROR] FFmpeg video encoding failed with exit code {ffmpeg_return_code}.")
            print(f"FFmpeg stderr:\n{ffmpeg_stderr_output}")
            # If encoding failed, the temp_silent_video_abs_path might be incomplete or invalid
            if os.path.exists(temp_silent_video_abs_path):
                try:
                    os.remove(temp_silent_video_abs_path)
                    print(f"[CLEANUP] Removed incomplete encoded video '{temp_silent_video_abs_path}'.")
                except OSError as e:
                    print(f"⚠️ [WARNING] Error deleting incomplete video '{temp_silent_video_abs_path}': {e}")
            cleanup_temp_file(recon_normalized_temp_path)
            return # Exit main if video encoding failed

    print(f"✅ [SUCCESS] Video frame processing complete. Silent video encoded to: '{temp_silent_video_abs_path}'.")
    print(f"[INFO] Total frames processed: {frame_count}")

    audio_processing_was_successful = False
    if FFMPEG_AVAILABLE:
        print("[INFO] Starting audio processing...")
        # Merge audio from the original video with the processed silent video
        # The temp_silent_video_abs_path is already correctly oriented, so no need for audio_processing_ffmpeg to apply filters.
        audio_processing_was_successful = process_audio_ffmpeg(current_input_video, temp_silent_video_abs_path, final_output_video_path)
    else:
        # If FFmpeg is not available, the temporary silent video is the final output
        if os.path.exists(temp_silent_video_abs_path):
            try:
                # Ensure the target final output path exists before renaming (remove if it does)
                if os.path.exists(final_output_video_path):
                    os.remove(final_output_video_path)
                os.rename(temp_silent_video_abs_path, final_output_video_path)
                print(f"✅ [SUCCESS] Silent video saved as '{final_output_video_path}'.")
                audio_processing_was_successful = True
            except OSError as e:
                print(f"❌ [ERROR] Could not rename temp silent file to final path: {e}.")

    # Final cleanup of the temporary silent video file
    if os.path.exists(temp_silent_video_abs_path):
        # Only remove if audio processing was successful (meaning the temp file was moved/copied)
        # or if the temp file path is different from the final output path (to avoid deleting the final result)
        if audio_processing_was_successful and os.path.abspath(temp_silent_video_abs_path) != os.path.abspath(final_output_video_path):
            try:
                os.remove(temp_silent_video_abs_path)
                print(f"[CLEANUP] Temp silent video '{temp_silent_video_abs_path}' deleted.")
            except OSError as e:
                print(f"⚠️ [WARNING] Error deleting temporary file '{temp_silent_video_abs_path}': {e}")
        elif not audio_processing_was_successful and os.path.abspath(temp_silent_video_abs_path) == os.path.abspath(final_output_video_path):
            print(f"[INFO] Audio processing failed/skipped. Output is the processed silent video: '{final_output_video_path}'.")
        elif not audio_processing_was_successful:
             print(f"[INFO] Audio processing failed/skipped. Temporary file '{temp_silent_video_abs_path}' is kept for inspection.")

    end_time_total = time.time()
    total_processing_time = end_time_total - start_time_total
    minutes = int(total_processing_time // 60)
    seconds = int(total_processing_time % 60)

    avg_fps = sum(frame_fps_samples) / max(1, len(frame_fps_samples)) if 'frame_fps_samples' in locals() else 0.0
    avg_conf = (sum_confidence / max(1, total_detections)) if 'total_detections' in locals() and total_detections > 0 else 0.0

    # --- Write .stats.json (matches ot_benchmark.py format for production_benchmark.py) ---
    stats_file_path = f"{final_output_video_path}.stats.json"
    try:
        avg_stats_conf = tracking_stats["sum_confidence"] / max(1, tracking_stats["total_detections"])
        avg_objs = sum(tracking_stats["objects_per_frame"]) / max(1, len(tracking_stats["objects_per_frame"]))
        avg_motion = sum(tracking_stats["motion_vectors"]) / max(1, len(tracking_stats["motion_vectors"]))
        avg_complexity = sum(tracking_stats["spatial_complexities"]) / max(1, len(tracking_stats["spatial_complexities"]))
        avg_latency = sum(tracking_stats["frame_latencies"]) / max(1, len(tracking_stats["frame_latencies"]))
        max_objs = max(tracking_stats["objects_per_frame"]) if tracking_stats["objects_per_frame"] else 0
        min_lat = min(tracking_stats["frame_latencies"]) if tracking_stats["frame_latencies"] else 0.0
        max_lat = max(tracking_stats["frame_latencies"]) if tracking_stats["frame_latencies"] else 0.0

        unique_ids_count = len(tracking_stats["unique_ids"])
        id_fragmentation_ratio = unique_ids_count / max(1, max_objs)
        # Real ID switches: count IDs that appeared then disappeared then reappeared
        # For a simple proxy: unique_ids - max_concurrent_objects = extra IDs from identity loss
        id_switches = max(0, unique_ids_count - max_objs)

        final_stats = {
            "YOLO_Confidence_Avg": round(avg_stats_conf, 4),
            "avg_motion_vector_magnitude": round(avg_motion, 4),
            "avg_yolo_objects": round(avg_objs, 4),
            "max_yolo_objects": max_objs,
            "spatial_complexity_index": round(avg_complexity, 6),
            "unique_ids_tracked": unique_ids_count,
            "id_fragmentation_ratio": round(id_fragmentation_ratio, 4),
            "ID_Switches": id_switches,
            "avg_inference_latency_ms": round(avg_latency, 3),
            "min_latency_ms": round(min_lat, 3),
            "max_latency_ms": round(max_lat, 3),
            "total_detections": tracking_stats["total_detections"],
            "avg_pipeline_fps": round(avg_fps, 3),
            "peak_cpu_percent": round(peak_cpu, 2),
            "peak_ram_mb": round(peak_ram_mb, 2),
            "peak_gpu_util_percent": round(peak_gpu_util, 2),
            "peak_vram_mb": round(peak_vram_mb, 2),
            "ffmpeg_encoder": "hevc_nvenc" if NVENC_AVAILABLE else FFMPEG_VIDEO_CODEC,
        }
        # Add adaptive pipeline stats (matches ot_benchmark.py output)
        if 'adaptive_controller' in locals() and adaptive_controller is not None:
            final_stats["adaptive_controller_adjustments"] = adaptive_controller.adjustment_count
            final_stats["adaptive_controller_final_la"] = round(adaptive_controller.filter_strength, 2)
            final_stats["adaptive_controller_final_alpha"] = round(adaptive_controller.hfdr_alpha, 3)
            final_stats["adaptive_controller_avg_fps"] = round(adaptive_controller.avg_fps, 1)
        if 'unified_controller' in locals() and unified_controller is not None:
            final_stats["adaptive_unified_mode_switches"] = unified_controller.mode_switches
            final_stats["adaptive_unified_temporal_frames"] = telemetry.get("mode_a_frames", 0)
            final_stats["adaptive_unified_roi_temporal_frames"] = telemetry.get("mode_b_frames", 0)
        with open(stats_file_path, "w", encoding="utf-8") as stats_file:
            json.dump(final_stats, stats_file, indent=4)
        print(f"📈 [INFO] Stats JSON saved: {stats_file_path}")
    except Exception as stats_err:
        print(f"⚠️ [WARNING] Failed to write stats JSON: {stats_err}")

    # --- Write enriched telemetry JSON ---
    telemetry_payload = {
        "adaptive_profile": ADAPTIVE_PROFILE_NAME,
        "mode_a_frames": telemetry.get("mode_a_frames", 0),
        "mode_b_frames": telemetry.get("mode_b_frames", 0),
        "final_pid_alpha": round(adaptive_controller.hfdr_alpha if 'adaptive_controller' in locals() else ADAPTIVE_INITIAL_ALPHA, 4),
        "avg_fps": round(avg_fps, 3),
        "class_counts": dict(class_counts) if 'class_counts' in locals() else {},
        "total_detections": int(total_detections) if 'total_detections' in locals() else 0,
        "avg_detections_per_frame": round(avg_objs if 'avg_objs' in locals() else 0.0, 3),
        "avg_confidence": round(avg_conf, 4),
        "hfdr_fresh_count": telemetry.get("hfdr_fresh_count", 0),
        "hfdr_cached_count": telemetry.get("hfdr_cached_count", 0),
        "hfdr_gated_count": telemetry.get("hfdr_gated_count", 0),
        "processing_time_s": round(total_processing_time, 3),
        "encode_time_s": round(total_processing_time, 3),
        "ffmpeg_unsharp_amount": telemetry.get("ffmpeg_unsharp_amount", 0.0),
        "ffmpeg_preset": FFMPEG_PRESET,
        "ffmpeg_crf": str(FFMPEG_CRF_VALUE),
        "final_filter_strength": round(adaptive_controller.filter_strength if 'adaptive_controller' in locals() else ADAPTIVE_FFMPEG_UNSHARP_AMOUNT, 2),
        "controller_adjustments": adaptive_controller.adjustment_count if 'adaptive_controller' in locals() else 0,
        "mode_switches": unified_controller.mode_switches if 'unified_controller' in locals() else 0,
        "ffmpeg_encoder": "hevc_nvenc" if NVENC_AVAILABLE else FFMPEG_VIDEO_CODEC,
    }
    telemetry_path = f"{final_output_video_path}.telemetry.json"
    try:
        with open(telemetry_path, "w", encoding="utf-8") as telemetry_file:
            json.dump(telemetry_payload, telemetry_file, indent=2)
        print(f"[INFO] Adaptive telemetry saved: {telemetry_path}")
    except Exception as telemetry_error:
        print(f"⚠️ [WARNING] Failed to write telemetry file: {telemetry_error}")

    if recon_report is not None and not fallback_mode_used:
        try:
            post_recon_report = run_recon(final_output_video_path, project_root)
            if post_recon_report is not None:
                post_json_path = save_recon_json(
                    project_root,
                    final_output_video_path,
                    post_recon_report,
                    suffix="postprocess",
                )
                print(f"[RECON] Post-process analysis saved: {post_json_path}")
            else:
                post_recon_report = recon_report
                print("⚠️ [WARNING] [RECON] Post-process analysis failed; falling back to intake report for CSV row.")

            post_process_row = build_recon_index_row(
                post_recon_report,
                stage="post_process",
                video_filename=os.path.basename(args.input_video),
                normalization_triggered=bool(recon_flags.get("normalization_triggered")),
                normalization_reasons=recon_flags.get("normalization_reasons", []),
                vmaf_score=final_stats.get("VMAF", "") if 'final_stats' in locals() else "",
                mota_score=final_stats.get("MOTA_Score", "") if 'final_stats' in locals() else "",
                gdrive_auto_transcoded=gdrive_auto_transcoded,
            )
            append_recon_index_row(project_root, post_process_row)
        except Exception as recon_csv_error:
            print(f"⚠️ [WARNING] [RECON] Failed to append post_process CSV row: {recon_csv_error}")

    cleanup_temp_file(recon_normalized_temp_path)

    print(f"\n[DONE] Total script execution time: {minutes} minute(s) and {seconds} second(s).")
    print(f"[INFO] Final output video is at: {final_output_video_path}")

if __name__ == "__main__":
    main()