JellyfinToolkit

Project Overview

Jellyfin Toolkit is a desktop GUI that gathers the day-to-day tidying of a Jellyfin or Emby media library into one window. Jellyfin and Emby share the same API lineage and this tool supports both: library data can be read straight from local database files or fetched over the server API. It analyses viewing data to understand your taste and rank by hit rate so you can decide what to keep, such as which titles you are tired of, which episodes can be merged, which videos lack subtitles, which NFO files no longer match their file names and which files need repair.

Media library housekeeping moved from the command line into a window, with every destructive action reversible.

Key Features

• Library overview: reads the library and reports total titles, distributions by year, studio and actor, saved and watched or unwatched counts and the number of duplicate groups
• Taste profile: builds a personal profile from favorites and viewing behaviour, lists top actors, studios and genres, recommends 20 unwatched titles, exports CSV and can call a local AI for analysis
• Quick tagging: fast card-based tagging with like, dislike, skip and delete, re-ranking scores in real time
• Delete staging: builds a low-hit list with reasons, moves files to the system recycle bin and journals each deletion
• Duplicate handling: finds versions of the same title at different resolutions or with different mosaic status, groups them and keeps the best
• Mosaic detection: splits library videos into mosaic and non-mosaic by keyword, file name and tags
• Subtitle detection and generation: scans folders for videos without subtitles and can batch-generate them, deduplicating and splitting long lines afterwards
• Restored-file replacement: works with Lada to move files named like xxx.restored.mp4 back into their original folders and adjusts library data so NFO and subtitles still resolve
• Mosaic removal: batch-invokes Lada with concurrency and output duration checks
• Video repair and transcoding: finds damaged or incompatible downloads and repairs or transcodes them into Jellyfin and Emby friendly MP4 with GPU acceleration
• NFO association repair: fixes mismatches between NFO file names and their contents
• Database tools: inspect table schemas, move data across databases and clean up .ts leftovers
• Episode merging: losslessly merges episodic releases into a single file
• Onboarding: a step-by-step guide on first run

Target Audience

• Users running a self-hosted Jellyfin or Emby library who need batch cleanup
• Users who want viewing behaviour to drive what to delete first
• Users who need to detect and generate subtitles and repair damaged files

Quick Start

1. Download JellyfinToolkit-vX.Y.Z-win64.zip from Releases, unzip it and run JellyfinToolkit.exe
2. You can also run from source: start.bat on Windows, or chmod +x start.sh && ./start.sh on macOS and Linux
3. Follow the onboarding, then choose a database file or the server API under Settings → Library Data Source, using Auto Detect if needed
4. For a server setup, fill in the address and API key under Settings → Server Sync and press Test Connection
5. For transcoding, repair or merging, point the tool at ffmpeg under Settings → FFmpeg Transcoding, or drop ffmpeg.exe and ffprobe.exe into the bin/ folder next to the program

Core Advantages

• Both servers supported: direct database reading auto-detects the new Jellyfin 10.9 and above schema and the traditional schema used by earlier Jellyfin and by Emby, and the server type is detected automatically
• Flexible data sources: automatic, database-only or API-only; API is recommended for Emby and works when the server lives on a NAS or in Docker
• No destructive surprises: deletes go to the system recycle bin and are journaled, merges back up first and every change can be rolled back
• Privacy friendly: no uploads, no telemetry and no network access unless you configure an endpoint, with read-only database access and GET-only API calls

System Requirements

Item	Requirement
OS	Windows 10/11, macOS, Linux, anywhere PySide6 runs
Python	3.9 or newer, 3.11 to 3.13 recommended
Dependencies	PySide6
External tools	FFmpeg and ffprobe for repair, transcoding and merging; other features work without them
Optional	A Jellyfin or Emby server with an API key
Optional	A local LLM such as Ollama or LM Studio over an OpenAI-compatible endpoint for AI review

Notes

• Back up your media library before running, since any batch file operation carries risk
• Subtitle generation needs a Faster-Whisper infer.exe and mosaic removal needs Lada's lada-cli.exe; neither ships with this repository
• The automation workbench is not finished yet, so leave it alone for now
• If an unavailable hardware encoder is selected, the tool falls back to libx264 with a notice instead of failing
• Uninstalling means deleting the program folder and the data folder, with no registry leftovers or hidden services