# VMAF Optimizer - Maintenance Guide

## Project Goals
To automatically optimize a large video library (TV Shows & Content) on Windows using an **AMD RX 9070 XT** GPU.
The goal is to reduce file size while maintaining "Visually Lossless" quality (VMAF 93+).

## Core Strategy
1.  **Hybrid Encoding:**
    *   **Encode:** Use Hardware Acceleration (`av1_amf` / `hevc_amf`) for speed (critical for 2TB+ library).
    *   **Verify:** Use `ab-av1` (software) strictly for VMAF score calculation.
2.  **Safety Net:**
    *   Extract a 60s sample.
    *   Encode sample with AV1 (QP 32).
    *   Calculate VMAF & Savings.
    *   **Decision Logic:**
        *   If VMAF > 97: Re-encode with higher QP (more compression) to save space.
        *   If VMAF < 93 or Savings < 12%: Fallback to HEVC.
        *   If HEVC fails: Keep original.
3.  **Architecture:**
    *   `smart_gpu_encoder.py`: The "Engine". Handles logic, ffmpeg calls, VMAF checks. Can run standalone.
    *   `smart_monitor.py`: The "UI/Controller". Runs the engine in threads, displays a TUI (Rich), handles caching and directory scanning.

## Current Status
*   **Working:**
    *   Hardware detection (AMD/NVIDIA/Intel).
    *   VMAF calculation (fixed regex for raw number output).
    *   Optimization logic (Smart QP adjustment).
    *   Multithreading (4 workers).
    *   Caching (Instant startup on second run).
*   **Issues:**
    *   **UI Progress:** The TUI shows "Action" but Progress/Speed columns are empty.
        *   *Root Cause:* `smart_gpu_encoder.py` sends status updates like `Encoding AV1 (size=...)` but `smart_monitor.py` expects format `Action | Progress% | Speed`.
    *   **Logs:** User reported logs might be hard to find or missing if permissions fail on `Z:`.

## Debugging Instructions
To run a simplified test without scanning the whole library:
1.  Create a folder `test_media` with 1 small video file.
2.  Run:
    ```powershell
    python smart_gpu_encoder.py --tv-dir ".\test_media" --content-dir ".\test_media" --jobs 1
    ```

## Future Todos
1.  **Fix TUI Parsing:** Update `smart_gpu_encoder.py` to format strings as `Action | Percent% | Speed`.
2.  **Sonarr Integration:** Add webhook triggers on success.
3.  **Linux Support:** Verify `av1_qsv` or `av1_vaapi` flags for Linux/Docker deployments.

---
**Key Files:**
*   `smart_gpu_encoder.py`: Core logic.
*   `smart_monitor.py`: TUI and Watchdog.
*   `library_cache.json`: Cache of scanned files to speed up startup.