TV Episode Manager turns a shelf of MakeMKV TV rips into a correctly labelled Jellyfin library. It scans disc and season folders, identifies episodes by comparing dialogue with reference subtitles, and lets you review matches before renaming files in place.
Approved episodes can be encoded with HandBrake into Jellyfin-ready MKV files. The application supports multi-episode titles split by chapter, persistent encoding queues, optional automation, and validation that checks the finished video, audio, subtitles, chapters, and duration before publishing it.
The project is Linux-only and keeps source rips unchanged. It stores credentials in the desktop keyring, does not upload video files, and requires user review for uncertain matches, duplicates, and validation failures. Development phases 0–10 are complete; additional production-workstation validation and ongoing maintenance remain.
Repository and release metadata are refreshed from Gitea during the static site build when the build environment has access to the repository.
Repository README
Turn a shelf of MakeMKV TV rips into a tidy, correctly labelled Jellyfin library, without guessing which file is which episode.
TV Episode Manager is a desktop application for Linux. It looks at the files MakeMKV produced (title_t00.mkv,
title_t01.mkv, …) and works out which episode each one is by comparing its dialogue with the episode’s
subtitles. You review and approve the matches; then it encodes each episode with HandBrake and files it as
Series - S01E03.mkv in a Jellyfin-ready folder. Your original rips are never moved, modified or deleted.
Everything is done in the application window. You don’t need a terminal after installation.
Why
DVD and Blu-ray discs rarely store episodes in order, and MakeMKV names its output by title number. A disc of
four episodes becomes title_t00.mkv to title_t03.mkv, sometimes plus a “play all” title holding every
episode. Working out which file is which usually means watching the start of each one. This application does
that by listening (or reading) instead, and shows you how sure it is.
What it does
- Finds your rips. It scans a
Ripped/<Series>/Season NN/<disc>/folder tree and inspects every file (length, video, audio and subtitle tracks, chapters). Files still being ripped are left alone until they stop changing. - Fetches episode information. Series, seasons and episode titles come from TMDB.
Reference subtitles for each episode can be downloaded from OpenSubtitles.com
or imported from your own
.srtfiles. - Identifies episodes by their dialogue. It reads each file’s own English subtitle track (DVD and Blu-ray picture subtitles are read with Tesseract OCR). Without one, it transcribes short audio samples with Faster Whisper, which runs on your computer. It then compares the text with every episode’s reference subtitles. Strong matches are proposed; uncertain ones, duplicates and missing references are shown for you to decide, never guessed.
- Renames in place, with undo. Approved files are renamed inside their disc folder
(
Series - S01E03.mkv; the pattern is configurable). Disc folders are never renamed or reorganized, and nothing is ever overwritten. - Splits multi-episode titles. When one file holds several episodes, Configure Episode Segments divides it into episodes by its chapters (for example five chapters per episode). Each episode can be checked by its own dialogue and is later encoded straight from that one file. The file itself is never split or changed.
- Encodes with HandBrake. Built-in DVD HQ (up to 720p) and Blu-ray HQ (up to 1080p) profiles produce MKV files with H.264 video (Intel Quick Sync by default), an AAC stereo track named Stereo (the default), the original surround track passed through as Surround, English soft subtitles named English, and chapter markers. Video is never upscaled. You can import your own HandBrake presets instead.
- Checks every encode before publishing it. Each output is validated: container, codec, resolution, aspect
ratio (allowing for HandBrake’s cropping), length, track layout, names and default flags. Track names and flags
are fixed with
mkvpropeditwhen needed. Anything else is held back for review instead of appearing in your library. - Keeps a persistent queue. Jobs survive restarts, show live progress, speed and time remaining, and can be paused, cancelled, retried and reordered. If the application closes mid-encode, the job starts again next time.
- Automates as much as you want. Optional, off by default, and switched on step by step: notice new rips, identify, accept strong matches, rename, queue and encode. Anything uncertain always waits for you.
- Diagnoses its own setup. The Diagnostics page checks the tools, HandBrake and Quick Sync, folder access, free space, credentials and the database, and can run a 30-second Quick Sync test encode.
What it never does
- Move, modify or delete your source video files, or rename your disc folders.
- Overwrite an existing file.
- Publish an encode that failed validation, or a whole multi-episode title as if it were one episode.
- Accept an uncertain or duplicate episode match without asking you.
- Use
sudo, install system packages or drivers, or change HandBrake’s Flatpak permissions. - Store your API keys or passwords in plain files or logs (they go to the desktop keyring).
Requirements
- Linux. Developed and used on Linux Mint 22.3 (Cinnamon). Ubuntu 24.04 and other distributions with Python 3.12 should work, but are untested.
- Python 3.12 or newer, with
python3-venv. - FFmpeg (including FFprobe). Required.
- HandBrake as the Flatpak
fr.handbrake.ghb, for encoding. Without it, everything except encoding still works. - Intel Quick Sync for the default profiles’ hardware encoding. Without it, enable Allow software fallback (x264) on the profile in Encoding Profiles. The application never falls back to software silently.
- MKVToolNix (
mkvpropedit), recommended, to correct track names after encoding. - Tesseract OCR with English data, recommended, to read DVD and Blu-ray subtitles. Without it, the audio is used.
- A free TMDB API key. An OpenSubtitles.com account and API key are optional, for downloading reference subtitles.
On Linux Mint or Ubuntu:
sudo apt install python3-venv libxcb-cursor0 ffmpeg mkvtoolnix tesseract-ocr tesseract-ocr-eng
HandBrake (if you don’t have it yet):
flatpak install flathub fr.handbrake.ghb
Install
git clone https://git.darksingularity.org/DarkSingularity/TVRipper.git ~/Applications/TVRipper
~/Applications/TVRipper/scripts/install-linux.sh
The script checks the requirements (listing anything missing with the apt command to run), installs the
application into its own Python environment in ~/.local/lib/tv-episode-manager/, and adds TV Episode
Manager to the applications menu under Sound & Video.
To update, pull and run the script again. Your settings and library are kept, and the database is backed up automatically before any upgrade:
cd ~/Applications/TVRipper && git pull && scripts/install-linux.sh
To uninstall, use Help → Remove from Applications Menu, then delete ~/.local/lib/tv-episode-manager.
Your data stays in the folders listed under Where your data is kept until you delete
them.
Getting started
- Settings → Folders: choose the folder that holds your rips (the ripped media root) and where finished episodes should go (the encoded media root, for example your Jellyfin TV library).
- Settings → Metadata and reference subtitles: enter your TMDB API key and, optionally, your OpenSubtitles.com details. Test buttons check them.
- Diagnostics → Run Checks: everything important should show a green tick. On a Quick Sync machine, run the Quick Sync test encode once.
- Ripped Library → Rescan to find your rips.
- Metadata & Subtitles: match each series to TMDB once, then download or import the reference subtitles for the seasons you’re working on.
- Episode Identification: identify the files, review the proposals, approve them, and rename them.
- Encoding Queue: add the approved episodes and press Start Queue.
The user guide explains every page.
How your files are laid out
Rips are expected in MakeMKV’s usual layout. Any disc folder name works, and season folders named Season 01,
Season 1, S01 or Specials are recognized (anything else can be corrected in the application):
Ripped/
└── Show Name/
└── Season 01/
└── SHOW_NAME_S1_D1/
├── title_t00.mkv → renamed in place to Show Name - S01E01.mkv
└── title_t01.mkv → Show Name - S01E02.mkv
Finished episodes go to the encoded media root, organized the way Jellyfin expects:
Encoded/
└── Show Name/
└── Season 01/
├── Show Name - S01E01.mkv
└── Show Name - S01E02.mkv
Discs with several episodes in one file
Some DVDs store a whole disc’s episodes as one long title. Select that file in the Ripped Library and choose Configure Episode Segments…:
- Enter how many chapters make up an episode and click Generate Segments. Check the ranges against the chapter list.
- Choose the season and first episode and click Assign Episodes in Order. Optionally, Identify All checks each segment’s episode by its own dialogue.
- Select the segments, click Approve Selected, then Add Approved to Encoding Queue.
Each episode becomes its own encoding job. It encodes only that episode’s chapters and is checked against the episode’s length and chapters. The settings can be saved as a rule and reused for the next disc.
Privacy and network use
The application contacts only:
- TMDB, for series and episode information (with your API key);
- OpenSubtitles.com, only if you enter an account, to download reference subtitles (this uses your download quota);
- Hugging Face, once, to download the speech recognition model, and only after you agree. Speech recognition then runs entirely on your computer.
Your video files are never uploaded. There is no telemetry, and the application switches off the usage reporting built into the libraries it uses (onnxruntime, which Faster Whisper uses for voice detection, and huggingface_hub). API keys and passwords are kept in the desktop keyring (GNOME Keyring or another Secret Service), never in settings files or logs.
Where your data is kept
| What | Where |
|---|---|
| Settings | ~/.config/tv-episode-manager/settings.json |
| Library database | ~/.local/share/tv-episode-manager/library.sqlite3 (backed up before each schema upgrade) |
| Reference subtitles | ~/.local/share/tv-episode-manager/reference-subtitles/ |
| Caches (artwork, speech model, OCR and transcripts) | ~/.cache/tv-episode-manager/ |
| Logs and window layout | ~/.local/state/tv-episode-manager/ |
| TMDB and OpenSubtitles.com credentials | the desktop keyring |
The XDG_*_HOME environment variables are honoured.
Status and limitations
TV Episode Manager is in active use, but young. Please keep backups of anything you can’t rip again.
- Used on a real ripping workstation (Linux Mint 22.3, HandBrake 1.11.2 Flatpak): a multi-episode DVD title was split into five episodes, identified by dialogue, encoded with Intel Quick Sync and validated. Blu-ray encodes with Quick Sync and imported HandBrake presets haven’t been tried on that machine yet.
- Built for English-language shows: identification, the English subtitle track and the track languages assume English.
- Linux only. It relies on the HandBrake Flatpak and the freedesktop keyring.
- Episode identification needs reference subtitles for the season. Matches are only accepted automatically when every episode of the season has one.
- Multi-episode titles are split by chapter. Splitting by timestamps (for titles without chapter markers) isn’t available yet.
- Automatic processing runs only while the application is open; there is no background service.
See docs/PROJECT_STATUS.md for details and CHANGELOG.md for what changed in each release.
Development
Python 3.12, PySide6 (Qt Widgets) and SQLite. The application starts without HandBrake, Quick Sync, MakeMKV or MKVToolNix; missing tools only disable the features that need them.
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/tv-episode-manager
.venv/bin/pytest
The tests use generated media and a mock HandBrake, so they need FFmpeg but neither HandBrake nor Quick Sync.
TVEM_HANDBRAKE_TESTS=1 adds real software encodes with the HandBrake Flatpak. See
docs/TESTING.md.
Documentation:
- User guide: the complete graphical workflow
- Deployment: installation details and the production checklist
- Architecture: structure, services and data model
- Requirements and the multi-episode specification
- Development plan and project status
Acknowledgements
TV Episode Manager builds on HandBrake, FFmpeg, MKVToolNix, Tesseract, Faster Whisper, Qt for Python and RapidFuzz. It is designed for rips made with MakeMKV and libraries served by Jellyfin. It is not affiliated with or endorsed by any of these projects.
This product uses the TMDB API but is not endorsed or certified by TMDB. Subtitle downloads are provided by OpenSubtitles.com.
License
Copyright © 2026 Keith Smith.
TV Episode Manager is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License, version 3 or (at your option) any later version. It is distributed in the hope that it will be useful, but without any warranty; see the license for details.
If you run a modified version of TV Episode Manager as a network service, you must make your modified source available to its users.
A DarkSingularity project.