Optimisarr

Safe, verified optimisation for self-hosted media libraries.

Docs • Quick Start • Hardware Acceleration

Optimisarr is an independently maintained media-library optimiser for people running a small self-hosted setup. It can transcode with a CPU or supported GPU, schedule work, and verify output before replacing an original.

_{All media shown in screenshots is fabricated test data created for documentation; no copyrighted material is used.}

Documentation

Start with the documentation index: getting started, configuration, hardware acceleration, reverse proxy, safe replacement, integrations, and troubleshooting.

Project status

Optimisarr is early-stage software. Use it on a small test set first and keep backups of media you cannot replace. It is maintained in spare time, so there is no support SLA or promise of a release schedule.

What it does

• Multiple libraries, each with its own media type (Film/TV/Music/Photo/Other) and rule profile, with a folder-picker for paths. Scanning discovers the file types that match the library (video, audio, or images).

• Recursive, settling-aware scanning that builds a media inventory (idempotent), with automatic background probing of newly discovered files. Enabled libraries are rescanned on a configurable global interval (one hour by default).

• ffprobe inspection (codec, resolution, duration, tracks, media kind).

• Optimisation for video, audio, and still images (images → WebP), each through the same candidate → transcode → verify → quarantine/rollback pipeline.

• FFmpeg/ffprobe tool detection, liveness, and readiness endpoints. Docker health checks verify database access, required writable paths, and media tools.

• Svelte 5 + Tailwind sidebar UI (Dashboard, Libraries, Inventory, Queue, Quarantine, Schedule, Settings; Tools live under Settings). Verification reports are available from Queue and Quarantine detail sheets.

• Queue resource controls: max concurrent jobs, CPU thread limits, and a free work-disk safety pause. The only global scheduling setting is the library scan interval; when work runs is set per library (see auto-optimise below).

• Per-library auto-optimise windows continuously queue newly eligible files; opt-in auto-replace promotes only fully verified jobs, still quarantining the original first so rollback remains available.

• Hardware capability detection for FFmpeg accelerators, CPU encoders, NVIDIA NVENC, Intel QSV, VAAPI, NVIDIA runtime, and /dev/dri mapping.

• Global encoder mode selection for Auto, CPU, NVIDIA NVENC, Intel QSV, and VAAPI.

• Configurable verification gates for duration tolerance, audio/subtitle retention, and required size reduction.

• Hardware transcoding through NVIDIA NVENC, Intel QSV, and Intel/AMD VA-API, with per-encoder availability confirmed by a real test encode (not just inferred), and the encoder used shown per job (GPU/CPU) on the Queue.

• GPU hardware decoding (QSV/VA-API) of the source as well as the encode, on by default, with automatic CPU-decode fallback for sources the GPU can't decode — so a large 4K encode no longer burns a CPU core just on software decode. Skipped for HDR→SDR tonemap jobs (the tonemap runs in software).

• A Queue detail view: click any job for a live progress bar, fps/speed/ETA, the resolved encoder, the verification report, and inline actions — plus a live CPU/GPU usage graph while it encodes (sampled with unprivileged reads only; no root or extra container capabilities). The sidebar's Queue item throbs a GPU chip when work is hardware-accelerated or a snail when it's on the CPU, with a running-job count.

• Optional service-activity pauses (Plex/Jellyfin/Emby), configurable replacement/quarantine policy with a retention window, and library integrations (Plex/Jellyfin/Emby re-scan, Sonarr/Radarr import-aware exclusions, notifications, config-and-secrets backup/import).

Still planned (see the roadmap): dry-run operation and real-hardware validation for AMD VA-API. Intel QSV has been tested on real hardware for both encoding and decoding.

Before you start

• Docker Engine with the Compose plugin.
• Read and write access to the media folders you mount into the container.
• /data, /work, and /trash on the same filesystem if you want atomic replacement moves.
• A backup of media that matters to you. Quarantine and rollback are useful, but they are not a backup strategy.

Quick start (Docker)

The image is published to GHCR on every push to dev:

docker run -d --name optimisarr \
  -p 8787:8787 \
  -e PUID=1000 -e PGID=1000 -e TZ=Europe/London \
  -v /path/to/config:/config \
  -v /path/to/media:/data \
  -v /path/to/work:/work \
  -v /path/to/trash:/trash \
  ghcr.io/jellman86/optimisarr:dev

Open http://localhost:8787, add a library on the Libraries page, then scan it. Compose examples are available for every supported runtime:

• CPU only
• NVIDIA NVENC
• Intel QSV
• Intel or AMD VA-API
• combined reference file

Keep /data, /work, and /trash on the same filesystem so the replacement pipeline can use atomic moves.

Hardware acceleration (GPU)

Transcoding runs through a bundled jellyfin-ffmpeg, which ships NVENC plus the Intel iHD driver and oneVPL runtime — so NVIDIA, Intel (incl. iGPUs like the N100), and AMD GPUs work without installing host driver packages. The encoder is picked by the global encoder mode (Settings → Auto by default); the Tools page shows what each GPU actually supports (availability is confirmed by a real test encode), and each Queue job shows whether it ran on the GPU or CPU.

When a hardware encoder is in use the source is hardware-decoded on the GPU too (Settings → Hardware decoding, on by default), so frames never round-trip through system memory. If the GPU can't decode a particular source, the job automatically retries with software decode rather than failing. The Queue detail view shows a live CPU/GPU usage graph while a job runs — GPU stats are read without any elevated privileges (per-process DRM fdinfo for Intel/AMD, nvidia-smi for NVIDIA), so no extra container capability or compose change is needed; hosts where no unprivileged source applies simply show "GPU stats unavailable".

• NVIDIA (NVENC): install the NVIDIA Container Toolkit on the host and run with --gpus all. You must also set NVIDIA_DRIVER_CAPABILITIES=compute,video,utility — without the video capability the NVENC library isn't injected and encoding fails with Cannot load libnvidia-encode.so.1 even though nvidia-smi works.

• Intel (QSV / VA-API) and AMD (VA-API): map the render node and add the container to the host's render group:

  docker run -d --name optimisarr \
    --device /dev/dri:/dev/dri \
    --group-add "$(getent group render | cut -d: -f3)" \
    ... ghcr.io/jellman86/optimisarr:dev

Use the matching Compose example: NVIDIA NVENC, Intel QSV, or Intel/AMD VA-API. A CPU-only file is also provided.

Development

Standards and commands live in CLAUDE.md. In short:

dotnet build Optimisarr.slnx      # backend
dotnet test  Optimisarr.slnx      # tests
cd web && npm run check           # frontend type/lint check
cd web && npm run dev             # frontend dev server (proxies /api to :8787)

License

Optimisarr is licensed under the GNU General Public License v3.0. The published Docker image also bundles GPL-licensed FFmpeg (jellyfin-ffmpeg), which remains under its own license.

Project references

• Changelog
• Product and architecture
• Roadmap
• Engineering standards
• Security policy
• Support
• Contributing
• Code of Conduct