MKV Subtitle Extractor & Parser

A file name that carries everything

The heart of the tool is a strict naming convention:

(basename)[.default][.(lang)][.(hi)][.forced].Extracted[(counter)].(ext)

The order of those parts is not decoration. The default flag comes first so Jellyfin can pick the main track. The language follows as a code Jellyfin parses reliably. HI or SDH stays next to the language, then the forced flag, then the source tag.

The source tag does a job of its own. Jellyfin does not parse custom flags, it shows them exactly as written, so .Extracted marks tracks from the container and capitalised .External marks collected ones. OpenSubtitles downloads keep plain default naming with no tag. So one folder can hold Movie.en.Extracted.srt, Movie.de.cc.External.srt and Movie.default.en.forced.srt, and in the interface you can see where each one came from.

Only one custom flag is allowed per file, and .Extracted can be removed from the code if you do not want it. Embedded tracks stay in the MKV as the base layer, and nothing is removed from the file.

The result in Jellyfin is a consistent order: default tracks first, then the other languages, HI and SDH tracks, and forced tracks.

Some typical results:

The counter exists because of a Jellyfin limit. Sublanguages such as pt-br are not supported, even though this has been widely requested. So two Portuguese tracks become Movie.pt.Extracted.srt and Movie.pt.Extracted1.srt, numbered by track ID, which is the only reliable fallback. It comes up with Portuguese, Spanish and Chinese. The counter is deterministic, so a repeated run gives the same names, it appears only for tracks Jellyfin cannot tell apart, and default tracks take priority in a collision. .Extracted1 also reads better in the interface than a bare number.

The language codes deserve a word too. All ISO 639-2 codes, including alternatives and legacy variants, become ISO 639-1, because Jellyfin parses those most reliably. Not all of them get parsed in the end, but they are at least recognised as a language and shown in the right column. Undefined and und codes count as no language. The mapping file is a plain list like ger=de that you can extend yourself.

How it runs

Install Python 3 and MKVToolNix and add both to the system path. The script sits in a folder with a mapping file for languages and a plain list of the folders to scan, recursively.

1. Put mapping.txt and paths.txt next to the script, with one folder per line in the paths file.
2. Run python MKVSubExtractJellyParse.py in a console, or by double click with a .bat shortcut.
3. Enter a language filter such as en, or leave it empty for all languages.
4. Pick the subtitle filter: all, text or image tracks.
5. Pick the mode: simulate or extract.
6. Read the output and the report before you extract for real.

The files land next to the MKV they came from. For each file the console shows the track ID, type, language and future name, text in yellow and images in blue, followed by a short count of text and image tracks.

Simulation is the part I recommend. It prints every future file name without writing anything. For each file, mkvmerge -J reads the tracks as JSON, a pattern finds HI and SDH in the track names, the mapping file turns all ISO 639-2 codes and legacy variants into ISO 639-1, and mkvextract then writes the files: .srt and .ass for text, .sub and .idx or .sup for images.

The report at the end is worth reading. It lists tracks with no language and tracks with three-letter codes the mapping could not parse, which get passed on 1:1 as a fallback, so you see which MKVs have bad metadata. In testing about 1 percent, 25 of 2,500, were completely faulty, and 2 of 2,500 had unparseable codes. Metadata can also be plain strange: a default forced track with no language happens, and the script still names it strictly by what it finds. A track with both HI and forced was not excluded, but it never turned up in testing.

What testing did not catch

I spent several days comparing the internal subtitles with the extracted ones on sample files, and everything looked right. A bug was hiding in a place those files did not reach.

LiamKarlMitchell had a file whose subtitles would not load in Jellyfin. The track was ASS, but the script wrote it with an .srt extension. Jellyfin picks its parser by extension, so the player's worker crashed. He tracked it down and sent a pull request that fixes it and adds an optional language filter. It was merged 1:1, and I thank him at the top of the README. He also reported that subtitles now load in about 2 seconds on a Samsung TV, and suggested it could become a plugin that runs on a schedule.

The rest of the history is mostly the README, where the naming rules were sharpened. An early .OpenSubtitles tag and sublanguage examples like pt-br are gone: downloads keep default naming, and Jellyfin does not parse sublanguages.