JellyPlugins/jellyfin-helper

🤖 Jellyfin plugin with ML-powered per-user recommendations, watch activity insights, automated media cleanup (trickplay, subtitles, symlinks, .strm), Overseerr/Jellyseerr request management, codec/health statistics, growth trends, trash bin, backup/restore & multi-instance Radarr/Sonarr. 8-tab dashboard, 8 languages.

stars

396

commits

primary language

Sep 9, 2026

updated

jellyplugins.github.io/jellyfin-helper/

arr-stack

backup

cleanup

dashboard

dotnet

health-check

i18n

jellyfin

jellyfin-plugin

machinelearning

media-server

radarr

recommendation

seerr

sonarr

statistics

strm

subtitles

symlink

trickplay

Browse cluster: Jellyfin Media Server Plugins →

README

Jellyfin Helper

A Jellyfin plugin that provides automated cleanup tasks, media library statistics, ML-powered smart recommendations, user activity insights, health checks, and Arr stack integration, all from a single, multi-tab dashboard.

AI disclosure: This project is AI-assisted but not vibe-coded. AI is used as a partner for post-change reviews, discussing specific problems, quick analysis, suggestions, and spell checking, never as a substitute for the logic, regression testing, code coverage, and static checks that gate every change. The i18n and parts of the UI are the main AI-generated portions. It was built with a great deal of effort and care, and we deliberately do not trust AI blindly.

Project

Quality

Stack

Live Demo

Try the interactive demo →

Explore the full 8-tab dashboard with realistic sample data. No Jellyfin server required.

Features

Feature	Description
8-Tab Dashboard	Overview, Codecs, Health, Trends, Discover, Settings, Arr, Logs, all accessible directly from the Jellyfin sidebar as a single plugin page
Trickplay Cleaner	Automatically finds and removes orphaned `.trickplay` folders whose corresponding media file no longer exists. Frees disk space from stale image extraction data
Empty Folder Cleaner	Deletes now-empty media folders that no longer contain video files (e.g. after manual cleanup). Skips known placeholder folders (Radarr/Sonarr), metadata-only folders, and music libraries
Subtitle Cleaner	Detects and removes orphaned `.srt`/`.ass`/`.vtt` subtitle files that no longer have a matching video. Uses ISO 639 language-code detection to avoid false positives
Link Repair	Scans for broken `.strm` files and broken symlinks, then automatically repairs them by locating the renamed or moved target media file in the parent directory of the original target
Seerr Cleanup	Connects to your Overseerr/Jellyseerr/Seerr instance and removes media requests whose underlying files are no longer available. Keeps your request list clean and in sync with actual media
Seerr Discovery	Personalized external content discovery via your Seerr instance. Scores TMDb candidates per user using the ensemble ML strategy, suggests not-yet-in-library media with one-click request submission, parental rating enforcement, and automatic exclusion of items already in your Jellyfin library or in Radarr/Sonarr. Note: this library exclusion covers your entire library and ignores the recommendation Excluded Libraries setting on purpose. Discovery only suggests titles you do not already own, so excluding a library hides its titles from recommendations but never makes Discovery offer to acquire copies you already have. It can optionally be displayed on the Jellyfin home screen as a Custom Tab when used with the Custom Tabs and File Transformation plugins
Statistics & Trends	Per-library disk usage, video codec, audio codec, resolution, dynamic range, and container format analysis, extracted from Jellyfin MediaStream metadata. eBook (Book) libraries are included in the storage overview and totals.
Growth Timeline	Cumulative media growth stored losslessly at daily resolution. Scroll or pinch to zoom, drag or swipe to pan; the scale adapts between day/week/month/year and the size axis rescales to the visible window. Hover any point to see the exact file count and size delta since that date
Library Insights	Top-10 largest media directories and recently added/changed items (last 30 days) per library, with per-library size breakdown. Displayed in the Trends tab with 15-min in-memory cache
Health Checks	Detects videos without subtitles (including embedded streams), missing artwork, missing NFO files, and orphaned metadata directories
Arr Integration	Compare your Jellyfin library with up to 3 Radarr + 3 Sonarr instances to find items only in Arr, only in Jellyfin, or in both
Backup & Restore	Export/import the full plugin state (configuration, growth timeline, baseline data, Arr instances) as a validated JSON file with XSS/injection protection
Log Viewer	Plugin-specific logs with level/source filtering, auto-refresh (10s), and download as `.log` file. Isolated from Jellyfin's main log to reduce noise
Trash / Recycle Bin	Cleanup tasks move files to a timestamped trash folder instead of permanently deleting them. Configurable retention period auto-purges expired items
8 Languages	Full UI translations: English, German, French, Spanish, Portuguese, Chinese, Turkish, Swedish
Smart Recommendations	ML-powered per-user recommendations using ensemble scoring (heuristic + learned + neural MLP blend). Analyses watch history to build genre, actor, director and studio affinity profiles, then scores unwatched candidates using 38 features. Children with restricted profiles only see age-appropriate recommendations. Incremental training runs only when TaskMode=Activate, with ranking-based evaluation and pre-computed collaborative filtering pipeline. Pure C# implementation with zero external ML dependencies
User Activity	Per-item and per-user watch activity tracking with play count, completion percentage, favorites detection, and genre distribution, displayed in the new Discover tab
Security	5-min statistics cache, 30s rate limiting, path traversal protection, XSS escaping, backup payload validation with size limits and injection detection, parental rating enforcement in recommendations
Unsaved Settings Alert	Warns before navigating away when the settings form has unsaved changes (dirty-tracking via snapshot comparison), with Discard / Save & Continue / Cancel options

All tasks default to Dry Run mode. Nothing is deleted until you explicitly activate them.

Compatibility: Jellyfin 12.0+ · .NET 10.0

Using Jellyfin 10.x? Stay on plugin version v2.1.0.6, which remains available in the repository. Version 3.x targets Jellyfin 12.0 and will not install on older servers.

Installation

From Repository (Recommended)

In Jellyfin, go to Dashboard → Plugins → Repositories

Add this repository URL:

https://raw.githubusercontent.com/JellyPlugins/jellyfin-helper/main/manifest.json

Go to Catalog and install Jellyfin Helper
Restart Jellyfin

Manual Installation

Download the latest release package from Releases
Extract the package and copy all files into your Jellyfin plugin directory (e.g. /config/plugins/JellyfinHelper/)
Restart Jellyfin

Quick Start

Open Jellyfin Helper from the sidebar. The last scan loads automatically
Go to the Settings tab to configure tasks, libraries, trash, and language
Review Dry Run results in the Jellyfin scheduled tasks log
Switch tasks to Activate when ready
The Helper Cleanup scheduled task runs weekly (Sunday 3:00 AM) or trigger it manually

Documentation

Resource	Description
CONTRIBUTING.md	Architecture, design patterns, build system, API reference, configuration, testing
CHANGELOG.md	Detailed version history
Live Demo	Interactive dashboard demo

Origin

Based on jellyfin-trickplay-folder-cleaner by @Noir1992, which was inspired by this community script by @S2ciOnur. This fork evolved into an independent project with significant additions.