📺 Bulk TV Show Renamer

Auto-Detect & Match to TVmaze • Jellyfin / Plex / Emby Compatible • Anime Support

A powerful, user-friendly Python application that automatically detects TV shows in your folders, matches them to TVmaze, and renames them to the perfect format for media servers.

---

✨ Features

🎯 Core Features

• Auto-Detection - Scans folders and intelligently extracts show names
• Auto-Matching - Automatically searches TVmaze for all detected shows
• Auto-Merging - Combines similar show names (e.g., "Attack On Titan" + "Attack On Titan S2")
• Anime Support - Handles absolute episode numbering (Naruto #150, etc.)
• Dry Run Mode - Preview changes before applying them
• Keyboard Shortcuts - Fast workflow with Ctrl+O, Ctrl+R, Ctrl+S, etc.

📝 Output Format

ShowName - S01E001 - [2008-01-20] - Episode Title.mkv

Perfect for:

• 🎬 Jellyfin
• 🎥 Plex
• 📺 Emby
• 🗂️ Kodi

---

🚀 Quick Start

Requirements

pip install customtkinter

Usage

1. Launch the application
2. Press Ctrl+O or click "Browse Folder"
3. Select your TV shows root folder
4. Press Ctrl+R - Auto-scans and searches TVmaze
5. Review the matches (change if needed)
6. Press Ctrl+S to START!

---

⌨️ Keyboard Shortcuts

Shortcut	Action
Ctrl+O	Open/Browse folder
Ctrl+R or F5	Scan folder
Ctrl+L	Load episodes
Ctrl+S	START RENAME
Ctrl+D	Toggle Dry Run / Live mode
Escape	Clear focus

---

📂 Supported File Formats

• .mkv - Matroska Video
• .mp4 - MPEG-4 Video
• .avi - Audio Video Interleave
• .m4v - iTunes Video
• .mov - QuickTime Movie
• .wmv - Windows Media Video
• .ts - Transport Stream
• .flv - Flash Video
• .webm - WebM Video

---

🎭 Detected Pattern Examples

Season + Episode Patterns

✅ Breaking Bad S01E01.mkv
✅ Breaking.Bad.1x01.mkv
✅ Breaking Bad - Season 1 Episode 1.mkv
✅ Breaking Bad - S01.E01.mkv
✅ Breaking Bad - 1x01.mkv

Absolute Episode (Anime)

✅ Naruto - 001.mkv
✅ Naruto - Ep001.mkv
✅ Naruto - Episode 001.mkv
✅ Naruto.001.mkv

Auto-Skipped Files

⏭️ S01OP01 - Opening Theme.mkv
⏭️ S01ED01 - Ending Theme.mkv
⏭️ NCOP01.mkv
⏭️ Special - Behind the Scenes.mkv

---

🛠️ Advanced Features

🔗 Manual Show Merging

Merge shows that were detected as separate:

"Jujutsu Kaisen" + "Jujutsu Kaisen S01 Dd2 0 [pahe Li]"
           ↓
    "Jujutsu Kaisen" (51 files)

🔍 Custom Search

If auto-match is wrong:

1. Type custom search term
2. Press Enter or click 🔍
3. Select correct show from dropdown

📥 Episode Data Options

• Include air-date - Adds [2008-01-20] to filename
• Try absolute episode # - For anime with absolute numbering
• Organize into folders - Creates ShowName/Season 01/ structure
• Auto-load episodes - Loads episodes automatically after matching

---

🎯 How It Works

1️⃣ Scanning Phase

📁 Root Folder
├── Attack on Titan S1/
│   ├── Attack.on.Titan.S01E01.mkv
│   └── Attack.on.Titan.S01E02.mkv
└── Attack on Titan S2/
    ├── Attack.on.Titan.S02E01.mkv
    └── Attack.on.Titan.S02E02.mkv

🔍 Detects: "Attack On Titan" (2 folders merged)

2️⃣ Matching Phase

🌐 Searches TVmaze: "Attack On Titan"
✅ Found: Attack on Titan (2013) [Adult Swim]
📥 Loads: 89 episodes across 4 seasons

3️⃣ Renaming Phase

DRY RUN:
  →  Attack on Titan - S01E001 - [2013-04-07] - To You, in 2000 Y…
  →  Attack on Titan - S01E002 - [2013-04-14] - That Day - The Fa…

LIVE MODE:
  ✅ Attack on Titan - S01E001 - [2013-04-07] - To You, in 2000 Y…
  ✅ Attack on Titan - S01E002 - [2013-04-14] - That Day - The Fa…

---

🧩 Filler Word Removal

Automatically removes these from show names:

• Quality: 1080p, 720p, 4K, BluRay, WEB-DL
• Codecs: x264, x265, HEVC, H.264
• Audio: AAC, DD5.1, DTS, ATMOS
• Streaming: AMZN, NF, DSNP, HMAX
• Release Groups: [YIFY], (PSA), pahe.in, SubsPlease
• Tags: REPACK, PROPER, INTERNAL

---

📊 Example Workflow

Before

D:/
├── attack.titan.s1.fhd.265-pahe.in/
│   ├── Attack.on.Titan.S01E01.To.You.1080p.BluRay.x265.DD+2.0-Pahe.in.mkv
│   ├── Attack.on.Titan.S01E02.That.Day.1080p.BluRay.x265.DD+2.0-Pahe.in.mkv
│   └── ...
└── attack.titan.s2/
    ├── Attack.on.Titan.S02E01.Beast.Titan.mkv
    └── ...

After (with "Organize into folders" enabled)

D:/
└── Attack on Titan/
    ├── Season 01/
    │   ├── Attack on Titan - S01E001 - [2013-04-07] - To You, in 2000 Years.mkv
    │   ├── Attack on Titan - S01E002 - [2013-04-14] - That Day.mkv
    │   └── ...
    └── Season 02/
        ├── Attack on Titan - S02E001 - [2017-04-01] - Beast Titan.mkv
        └── ...

---

🔧 Configuration Options

Sidebar Settings

Option	Description	Default
Dry Run	Preview without changes	✅ ON
Include air-date	Add [YYYY-MM-DD]	✅ ON
Try absolute episode #	For anime	✅ ON
Organize into folders	Create Show/Season structure	❌ OFF
Auto-load episodes	Load after search	✅ ON

---

🐛 Troubleshooting

Issue: Show detected incorrectly

Solution: Use manual search or merge shows

1. Type correct name in "Custom search"
2. Press Enter or click 🔍
3. Select from dropdown

Issue: Episodes not matching

Solutions:

• ✅ Enable "Try absolute episode #" for anime
• ✅ Check TVmaze has correct episode data
• ✅ Use custom search to find better match

Issue: File already exists error

Solution: The tool now auto-adds (1), (2), etc. to duplicates

Issue: Opening/Ending themes renamed

Solution: Now auto-skipped (OP01, ED01, NCOP, etc.)

---

📈 Statistics Display

After each run:

══════════════════════════════════════════════════════════════════
  COMPLETE!
    ✅ Renamed: 141
    ⏭  Skipped: 119
    ❌ Errors:  0
══════════════════════════════════════════════════════════════════

---

🎨 Color-Coded UI

Color	Meaning
🟢 Green (Mint)	Success, Ready
🔵 Blue (Sky)	Info, Actions
🟡 Yellow	Warning, Dry Run
🔴 Red	Error, Live Mode
⚪ Gray	Neutral, Skipped

---

🌟 Pro Tips

1. Always start with Dry Run to preview changes
2. Review auto-matches - they're usually 95%+ accurate
3. Use merge feature for shows split across folders
4. Enable auto-load for fastest workflow
5. Keyboard shortcuts are your friend: Ctrl+O → Ctrl+R → Ctrl+S

---

📝 File Naming Convention

Standard Format

{Show Name} - S{Season}E{Episode} - [{Air Date}] - {Title}.{ext}

Examples

✅ Breaking Bad - S01E001 - [2008-01-20] - Pilot.mkv
✅ Attack on Titan - S03E022 - [2019-06-30] - Beyond the Wall.mkv
✅ Jujutsu Kaisen - S02E023 - [2023-12-28] - The Shibuya Incident.mkv

Without Air Date

✅ Breaking Bad - S01E001 - Pilot.mkv

---

🔒 Safety Features

• ✅ Dry Run Default - Always previews first
• ✅ No File Deletion - Only renames
• ✅ Duplicate Protection - Won't process same file twice
• ✅ Backup Recommendation - Always backup before live mode
• ✅ Path Length Protection - Prevents Windows path-too-long errors
• ✅ Collision Handling - Adds (1), (2) if file exists

---

📚 API Credits

This application uses the TVmaze API for show and episode data.

• API: https://www.tvmaze.com/api
• Rate Limit: Respects TVmaze guidelines with built-in delays
• Attribution: TVmaze data is property of TVmaze

---

🆘 Support

Common Questions

Q: Does it work with movies? A: No, this is specifically for TV shows.

Q: Can I undo renames? A: No automatic undo. Always use Dry Run first!

Q: What about Naruto numbering? A: Enable "Try absolute episode #" for correct anime numbering.

Q: Why is Naruto showing S2002E001? A: TVmaze organizes Naruto by year. This is correct per their data.

Q: Can I change the output format? A: Not in the GUI, but you can modify the build_name function in the code.

---

📜 License

This is free software. Use at your own risk. Always backup your files before using live mode.

---

🎬 Version History

v2.0 - Current

• ✨ Auto-search on scan
• ✨ Keyboard shortcuts
• ✨ Auto-skip OP/ED/Specials
• ✨ Duplicate file protection
• ✨ File exists handling
• ✨ Ready status badge
• 🐛 Fixed: Multiple processing of same file
• 🐛 Fixed: File collision errors

v1.0 - Initial

• Basic TVmaze matching
• Manual search workflow
• Dry run mode
• Episode detection

---

🙏 Acknowledgments

• CustomTkinter - Modern UI framework
• TVmaze - Episode data API
• Community - Testing and feedback

---

📞 Contact

For bugs, suggestions, or questions, please open an issue on GitHub.

---

Made with ❤️ for the home media server community

Happy renaming! 🎉