VMAFOptimiser/MAINTENANCE.md

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:

   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.