DOCSEARCHbyAlgolia
Submit Docs

Unmanic Documentation

website·Indexed 32 days ago

https://docs.unmanic.app/

Documentation for Unmanic, an automated media processing tool. Includes guides on installation (Docker, Windows, macOS, pip), library configuration, event monitoring, and hardware-accelerated encoding via NVIDIA and VAAPI. Provides comprehensive developer resources for writing Python plugins, managing plugin repositories, and using the Plugin Manager CLI.

Tokens
35.2K
Snippets
114
Records
226
Agent score
64%

What's inside Unmanic

  1. Overview of Unmanic media optimization

    Unmanic is an open-source (GPL v3) tool designed to automatically optimize media libraries for storage efficiency. It runs in the background to continuously apply user-defined compression and cleanup rules as new content arrives or old content is revisited. Key capabilities include:

    • Removing bloat: Stripping unnecessary streams, attachments, or metadata.
    • Standardizing outputs: Ensuring consistent formats and settings across the library.
    • Compressing media: Using FFmpeg to shrink video and audio files while preserving desired tracks.
    • File conversion: Converting documents to PDFs, normalizing image metadata, and fixing orientation.

  2. Overview of Unmanic file processing workflow

    Unmanic automatically processes files by scanning configured libraries and detecting work based on a plugin-based system. The core workflow consists of:

    1. Monitoring: Unmanic monitors one or more libraries (directories) for files.
    2. Detection: Plugins determine if a file requires processing.
    3. Queueing: Files identified for work are added to a pending tasks queue.
    4. Execution: Workers pick up tasks and execute the assigned plugins in a sequential flow, performing operations in the order defined for that specific library.

  3. Overview of Unmanic file library optimization

    Unmanic is a tool designed to optimize file libraries by converting files into uniform formats, managing file movements based on timestamps, or executing custom commands based on file size. It automates library management through four primary mechanisms:

    1. Built-in Scheduler: Scans the entire library for files that do not match configured file presets and adds them to a processing queue.
    2. File/Directory Monitor: Detects new or modified files and tests them against presets to determine if they need processing.
    3. Task Handler: Manages the concurrent execution of multiple file manipulation tasks.
    4. Web UI: Provides a graphical interface to configure, manage, and monitor the optimization progress of the library.

  4. Understand Unmanic linking and remote task flow

    Linking allows multiple Unmanic installations to cooperate, enabling tasks to be processed across different machines while maintaining centralized control. The general workflow is:

    1. A local installation connects to one or more remote installations.
    2. Tasks are queued on the local installation.
    3. When a remote installation is available and configured to receive tasks, tasks are assigned to it.
    4. The task is processed on the remote worker, and results are returned to the local installation for post-processing.

  5. Share state between plugins using the Task Data Store helper

    The Task Data Store helper allows plugins to share state between runners and other plugins within a single task. This data is transient and only exists for the duration of the task. It is only available in the main Unmanic process; child processes cannot access it. Metadata size per plugin is limited to 32KB.

  6. Understand Unmanic Plugin Architecture

    Unmanic plugins are stand-alone Python modules executed at defined stages during the library optimization process. When a plugin is called, Unmanic provides it with data regarding the current task state or the process about to be carried out. Plugins can use this data to manipulate the subsequent process or perform functions outside the scope of the Unmanic application. While a single plugin can be designed to run at multiple stages, the best practice is to design each plugin to perform a single task.

  7. Unlock Supporter features in Unmanic

    Supporter access unlocks several advanced capabilities in Unmanic, including unlimited libraries, unlimited linked installations, advanced plugin options, Unmanic Central features, and access to supporter community channels. To activate these features, you must sign in and link your Unmanic instance with an account that has supporter status.

  8. Understand Unmanic Worker concurrency and scaling

    Workers are responsible for executing the main processing tasks in Unmanic. They run simultaneously and execute commands as sub-processes in true parallelism (not bound to a single thread). Unmanic supports up to 12 concurrent workers. It is recommended to start with one worker and gradually increase the count to balance system resource usage with processing speed.

  9. Manage a fleet with Unmanic Central

    Unmanic Central is a supporter-only dashboard for managing multiple Unmanic installations from a single interface. It uses a self-hosted Unmanic Central Datastore to keep data on your own infrastructure.

    Features include:

    • Custom Dashboards: Create widgets for worker status, resource usage (CPU/RAM), uptime, library size, and scan history.
    • Centralized Logging: View and filter logs from all installations in one stream, with the ability to focus on errors.
    • Processing Insights: Track file-size metrics and total savings sliced by time range or outcome.
    • Kiosk Mode: Automatic refresh for wall displays.
    • External Integration: Connect Grafana directly to the datastore for advanced reporting.

  10. Understand the Unmanic file processing workflow

    Unmanic processes files through a sequential pipeline:

    1. Discovery: Files are identified via library scanning, file system event monitoring, or API submission.
    2. File Testing: Library Management - File Test plugins determine if a file needs processing. If a plugin requests a task, the file is queued; if it requests ignore, the file is skipped.
    3. Queuing: Files are placed in the pending tasks queue.
    4. Worker Processing: Workers execute Worker - Process plugins in sequence. Each plugin performs an internal test and writes output to a temporary cache directory (typically /tmp/unmanic) to protect original files.
    5. File Movement: By default, successful tasks overwrite the original source file with the cached version. Post-processor - File Movement plugins can override this behavior.
    6. Results Processing: Post-processor - Task Results plugins handle notifications, media server updates, and cleanup.

  11. Enable NVIDIA hardware acceleration for Unmanic plugins

    While Unmanic itself does not require hardware acceleration, specific plugins (such as the Transcode Videos plugin) can utilize NVIDIA NVDEC and NVENC for faster video decoding and encoding. To enable this, you must have a compatible NVIDIA GPU, the correct drivers installed, and an FFmpeg build with NVENC support.

  12. Start developing Unmanic plugins

    Developers should begin with the plugin development overview and guides. For those using AI agents or with limited coding experience, the tool.plugin-builder project (https://github.com/Unmanic/tool.plugin-builder) provides a docker-compose environment for creation and testing, helper scripts for repo management, and targeted instructions for LLM agents.