Differences

This shows you the differences between two versions of the page.

--- automation:unmanic [2025/12/20 17:25] – created - external edit 127.0.0.1
+++ automation:unmanic [2025/12/20 18:53] (current) – privacyl0st
@@ Line 1: / Line 1: @@
+====== 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.