Universal Media Renamer for Jellyfin/Plex

A smart, cross-platform Python tool that renames TV show files so they work perfectly with Jellyfin, Plex, and other media servers without breaking your existing folder structure.

⚠️ Disclaimer This tool is under active development. Always use --dry-run first and test on backups or small batches. Pull requests, feedback, and issues are welcome!

The Problem

You have 100 TV show files with inconsistent naming like:

• Breaking.Bad.S01E01.Pilot.720p.WEB-DL.x264-GROUP.mkv
• Doctor.Who.2005.S05E04.Time.Of.The.Angels.HDTV.XviD-FoV.avi
• [Erai-raws] Cyberpunk - Edgerunners - 01 [1080p][Multiple Subtitle].mkv

Jellyfin and Plex need them consistently named:

• Breaking Bad (2008) - S01E01 - Pilot.mkv
• Doctor Who (2005) - S05E04 - Time of the Angels.avi
• Cyberpunk Edgerunners - S01E01.mkv

This tool automates that transformation, handling codec tags, quality indicators, release groups, and anime/fansub formats automatically. It works safely with --dry-run so you preview changes before applying them.

Quick Start (TL;DR)

# Install from source
pip install .

# Or install in development mode
python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"

# ALWAYS preview first (safe, shows what would change)
rename --dry-run "/path/to/TV Shows/Breaking Bad (2008)"

# Once you're happy with the preview:
rename "/path/to/TV Shows/Breaking Bad (2008)"

# For anime/fansub releases:
rename --anime --dry-run "/path/to/Anime/Cyberpunk Edgerunners (2022)"

# With metadata cleanup (removes internal codec info from files):
rename --deep-clean --dry-run "/path/to/TV Shows/Breaking Bad (2008)"

Sample dry-run output

[DRY] Breaking.Bad.S01E01.Pilot.720p.WEB-DL.x264-GROUP.mkv
    → Breaking Bad (2008) - S01E01 - Pilot.mkv

Windows/WSL note: For --deep-clean, install MKVToolNix, FFmpeg, and MediaInfo inside WSL, not on Windows. The tool needs them available in the WSL environment.

How It Works

The tool automatically:

• Detects series name from your folder structure (e.g., "Breaking Bad (2008)" → "Breaking Bad")
• Recognizes episode patterns:
  • Standard TV: S01E01, S01 E01, 1x01, 01x01
  • Anime/Fansub: [Group] Show - 01 [Quality], Show - 01 [Metadata]
• Extracts episode titles using boundary detection to separate real titles from technical metadata
• Cleans filenames by removing:
  • Quality indicators (720p, 1080p, 4K, etc.)
  • Codec info (x264, x265, HEVC)
  • Source tags (WEB, BluRay, HDTV, etc.)
  • Platform tags (AMZN, NFLX, HULU)
  • Release group names and hash codes
• Preserves meaningful content like "(Part 1)" or "(Director's Cut)" while removing technical junk
• Handles subtitles by automatically renaming .srt files to match their video, preserving language codes
• Optionally cleans internal metadata with --deep-clean (removes codec info embedded inside MKV/MP4 files)

Folder Structure Requirements

IMPORTANT: This tool works best with properly organized TV show folders. Each show should have its own folder:

Recommended Structure

TV Shows/
├── Breaking Bad (2008)/
│   ├── Season 1/
│   │   ├── Breaking.Bad.S01E01.Pilot.720p.WEB-DL.x264-GROUP.mkv
│   │   └── Breaking.Bad.S01E02.Cat's.in.the.Bag.720p.WEB-DL.x264-GROUP.mkv
│   └── Season 2/
│       └── episode files...
├── Doctor Who (2005)/
│   ├── Season 5/
│   │   └── Doctor.Who.2005.S05E04.Time.Of.The.Angels.HDTV.XviD-FoV.avi
│   └── Specials/
│       └── special episode files...
└── 3 Body Problem (2024)/
    └── Season 1/
        └── episode files...

What NOT to do

Mixed Folder/
├── Breaking.Bad.S01E01.mkv          ← Will become "Mixed Folder - S01E01.mkv"
├── Doctor.Who.S05E04.avi            ← Will become "Mixed Folder - S05E04.avi"
└── 3.Body.Problem.S01E01.mkv        ← Will become "Mixed Folder - S01E01.mkv"

The tool uses your folder name as the series name. Organize each show into its own folder before running.

Command-Line Flags

Combining Flags

rename --anime --deep-clean --format "Show - SxxExx" --verbose --dry-run "/path/to/anime"

Output Formats

Choose how your final filenames look:

Recommended: Use Show (Year) - SxxExx for TV shows, Show - SxxExx for anime.

Deep Clean Feature (--deep-clean)

This option cleans internal metadata from video files and renames companion files (subtitles, artwork, NFO).

What It Does

• MKV files: Clears container titles and removes technical metadata tags from video/audio/subtitle tracks. The streams themselves are untouched—only their internal title labels are removed.
• MP4 files: Sets clean container title (only if file contains problematic metadata)
• Companion files: Renames external .srt, .nfo, .jpg files to match their video, preserving language codes (e.g., show.en.srt stays show.en.srt)

About Internal Track Titles

If your MKV has 5 subtitle streams with internal titles (common in multi-language releases), --deep-clean will clear those title labels. The subtitle streams themselves remain intact—this is normal and expected for multi-language files. External subtitle files (.srt, .ass) are handled separately and keep their language codes intact.

Anime Mode (--anime)

Use this for fansub releases and anime with non-standard naming. The flag:

• Prioritizes anime patterns like - 01 [Quality] over standard TV patterns
• Defaults season to 01 for single-season shows
• Changes default format to Show - SxxExx (cleaner for anime)
• Handles fansub groups like [Erai-raws], [SubsPlease], [HorribleSubs]
• Removes hash codes and complex metadata

Example

# Before:
[Erai-raws] Cyberpunk - Edgerunners - 01 [1080p][Multiple Subtitle][ABC123].mkv

# After (with --anime):
Cyberpunk Edgerunners - S01E01.mkv

Concrete Examples

Standard TV Show

rename --dry-run "/path/to/TV Shows/Breaking Bad (2008)"

Converts all files to: Breaking Bad (2008) - S01E01.mkv format

TV Show with Episode Titles and Metadata Cleanup

rename --deep-clean --format "Show (Year) - SxxExx - Title" --dry-run "/path/to/show"

Anime/Fansub

rename --anime --deep-clean --dry-run "/path/to/Cyberpunk Edgerunners (2022)"

Converts anime files to: Cyberpunk Edgerunners - S01E01.mkv

Override Series Name

rename --series "My Little Pony Friendship Is Magic" --dry-run "/path/to/mlp"

Multiple Shows at Once

for show in "/path/to/TV Shows"/*; do
    rename --dry-run "$show"
done

Safety Features

• Idempotent: Safe to run multiple times. Re-running on already-renamed files results in no changes.
• Validation: Checks file existence and prevents accidental overwrites
• Dry-run: Preview all changes before applying them
• Collision handling: If target file exists, the tool skips it unless --force is used
• Permission handling: Automatically fixes read-only files when possible
• No double-processing: Companion files renamed once, not twice
• Graceful errors: Detailed messages if something goes wrong

Supported File Types

Troubleshooting

No files found

• Check extensions are supported (mkv, mp4, avi, etc.)
• Verify the path is correct
• Use --verbose to see detection details

Episode patterns not detected

• For spaced formats like S01 E01: These work automatically
• For anime: Try the --anime flag
• For unusual formats: Use --series "Name" to override detection

Series name not detected correctly

• Ensure proper folder structure: Each show in its own folder
• Use --series "Exact Name" to override
• Check folder name contains the series name (e.g., "Breaking Bad (2008)")

Episode titles not clean

• Try --format "Show - SxxExx" to skip titles altogether
• Use --series "Name" for better cleaning
• For anime, use --anime which defaults to no titles

Permission errors

• The tool automatically fixes read-only files
• Ensure you have write permissions to the directory
• On WSL, check Windows file permissions

Metadata cleanup not working

• Install MKVToolNix inside WSL (not just on Windows)
• Check files are actually MKV format
• Use --verbose to see processing details

Known Limitations

• Multi-episode files like S01E01-E02 are treated as the first episode (S01E01)
• Specials may map as Season 00 depending on folder layout—ensure Specials folders are recognized or use --series override

Essential Tips

1. Always use --dry-run first — it's your safety net
2. Test on a small batch before processing large collections
3. Organize shows in separate folders — one show per folder, one run per show
4. Make backups of important collections
5. Use --verbose when debugging — it shows exactly what the tool is detecting

Installation

From Source

git clone https://github.com/Phatnoir/jellyfin-renamer.git
cd jellyfin-renamer
pip install .

Development Mode

pip install -e ".[dev]"

This installs the package in editable mode (code changes take effect immediately) with dev dependencies (pytest, etc.).

Running Tests

pytest Tests/

Requirements

• Python 3.10 or higher
• No external dependencies for basic operation

Optional Dependencies (for --deep-clean)

• MKVToolNix - Ubuntu/Debian: sudo apt install mkvtoolnix; macOS: brew install mkvtoolnix
• FFmpeg - Ubuntu/Debian: sudo apt install ffmpeg; macOS: brew install ffmpeg
• MediaInfo - Ubuntu/Debian: sudo apt install mediainfo; macOS: brew install mediainfo

The tool works without these but will skip metadata cleanup.

Contributors

Thanks to the following people who have contributed to this project:

• @matthiasbeyer - Added shellcheck CI workflow for the original Bash implementation

License

MIT. See LICENSE for details. Provided as-is, without warranty.