FFmpeg-Easy-Unraid

A "Set and Forget" Batch Transcoder designed for Unraid. Convert your media library (Movies, TV Series) to modern, space-saving formats (H.265/HEVC or AV1) with ease.

📖 About The Project

FFmpeg-Easy-Unraid is a Docker container built to simplify the process of shrinking large video libraries. It automatically scans an input directory, converts video files to highly efficient formats, and moves the original files to a "finished" folder upon success.

It is designed to be robust ("fail-safe"), supporting modern hardware acceleration while protecting your server from freezing via intelligent CPU monitoring.

Key Features

• Run-Once Workflow: This container is designed to run on demand. It scans the /import directory on startup, processes the queue, and stops automatically when finished. It does not continuously monitor the folder to save resources. To process a new batch, simply restart the container.
• Modern Codecs: Supports H.265 (HEVC) and AV1.
• Hardware Acceleration: Full support for Nvidia NVENC, Intel QuickSync/Arc, and optimized CPU encoding.
• Smart Workflow:
  • Scans /import for media.
  • Transcodes to /export.
  • Moves successfully processed originals to /import/finished.
  • Directory Preservation: Perfect for TV Shows! Recursively scans folders and recreates the exact directory structure (e.g., Series Name/Season 1/) in the output.
• Safety First: Detects if CPU pinning is active. If not, it automatically limits thread usage to 50% of available cores to prevent Unraid from freezing.
• Detailed Stats: Displays exact space savings (GB/MB and %) after every run.
• Container Standardization: Automatically outputs to .MKV for maximum compatibility with subtitles and audio tracks.

🟢 How to Enable Nvidia Support (Important!)

By default, Docker containers cannot see your Graphics Card. To enable Nvidia NVENC support, follow these steps strictly:

Step 1: Install the Driver

In Unraid, go to the "Apps" tab (Community Applications) and install the "Nvidia Driver" plugin. Reboot if asked.

Step 2: Configure the Container

When adding or editing this container in Unraid:

1. Switch to "Advanced View" (toggle in the top right corner).

2. Find the field "Extra Parameters".

3. Add the following text to the end of the line (separated by a space):

   --runtime=nvidia
   *(Note: Do not remove `--cap-add=SYS_NICE` if it is already there. Just add this after it.)*
   

4. Find the Variable "Nvidia Visible Devices" (in Advanced View).

• Set this to your GPU UUID (recommended, found in the Nvidia Driver Plugin settings).
• OR set it to all if you only have one GPU.

1. Apply the changes.

The container will now perform a hardware check on startup. If successful, logs will show [INIT] Hardware check passed.

⚖️ CPU vs. GPU Encoding: What should I choose?

• Choose CPU Encoding (cpu_h265) if you want the best possible compression efficiency and quality preservation. CPU encoders (libx265) are generally smarter than GPU encoders, resulting in smaller files for the same visual quality. Ideally, use this for long-term archiving.
• Choose GPU Encoding (nvidia_... / intel_...) if speed is your priority. GPUs can process files much faster, but the file size might be slightly larger to achieve the same visual quality compared to CPU encoding.

⚙️ Prerequisites

1. For Intel GPU Encoding (QuickSync / Arc)

• Device Mapping: You must pass the device /dev/dri to the container.
• AV1 Support: Requires an Intel Arc GPU or newer iGPU (Meteor Lake+).

2. For CPU Encoding

• Recommendation: Use CPU Pinning in the Unraid Docker settings to assign specific cores. If you forget this, the script's safety mode will engage (limiting to 50% load).

🚀 Configuration & Environment Variables

The container is controlled via Environment Variables.

A Note on Defaults

Why these default values? The default settings (CRF 18 for H.265 / CRF 24 for AV1) are chosen based on extensive personal testing. In my experience, these values represent the "Sweet Spot": they provide significant file size reduction while maintaining visual quality that is virtually indistinguishable from the source. Unless you have specific needs, I recommend leaving the Quality fields empty to use these smart defaults.

Variable List

📂 Folder Structure (Mappings)

You need to map two volumes in Docker/Unraid:

1. Input: Map your source media folder to /import.

• Note: The container needs Read/Write access to move finished files to /import/finished.

1. Output: Map your destination folder to /export.

Example Workflow:

1. You place a TV Show folder MySeries/Season 1/Episode 1.mkv in /import.
2. Script converts it and saves the new version to /export/MySeries/Season 1/Episode 1.mkv.
3. Script moves the original to /import/finished/MySeries/Season 1/Episode 1.mkv.
4. Container Stops. To convert new files later, simply restart the container.

📜 License

Distributed under the GPL-3.0 license. See LICENSE for more information.

Author: metronade