====== Unmanic – General Configuration Guide ======

**Purpose:**  
Unmanic is the content transcoding and media optimization engine in your automation ecosystem. Its primary goal is to convert incoming media files into formats that balance **efficient resource utilization** and **high-quality playback** across devices, while integrating seamlessly with your acquisition pipeline (Prowlarr, Jackett, Sonarr, Radarr, qbittorrent).  

Installed in a **Python virtual environment** on your bare-metal Plex Media Server, Unmanic handles CPU/GPU-aware video and audio transcoding, subtitle extraction, and file management, ensuring that your library stays consistent and optimized with minimal manual intervention.

---

===== Key Concepts =====

  * **Plugins Stack** – Unmanic operates as a sequence of plugins applied in processing order. Plugins can manage file acceptance, transcoding, subtitle handling, and post-processing tasks.  
  * **Hardware Utilization** – Unmanic can leverage NVIDIA GPUs (`nvenc`), Intel QuickSync (`qsv`), or CPU-based transcoding. Optimal configuration balances CPU/GPU usage with quality and throughput.  
  * **Library Safety** – Built-in filters prevent files from being unnecessarily re-encoded, reduce duplication, and reject output larger than the original.  
  * **Subtitle Handling** – All ASS or embedded subtitles are converted to SRT, and unwanted image-based subtitle streams are removed to maximize compatibility.

---

===== Best Practices and General Configuration =====

=== 1. Library Management / Pre-Processing ===
These plugins determine which files are processed and how:

  * **Ignore Recently Modified** – Skip files modified in the last hour to avoid partial or actively written files.  
  * **Ignore Under Size** – Minimum file size threshold of 300 MB prevents transcoding very small clips.  
  * **Ignore Video File Under Resolution** – Default target 720p, ignoring 480p/SDTV content unless explicitly required.  
  * **Reject File if Larger than Original** – Prevents unnecessary bloating.  
  * **Subtitle Extraction & Conversion** – All ASS subtitles converted to SRT; image subtitles stripped or removed.  
  * **Stream Stripping** – Remove extraneous image streams and non-essential audio/subtitle languages to optimize file size.

=== 2. Worker / Processing ===
Processing plugins handle actual transcoding and audio/video handling:

  * **Video Transcoding** – Default codec: `hevc_nvenc` with CRF-style quality targeting. GPU `nvenc` device 0 used, preset `p6`, tune `hq`, main profile `main`. Smart filters applied, black bar autocropping enabled. Target resolution `source` (keeps original unless otherwise specified).  
  * **Audio Transcoding** – Main codec `aac` via standard VBR or AC3 encoder as fallback. Average bitrate 192 kbps; stereo fallback audio added to ensure device compatibility.  
  * **Stream Cleanup** – Remove unneeded image streams, unnecessary subtitle languages, and extra audio tracks.  
  * **Container & Output** – Output container: MKV; original container kept only if no transcoding applied.

=== 3. Post-Processing ===
Final checks and library integration:

  * **Reject File if Larger than Original** – Last safeguard.  
  * **Notifications** – Radarr, Sonarr, and Plex are notified on task success or failure.  
  * **Subtitle & Transcode Completion** – Ensure all SRT subtitles are properly extracted; verify audio/video transcodes completed.

---

===== Specific Tuning From Our Configuration =====

  * **Video Transcoder (`video_transcoder`)**  
    - `mode`: standard  
    - `video_encoder`: `hevc_nvenc` (GPU 0)  
    - `preset`: 4 (`p6` for NVENC)  
    - `tune`: `hq`  
    - `CRF` based quality: 23  
    - Smart filters enabled  
    - Autocrop black bars enabled  
    - Target resolution: source  
    - Strip extra streams and attachments  

  * **Audio Transcoder (`audio_transcoder`)**  
    - Codec: AAC (VBR, 192 kbps)  
    - AC3 fallback for compatibility  
    - Extra stereo track added where applicable  

  * **Subtitle Handling**  
    - Extract all SRTs, convert any ASS to SRT  
    - Remove image-based subtitles  

  * **Filters**  
    - Ignore files under 300 MB  
    - Ignore files modified <1h ago  
    - Ignore video under 720p by default  
    - Remove unwanted subtitle languages (all non-English / non-primary languages)

---

===== Hardware Considerations =====

  * **CPU** – Multithreaded CPU usage is supported; efficient for smaller transcodes.  
  * **GPU** – NVIDIA NVENC preferred for HEVC hardware acceleration; ensures high throughput without overloading CPU.  
  * **RAM** – Recommended minimum 16 GB for a moderate library, more for concurrent transcodes.  
  * **Disk I/O** – SSD/NVMe recommended for active working folders; NFS mounts acceptable but slower.  
  * **Python Virtual Environment** – Ensures clean dependency management without affecting system Python.

---

===== Tips for New Users =====

  * Start with a small test folder to ensure your hardware, GPU, and filters behave as expected.  
  * Always test Fallback AAC/AC3 audio to ensure device compatibility before bulk processing.  
  * Monitor logs for skipped or rejected files; this often indicates file size, resolution, or filter mismatches.  
  * Update Unmanic regularly; plugin improvements and bug fixes are frequent.

---

This guide is designed to get a new user running **quickly with our optimized configuration**, balancing **high quality** and **efficient resource use** while minimizing library disruption. Detailed plugin tuning or per-file troubleshooting should be referenced in the official plugin documentation as needed.