Episode Rename Script

A Bash utility for batch renaming TV show episode files from numeric format (e.g., 701.mkv, 1001.avi) to the standard season-episode format (e.g., S07E01.mkv, S10E01.avi).

Features

• Safe by Default: Runs in dry-run mode to preview changes before applying them
• Flexible Input: Accepts both 3-digit (e.g., 701) and 4-digit (e.g., 1001) episode numbering
• Preserves Extensions: Maintains original file extensions and any additional text in filenames
• Recursive Search: Finds and processes files in subdirectories
• Clear Feedback: Shows preview or confirmation of each rename operation

Requirements

• Bash shell (version 4.0 or higher recommended)
• Standard Unix utilities: find, mv

Installation

1. Clone or download this repository:

   git clone <repository-url>
   cd episode-rename-script
   

2. Make the script executable:

   chmod +x rename_episodes.sh
   

Usage

Basic Syntax

./rename_episodes.sh [path] [--run]

Parameters

Parameter	Required	Default	Description
path	No	. (current directory)	Target directory containing episode files
--run	No	(dry-run mode)	Execute actual renaming (without this flag, only previews changes)

Examples

Preview changes in current directory

./rename_episodes.sh

Preview changes in a specific directory

./rename_episodes.sh /path/to/tv/shows

Actually rename files (apply changes)

./rename_episodes.sh /path/to/tv/shows --run

Apply changes in current directory

./rename_episodes.sh . --run

How It Works

The script uses pattern matching to identify and parse episode files:

1. File Detection: Finds files starting with 3 or 4 consecutive digits
2. Pattern Parsing: Extracts season and episode numbers using regex
   • First 1-2 digits → Season number
   • Last 2 digits → Episode number
   • Remaining text → Preserved as-is
3. Formatting: Converts to S##E## format with zero-padded season numbers
4. Renaming: Moves files to new names (in --run mode only)

Naming Convention Examples

Original Filename	New Filename	Description
701.mkv	S07E01.mkv	Season 7, Episode 1
1225.mp4	S12E25.mp4	Season 12, Episode 25
305 - Episode Title.avi	S03E05 - Episode Title.avi	Preserves extra text
1001.720p.mkv	S10E01.720p.mkv	Preserves quality tags

Safety Features

• Dry-Run Default: The script will NOT modify files unless you explicitly add the --run flag
• Directory Validation: Exits with error if the specified directory doesn't exist
• Clear Mode Indicator: Displays whether running in preview or live mode
• Per-File Feedback: Shows each rename operation as it's processed

Error Handling

The script will exit with an error if:

• The specified directory does not exist
• The directory path is invalid

Sample Output

Dry-Run Mode (Preview)

--- Mode: DRY RUN (Preview Only) ---
Searching in: /home/user/MyShows
[PREVIEW] '701.mkv' -> 'S07E01.mkv'
[PREVIEW] '702.mkv' -> 'S07E02.mkv'
[PREVIEW] '1001.mp4' -> 'S10E01.mp4'
--- Finished Preview. To apply changes, add '--run' to your command. ---

Live Mode (Actual Renaming)

--- Mode: LIVE (Renaming Files) ---
Searching in: /home/user/MyShows
[RENAMED] '701.mkv' -> 'S07E01.mkv'
[RENAMED] '702.mkv' -> 'S07E02.mkv'
[RENAMED] '1001.mp4' -> 'S10E01.mp4'

Limitations

• Only processes files starting with 3 or 4 digits
• Assumes the first 1-2 digits represent season number, last 2 digits represent episode number
• Does not validate that season/episode numbers are logical or sequential
• Does not handle files that are already in S##E## format (will be skipped)

Troubleshooting

Files not being detected?

• Ensure filenames start with digits (e.g., 701.mkv, not Episode701.mkv)
• Check that files are in the directory you specified

Changes not being applied?

• Remember to add the --run flag to actually rename files
• Verify you have write permissions in the target directory

Script not executable?

• Run chmod +x rename_episodes.sh to make it executable

License

This script is provided as-is for personal or commercial use.