dragosmiron / immich-video-optimizer

# 🎬 Immich Video Optimizer
A terminal client for Immich that drastically reduces storage usage by re-encoding high-bitrate videos to HEVC (H.265) using local hardware acceleration, while flawlessly preserving original metadata, creation dates, GPS coordinates, album memberships, tags, stack membership, and favorite status.
---
## ✨ Features
- **Hardware Acceleration:** Native support for Apple Silicon & Intel (`hevc_videotoolbox`), NVIDIA (`hevc_nvenc`), and Intel Linux (`hevc_vaapi`), with automatic CPU fallback (`libx265`).
- **Full Metadata & State Preservation:** Preserves camera make/model, original shooting dates, GPS coordinates, original filenames, user album memberships, tags, stack membership, and favorite status.
- **Smart Filtering & Remote Probing:** Filter scans by bitrate density (`MB/min`), total file size, or date range (`YYYY-MM-DD`). Automatically detects and skips existing HEVC videos remotely without downloading them.
- **External Library Safety:** Automatically excludes read-only and external library assets from scans to protect external storage mounts.
- **Incremental Scans (Tagging):** Tags replaced videos (`immich-optimizer`) so previously optimized videos can be skipped on future scans.
- **Dry Run & Size Guard:** Preview estimated space savings before encoding. If a re-encoded video ends up larger than the original, replacement is skipped automatically.
- **Adjustable Quality:** 1–10 quality slider ranging from High Compression (~70–80% savings) to Visually Lossless (~15–20% savings), plus custom FFmpeg flags support.
- **Low-Footprint & Resumable:** Downloads, transcodes, and streams uploads in parallel while keeping at most 2 temporary videos on disk. Pause anytime and resume later where you left off.
- **Timestamped Gzip Log Rotation:** Automatically rotates logs when they exceed 10 MB and archives them to compressed `.log.gz` files to save disk space.
- **Universal Config Auto-Healing:** Automatically restores missing or deleted config items with defaults and repairs invalid settings on startup.
---
## 📖 Table of Contents
- Features
- Prerequisites
- Installation
 - Option 1: Pre-Compiled Binary (Recommended)
 - Option 2: Build From Source
- Usage & Workflow
 - Step 1: Connect to Immich
 - Step 2: Scan & Filter Candidates
 - Step 3: Configure Settings
 - Step 4: Dry Run & Savings Preview
 - Step 5: Run Batch Optimization
 - CLI Flags
- Configuration
 - Configuration File Locations
 - Annotated `config.yaml` Reference
 - Universal Config Auto-Healing
- Logs & Diagnostics
 - Log File Locations
 - Checking & Inspecting Logs
 - Automatic Log Rotation & Gzip Archiving
- Safety & Data Protection
 - Zero-Data-Loss Pipeline
 - Tracking Albums & Verification
 - Note for Mobile Users: "Free Up Space"
- Development & Testing
- License
---
## 📋 Prerequisites
Immich Video Optimizer requires **`ffmpeg`** and **`exiftool`** installed and available in your system `PATH`:
- **macOS (Homebrew):**
 [code] 
- **Linux (Debian / Ubuntu):