Media Renamer

A Python tool for renaming movie folders and files with proper IMDB-style formatting using The Movie Database (TMDB) API.

What it does

Media Renamer takes movie folders with inconsistent naming and renames them (and all files within) to a standardised format that includes IMDB identifiers. This is particularly useful for media server applications like Plex that benefit from consistent, metadata-rich file naming.

Example transformation

Before:

Beverly Hills Cop Axel F (2024)/
├── Beverly Hills Cop Axel F (2024).mkv
├── Beverly Hills Cop Axel F (2024).1208527.srt
├── Beverly Hills Cop Axel F (2024).1208528.srt
└── Beverly Hills Cop Axel F (2024).1208529.srt

After:

Beverly Hills Cop -- Axel F (2024) {imdb-tt3083016}/
├── Beverly Hills Cop -- Axel F (2024) {imdb-tt3083016}.mkv
├── Beverly Hills Cop -- Axel F (2024) {imdb-tt3083016}.1208527.srt
├── Beverly Hills Cop -- Axel F (2024) {imdb-tt3083016}.1208528.srt
└── Beverly Hills Cop -- Axel F (2024) {imdb-tt3083016}.1208529.srt

Features

• Interactive search: Presents multiple options from TMDB with cast information
• Fuzzy folder name parsing: Handles torrent-style names with quality/codec tags and group identifiers. A multi-candidate pipeline extracts the clean title from before the year token, strips known technical tokens (resolution, codec, audio, release flags such as WS, Multi, EAC3, etc.), and falls back through progressively simpler queries until TMDB returns a match
• Tolerant year matching: Year is used as a soft ranking signal rather than a hard filter — results for the right film ranked by year proximity, so an off-by-one label won't discard correct matches
• Intelligent filename sanitisation: Replaces problematic characters (: becomes --, / becomes or, etc.)
• Comprehensive renaming: Renames both folders and all files within them
• Flexible input: Accepts custom rename strings or skips items entirely
• Safe operation: Checks for existing target folders to prevent conflicts
• Comprehensive test suite: Includes pytest-based tests with mocked API calls

Installation

Via pipx (recommended)

pipx install media-renamer

Then save your TMDB API key:

media-renamer --set-api-key your_api_key_here

This writes the key to ~/.media-renamer.conf and you're ready to go. As a fallback, the TMDB_API_KEY environment variable is also accepted.

From source

1. Clone the repository:

   git clone <repository-url>
   cd media-renamer
   

2. Create a virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Make scripts executable:

   chmod +x media-renamer
   chmod +x replicate-structure
   

Setup

Get a TMDB API Key

1. Create a free account at The Movie Database
2. Go to API Settings and request an API key
3. Save it:

   media-renamer --set-api-key your_api_key_here
   

   This writes the key to ~/.media-renamer.conf.

Usage

Basic usage

./media-renamer <folder_pattern>

Examples

Rename all movie folders in current directory:

./media-renamer "*"

Rename specific folders:

./media-renamer "Beverly Hills Cop*" "Bridget Jones*"

Supported folder name formats

The tool handles a range of naming conventions:

Format	Example
Clean with year	Beverly Hills Cop Axel F (2024)
Torrent with quality/group tags	Aniara (2019) (1080p BluRay x265 HEVC 10bit DTS 5.1 Qman) [UTR]
Dot-separated with release flags	Sexy.Beast.2000.WS.1080p.BluRay.x265.HEVC.EAC3-SARTRE
Multi-language / HDR torrent	The.Mummy.1999.Multi.2160p.BluRay.x265.HDR.DTS-HDMA.7.1.[En+Hi]-DTOne
Underscore separators	The_Dark_Knight_(2008)
No year	Some Movie [YTS]

Year mismatches of one or two years are tolerated — the correct film will still appear in the results, ranked by proximity to the folder's year.

Interactive process

When you run the tool, it will:

1. Parse each folder name to extract title and year (stripping torrent noise)

2. Search TMDB for matching movies, ranked by year proximity

3. Present up to 3 options with cast information:

   Looking up Beverly Hills Cop Axel F (2024)...
   1) Beverly Hills Cop -- Axel F (2024) {imdb-tt3083016} (Beverly Hills Cop: Axel F; 2024; Eddie Murphy, Joseph Gordon-Levitt, Taylour Paige)
   2) Beverly Hills Cop -- Axel F (2024) {imdb-tt8874500} (Beverly Hills Cop: Axel F; 2024; Behind the Scenes)
   3) Beverly Hills Cop -- Axel F (2024) {imdb-tt9876543} (Beverly Hills Cop: Axel F; 2024; Documentary)
   Choose 1-3, or enter a new rename string, or nothing to skip:
   >
   

4. You can:

   • Enter a number (1-3) to select one of the options
   • Type a custom rename string
   • Press Enter to skip this folder

Filename formatting rules

The tool follows these character replacement rules for safe filenames:

Character	Replacement	Reason
:	--	Subtitle separator
/	or	Alternative indicator
\	or	Alternative indicator
<>	()	Bracket substitution
"	'	Quote substitution
|	,	List separator
?	!	Question to exclamation
*	x	Wildcard to letter

Testing

The project includes a comprehensive test suite using pytest.

Run tests

pytest

Create test data

Use the included replicate-structure script to create a test directory structure:

./replicate-structure /path/to/your/movies ./test-data

This creates a copy of your directory structure with empty files, perfect for testing without risking your actual media files.

Test coverage

The test suite covers:

• Folder name parsing
• Filename sanitisation
• Movie name formatting
• TMDB API integration (mocked)
• Complete renaming workflows
• Edge cases and error handling

File structure

media-renamer/
├── media_renamer.py        # Main module
├── media-renamer           # CLI entry point
├── replicate-structure     # Test data generator
├── test_media_renamer.py   # Test suite
├── requirements.txt        # Dev dependencies (requests, pytest, pytest-mock)
├── pyproject.toml          # Package configuration
└── README.md              # This file

Requirements

• Python 3.7+
• requests - For TMDB API calls
• pytest / pytest-mock - For running tests

Compatibility

This tool is designed to work with:

• Plex Media Server - The naming format is optimised for Plex's metadata agents
• Other media servers - The standardised format should work with most media management tools
• General file organisation - Useful for anyone wanting consistent movie file naming

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run the test suite
5. Submit a pull request

Acknowledgements

• The Movie Database (TMDB) for providing the comprehensive movie API
• Plex for inspiring the naming format standards
• Originally designed to complement a browser extension for enhanced IMDB search results https://github.com/lorenzowood/plex_name_formatter_extension