2026-01-01 13:00:39 -05:00

6.0 KiB

Raw Blame History

renamarr

A rolling rename utility for Sonarr and Radarr that safely triggers filename updates with staggered delays. Useful for avoiding API rate limits or filesystem locks when renaming large numbers of episodes/movies.

Features

Staggered Renames: Configurable delays between rename operations to avoid overwhelming your server
Progress Tracking: Automatically tracks completed renames across runs—re-runs skip already-processed files
Sonarr & Radarr Support: Works with both TV series (Sonarr) and movies (Radarr)
Selective Renaming: Filter by season number to rename specific seasons only
Cross-Platform Path Mapping: Converts between local and server paths (Windows ↔ Linux)
Detailed Logging: JSON-formatted logs with timestamps, file paths, and episode details
Smart Caching: Caches series/movie metadata to minimize API calls

Requirements

Python 3.7+
Sonarr v3+ and/or Radarr with API access
Network access to your Sonarr/Radarr instance

Installation

Clone or download this repository
Install dependencies:
```
pip install requests
```

Configure config.xml with your Sonarr/Radarr details:

<?xml version="1.0"?>
<config>
    <path_mappings>
        <mapping from="P:\tv" to="/mnt/plex/tv"/>
        <mapping from="P:\anime" to="/mnt/plex/anime"/>
        <mapping from="P:\movies" to="/mnt/plex/movies"/>
    </path_mappings>
    <services>
        <sonarr>
            <url>http://10.0.0.10:8989</url>
            <api_key>your_sonarr_api_key_here</api_key>
        </sonarr>
        <radarr>
            <url>http://10.0.0.10:7878</url>
            <api_key>your_radarr_api_key_here</api_key>
        </radarr>
    </services>
</config>

Usage

Basic Usage

Rename all episodes in a series:

python main.py "P:\tv\Breaking Bad"

With Options

Rename only a specific season:

python main.py "P:\tv\Breaking Bad" -s 5

Customize wait time between renames (in seconds):

python main.py "P:\tv\Breaking Bad" -w 60

Combine options:

python main.py "P:\tv\Supernatural" --season 15 --wait 180

Interactive Mode

If you run without a folder argument, the script will prompt you:

python main.py
Enter series folder path: P:\tv\Breaking Bad

Configuration

config.xml

Path Mappings: Map local paths to server paths. This is essential if:

Your local machine uses Windows (P:\tv) but Sonarr runs on Linux (/mnt/plex/tv)
You provide a server path to the script and need it converted to local for verification

Services: Add your Sonarr/Radarr URLs and API keys. You can find API keys in:

Sonarr: Settings → General → API Key
Radarr: Settings → General → API Key

How It Works

Initialization: Loads Sonarr/Radarr caches to find your series/movie
Filtering: Identifies episodes/movies with files, optionally filters by season
Progress Check: Loads progress tracking to skip already-renamed files
Rolling Renames: Triggers one rename at a time with configurable delays
Progress Saving: Updates progress after each rename to resume if interrupted

Progress is stored in logs/rolling_rename_progress.json and includes:

Series/movie ID and title
Count of completed vs total episodes
Timestamp of each rename

Output

Logs are stored in logs/rolling_rename.log with detailed JSON entries:

{"timestamp": "2026-01-01T17:47:04Z", "level": "INFO", "message": "[1/12] Breaking Bad - S05E01 - Fifty-One", "module": "main", "funcName": "rolling_rename_series", "line": 169}

Troubleshooting

"Folder not found" error

Verify the path is correct and accessible
If using a server path (e.g., /mnt/plex/tv), ensure path_mappings in config.xml is set up to convert it

"Series not found in Sonarr/Radarr"

Verify the series/movie exists in your Sonarr/Radarr library
Check that API keys and URLs in config.xml are correct
Ensure the folder path matches what Sonarr/Radarr has configured

API Key or Connection Issues

Verify Sonarr/Radarr is running and accessible at the configured URL
Check API key is correct (copy directly from settings, avoid typos)
Verify firewall/network allows connection to Sonarr/Radarr

Re-running doesn't rename remaining files

Check logs/rolling_rename_progress.json to see what's already completed
You can delete this file to reset progress and re-rename everything

Project Structure

renamarr/
├── main.py                 # Main entry point
├── config.xml              # Configuration (Sonarr/Radarr URLs, API keys, path mappings)
├── .gitignore              # Git ignore rules
├── README.md               # This file
├── core/
│   ├── config_helper.py    # Loads and parses config.xml
│   ├── sonarr_radarr_helper.py  # Sonarr/Radarr API communication
│   └── logger_helper.py    # Structured JSON logging setup
├── cache/
│   ├── sonarr_cache.json   # Cached Sonarr series data
│   ├── radarr_cache.json   # Cached Radarr movies data
│   └── temp_episodes.json  # Temporary episode cache for current operation
└── logs/
    ├── rolling_rename.log  # Main log file (JSON formatted)
    └── rolling_rename_progress.json  # Progress tracking across runs

Tips

First Run: The first run is slow because it fetches and caches all series/movies from Sonarr/Radarr. Subsequent runs are faster.
Large Libraries: For large libraries, caches can take 30+ seconds to load. This is normal.
Safe to Interrupt: If you interrupt the script (Ctrl+C), progress is saved. Just run again to resume.

Batch Operations: Use a loop or scheduler to rename multiple series:

python main.py "P:\tv\Show 1" -w 30
python main.py "P:\tv\Show 2" -w 30
python main.py "P:\tv\Show 3" -w 30

License

MIT License - See LICENSE file for details

Support

For issues or questions, check the logs in logs/rolling_rename.log for detailed error messages.

6.0 KiB Raw Blame History