TV File renaming script

Here you'll find a little program which can rename your video collection for you, it has the following nifty features:

• Automatically downloads episode titles from the web
• Can handle a massive variety of filenames
• Cleans up long filenames
• Very customisable
• Completely automatic!

Download	Version
Latest Perl script
Win32 bare executable	v2.57 (2020-04)

Found a bug? Please report it at https://github.com/meermanr/TVSeriesRenamer/issues

There are two flavours of the script, the normal Perl script which works on any computer which has the Perl scripting language installed on it, and a special Windows-only executable. If you don't know which one to download, try the Windows-only one, it won't bite.

Works on any platform which has the Perl scripting language installed. Perl comes pre-installed with most Linux distributions and Mac OS X, if you don't have it you can get it readily from perl.org

Download as Perl script

A special Windows-only version, which is created out of the Perl script proper above. It's a much bigger download, and is known to have some minor glitches, but it doesn't require you to have Perl installed.

• Download installer (~2.6MB)
• Download bare executable (~2.6MB)

==

Please skim over this page to get an idea of how to use the script effectively, and email me if you have any comments / suggestions and what-not!

This section is a “least you need to know” approach to documentation. Once you're familiar with the basics you may want to check the advanced section to see all that you can achieve with the script!

Group your videos into folders, one season per folder. Name the folder like this:

"<NAME-OF-SERIES> <SEASON#>x"

Examples:

• “Smallville 6x”
• “Rome 1x”
• “Southpark 10x”

Now to run the script. Move the script¹⁾ into the same folder as your videos and run it by double-clicking.

The script may take about 10-15 seconds to load, and then you should see it something like the following:

Detected series name 'Smallville' (Season 6)
Reading input in AutoFetch mode from EpGuides.com
Fetching document ... [Done]
Generating changes...

Proposed changes:
____________________________________

Smallville 6x01 - Zod.avi
Smallville 6x02 - Sneeze.avi
Smallville 6x03 - Wither.avi
Smallville 6x04 - Arrow.avi
Smallville 6x05 - Reunion.avi
Smallville 6x06 - Fallout.avi
Smallville 6x07 - Rage.avi
Smallville 6x08 - Static.avi
Smallville 6x09 - Subterranean.avi
Smallville 6x10 - Hydro.avi
Smallville 6x11 - Justice.avi
Smallville 6x12 - Labyrinth.avi
Smallville 6x13 - Crimson.avi
Smallville 6x14 - Trespass.avi
Smallville 6x15 - Freak.avi
Smallville 6x16 - Promise.avi
Smallville 6x17 - Combat.avi
Smallville 6x18 - Progeny.avi
Smallville 6x19 - Nemesis.avi
Smallville 6x20 - Noir.avi
Smallville 6x21 - Prototype.avi
Smallville 6x22 - Phantom.avi
____________________________________

Would you like to proceed with renaming? [y/N/?]:

Press “Y” and you're done!

It's always good to know how to approach a problem. When you find the script isn't doing exactly what you want, try the built-in help for a list of options:

tvrenamer.pl --help

Some series, notably Southpark, number their files without a gap between the season number and the episode number. For example, “1005.avi” is season 10, episode 5. The script will read this number as episode “1005” of whatever season it thinks the folder is²⁾. To correct this, use:

tvrenamer.pl --dubious

This will make the script use only the last 2 digits of a number in the file name as the episode number, using the rest as the season.

The script tries to make as few assumptions as possible, which means that if the data it found on the web for your series only lists, say, 6 episodes of a 22 episode series it cannot know that the series will eventually be 22 episodes. It works on what it knows to be true and in this case that means: “There are 6 episodes”. So it considers a single-digit number to be sufficient.

If the website was updated to list the first 10 episodes, then the script would think “Ah, I'm going to need more space for the numbers” and will pad the single-digit numbers with zeros. This scales well: When I rename my 260+ episode series, it pads the numbers so they are all 3-digits long.

However, you can override this if you like. Just tell the script how many digits you want your numbers to be:

tvrenamer.pl --pad=2

If you see a lot of nonsense, such as “←[31m”, try the --noANSI option when you run the script. This disables fancy text formatting, such as using colour etc.

“ANSI” is the colloquial term for ANSI Escape Codes, which is a way of displaying coloured text. If you have ever dabbled in HTML it's a bit like a <font> tag which is hidden from sight but magically changes the way text is displayed.

DOS doesn't natively support ANSI escape sequences, but if you install the Perl module Win32::Console::ANSI you need only comment-in a line near the top of the script to enjoy colour.

Remove the “#” infront of this line:

#use Win32::Console::ANSI;  # Hack to fix up Win32 console to support ANSI  (http://www.bribes.org/perl/wANSIConsole.html#dl)

Because I'm in a bit of a rush, here is the latest email I wrote answering this question (also, see below for an even better solution):

Of course the simplest answer is to make shortcuts instead of copying, but that doesn't really solve the problem - it's a manual step for each folder!

> Hello,
>
> Thank you for your script. It really helps me.
 
You're very welcome! :-)
 
> I have two questions:
>
> 1. Is it possible to specify another path than default one? At this moment I
> must copy the executable tvrenamer.exe to all my folders or change my PATH
> variable.
 
Not exactly. I plan to add that feature in v3 which I am working on at
the moment, but it's going to be a while before it is ready.
 
However, it sounds like you are using Windows and there is a special
feature for windows you may like! The script has the ability to
"install" itself on your PC such that when you right click on a folder
in explorer one of your choices is "Use TVrenamer script".
 
To install this feature, copy tvrenamer.exe to your desktop and then
open a command prompt like so:
 
  START > RUN > "cmd.exe" > OK
 
This should open a black window where you can type in commands. Change
to your desktop directory with
 
 "cd Desktop" <ENTER>
 
Now run the script like so:
 
 "tvrenamer.exe --associate-with-video-folders" <ENTER>
 
This should print some text telling you all went well. Try
right-clicking a folder in explorer, you should see a new option "Use
TVRenamer script". If it doesn't work please let me know, with as much
info as you can spare on what you did and what sort of system you are
using. Also a hint at how tech-savvy you are would be helpful when I
write my response.
 
You can uninstall this feature like so:
 
 "tvrenamer.exe --unassociate-with-video-folders"
 
Good luck!
 
- RobM

I got a better solution to this problem from Dave (thanks!):

>Hi Robert,
>
>Thanks for this great app, its been very handy for me.
>
>I noticed on your site there's a section with "Can I rename folders without having to copy tvrenamer.exe all the time?"
>Your answer, while it works, means you can't enter extensions to the exe.
>
>An easier way of solving this problem is for a user to place a copy of tvrenamer.exe in their windows/system32 folder.
>Then they can just type tvrenamer.exe in any folder and it will pick it up.
>This has been working for me, and is a simple way without having to copy it into each folder.
>
>Regards,
>Dave

..and then Adrian sent me a script he uses, which finds the directories for you! Thanks very much Adrian!

> I have a script that I run regularly to scan through the TV Shows
> directory on my NAS. The script runs tvrenamer.pl on any likely
> looking directory (assuming a directory structure such as
> "Programme/Series x" or "Programme/Season x" where x is a numeric
> value). The script is very rough and ready and looks like this:
>
> #!/bin/sh
> cd /Volumes/video/TV\ Series
> IFS=$'\n'
> for dir in `find -E . -type d -iregex "./[^/]*/S(eason|eries)[[:space:]]+[0-9]+"`; do
>       ( cd "$dir"; rm -f ._*; tvrenamer.pl --unattended; )
> done

You can create a preferences file, which tvrenamer.exe will read every time you run it. This file contains all the options you might want to include on a command line or in a shortcut, without the hassle of actually including them.

First you need to create an empty text file with a special name that Windows doesn't usually like (sorry, the script was originally written for Linux). Create the file like so:

 START > Run > "cmd.exe" > OK
 "echo. > .tvrenamerrc" <ENTER>
 "notepad .tvrenamerrc" <ENTER>

This should pop up notepad with an empty file. Enter text so that the file contains the commands you want to appear by default, one per line. For instance, if you didn't want it to ask you for confirmation, you could add:

--unattended

and then save it. Now when you run tvrenamer.exe it should not prompt you to answer any questions, and will assume “Yes” to renaming, and “No” to any other questions (to make sure it doesn't trash your files by doing something weird).

(In order of appearance)

Sar: Seriously, thanks for making your work available; I think this has to be the third most useful software tool I've used to further my anime-watching experience, the other two being the media player and the download tool. Messily-named files wind me up something rotten.

TonyW: Thanks for this superb little script (Tv episode file renamer)!

Rolf: I found your rename script today and tried it on a couple of episodes. Simply awesome!

TonyJ: This script is absolute gold! I thought about doing a similar thing in ruby, but this works a treat!

Zhen: Keep up the good work

JesusG: Very impressed with your script!!! It's become a essential in my software favourites. Thank you very much

BrockH: I like your renaming script… only downloaded it tonight, but it's worked fine on the couple of series I've run it on.

PhilS: First of all, great script! Love it. Took me a while to setup my .tvrenamerrc but it's all looking good now.

DavidA: First off, I'd like to thank you for a great script. I've been looking for something like this for a while now.

GeoffA: First just wanted to say thanks for the tv renamer script. It's something I've been wanting for a very long time but had never bothered looking for since I didn't really think anyone had written one. I actually stumbled on it completely by accident.

If you want to speak louder than words, I invite you to donate something - but please, don't feel you have to! I maintain this script because I enjoy it!

If you are having problems, and skimming the manual and trouble-shooting doesn't help, don't hesitate to find me online (but please mention the script or I might think you're spam!) or send me an email:

Email: robert.meerman@gmail.com
Skype: robertmeerman
MSN: rob_meerman@hotmail.com
IRC: RobM, in #CompSoc and #anime on irc.animesoc.co.uk
ICQ: 37099562 (Page me⁴⁾)

I want the manual to explain all aspects of the script in an accessible manner. In practice this means I intend to document the effects of all options available to the script, with lots of examples.

This script started back in late 2001 as a one-line Perl command that removed the word “Chapter” from every file in the current directory. Back then I didn't know any Shell-scripting or Perl, so that was my first Perl script ever!

Perl and it's regular expressions intrigued me, so I spent some time reading the Linux man pages and eventually set myself the challenge of making a script that could rename every file in a folder using a list of desired filenames.

It's been evolving ever since, and now sports some rather nifty features!

If you are using the Perl script proper (tvrenamer.pl) you need to have Perl installed, and have the following modules available (all available through CPAN):

• Switch
• Term::ReadKey
• Cwd
• LWP::Simple3
• URI::Escape
• Compress::Zlib
• File::Glob
• (Windows users only) Win32API::File
• (Windows users only) Encode

If you are using the Windows-only build, then you only need Windows.

This script takes episode title data as input and tries to match it to the files present in the current directory. For this to work properly both the episode data you feed it, and the filenames need to be in a format that the script can understand.

There are multiple ways of feeding the script episode titles you want applied to the file in the current folder:

1. Copy and Paste the data from a website to the script
2. Copy and paste the data from a website into a textfile for the script to use
3. Instruct the script which webpage to download and use
4. Let the script search the web automatically

Normally you will want to use the last method, as it is the most convenient and works in most cases. Below I will explain how to use the various methods with any tips that come to mind, as well as some examples.

This was the first mechanism the script had for getting data. It may still be useful in modern versions because it is less susceptible to cosmetic changes in a website than some of the modern parsers.

Invoke this mechanism by passing the “-” option to the script:

tvrenamer.pl -

You should see something like the below:

Detected series name 'Smallville' (Season 6)
Reading input in AutoDetect mode from STDIN (Press ^D to end):

Now you goto one of the supported websites (see tvrenamer.pl --help for a list) and copy the episode data to the clipboard, then paste it into the terminal you are running the script in. Press return a couple of times to make sure you're on a new blank line, and then press CTRL + D to signal you're done pasting text.

For example, I would paste the following data from http://epguides.com/Smallville:

111.   6- 1     2T7701     28 Sep 06   Zod
112.   6- 2     2T7702      5 Oct 06   Sneeze
113.   6- 3     2T7703     12 Oct 06   Wither
114.   6- 4     2T7704     19 Oct 06   Arrow
...

The script ought to then suggest the following:

Proposed changes:
____________________________________

Smallville 6x01 - Zod.avi
Smallville 6x02 - Sneeze.avi
Smallville 6x03 - Wither.avi
Smallville 6x04 - Arrow.avi
...

This mechanism is useful for off-line renaming because the script does not need to contact a website to obtain the episode titles.

Same as the previous section, except you save the episode title data into a text-file which you must place in the same directory as your videos, and name specially using the website lists in tvrenamer.pl --help. For instance, the built-in help contains the following line:

  --EpGuides         Assume input is in http://www.EpGuides.com format

So you would name the text-file EpGuides.txt, although the case is not important. To use this text file you would simply run the script in the current directory, and it will pick it up.

tvrenamer.pl

: It shouldn't be necessary to give the text-file a special name.

This is perhaps the second most useful mechanism, it's handy for when the script is having a retarded moment and cannot work out what your series is called.

Find the page on one of the supported websites (see the list in tvrenamer.pl --help) which lists all the episode titles, and provide this link to the script on the command line. Be sure to include the quote marks on Linux and Mac OS X! ⁵⁾

tvrenamer.pl "http://epguides.com/Smallville/"

By far the most convenient mechanism, when it works. I'm always looking to add support for more websites, so let me know if the script isn't compatible with your favourite site!

As this is the default behaviour, you do not need any arguments to the script:

tvrenamer.pl

For this mechanism to work you need to make sure the script has the “correct” name of the series in mind when searching. “Correct” here means that it matches what the website says. For example the recent Dr Who series is called “Doctor Who 2005”, even though I prefer to think of it as “Dr Who 27x”.

Either rename the folder to match the website, or amend the script's behaviour using some of the advanced options which are described later. For completeness here is how I tackled the above Dr Who problem: I kept my folder called “Dr Who 27x” and used the following command:

tvrenamer.pl --series=DoctorWho_2005 --season=1 --postproc='s/DoctorWho_2005/Dr Who/;s/ 1x/ 27x/'

How does this work?

• The --series= switch overrides the name which is normally taken from the folder's name.
• The --season= switch again overrides the season which is normally taken from the folder's name.
• The --postproc= switch is a highly advanced one which allows me to inject some Perl script for this run only. I've specified two substitutions:
  1. s/DoctorWho_2005/Dr Who/ which replaces the first occurrence of “DoctorWho_2005” in the new filename with “Dr Who”.
  2. The second substitution is s/ 1x/ 27x/ which replaces the first occurrence of “ 1x” in the new filename with “ 27x”.

Without the --postproc- the script would suggest new filenames like this:

DoctorWho_2005 1x01 - Rose.avi
DoctorWho_2005 1x02 - The End of the World.avi
...

With the --postproc= I get this:

Dr Who 27x01 - Rose.avi
Dr Who 27x02 - The End of the World.avi

As I wrote the script, it pretty much always works for me. So I need your help making this bit useful, if you have a problem getting to run please email me, even if you don't much care about making it work and will never return to my site! If you encountered a weird problem and managed to fix it yourself, please also let me know so others can benefit from your solution!

To report a problem, email robert.meerman@gmail.com, including a problem description and output log (or screenshot if you don't know how to log output).

In the meantime, here are somethings to check:

Do you have all of the following Perl modules installed?

• Switch
• Term::ReadKey
• Cwd
• LWP::Simple3
• URI::Escape
• Compress::Zlib
• File::Glob
• Text::Unaccent
• (Windows users only) Win32API::File
• (Windows users only) Encode

You can install these modules using the cpan command. You can think of it as a Perl package manager. Run the following command from a command-prompt:

All platforms:

cpan Switch Term::ReadKey Cwd LWP URI::Escape Compress::Zlib File::Glob Text::Unaccent

Additional command for Windows (these are needed to work around Unicode issues)⁶⁾:

cpan Win32API::File Encode

You may need to convert the file from DOS line-endings to Unix ones. Popular utilities for this are “fromdos” and “dos2unix”.

• AutoFetch mode that automatically searches AniDB.info, Epguides.com & TV.com for your series
  • Automatic detection of anime series, though can be manually specified with --series=anime or explicitly avoided with --series=tv.
• AutoDetect support for multiple copy'n'paste formats
  • AniDB.net (for anime)
  • TVtorrents.com
  • TVtome.com (no longer exists)
  • TV.com general episode list format
  • TV.com “All Seasons” episode list format (very useful)
• AutoDetect support for some fetched webpage formarts
  • AniDB.net (for anime)
  • TV.com “All Seasons” episode list format (very useful)
• Ability to read any of the above from appropriately named text files, such as “AniDB.txt” or “TV.txt”.⁷⁾
• Changes are reversible via ''–interactive'' switch which creates or updates a “unrename.pl” (or “unrename.bat” if you use the EXE version of the script)
• Option to select changes interactively (''--interactive'')
• Uses current directory name as series name, allowing you to conveniently change series names at any time. An example use might be to distinguish season 1 from a recently-started season 2.
  • Directory structures such as “House/Series 1/*” are interpreted as you would expect: SeriesName=“House”, Season=1
  • Recognises the following parts of the current directory's name.
    • “ (Complete)” at the end is ignored, as it is assumed to be a user note
    • “ (onDisc)” at the end is ignored, as it is assumed to be a user note
    • “Series Name 1x”, “Series Name 2x” is recognised as “Series Name” seasons 1 and 2 respectively, and file names will have “1x” and “2x” placed before their episode number appropriately — i.e. 1×01, 1×02, 1×03… and 2×01, 2×02, 2×03… (different numbering schemes can be chosed with the --scheme= option detailed below)
  • Series name can be manually specified with a command-line switch (--series=X)
  • Series name can be obtained from fetched webpages (--autoseries)
  • Season number can be manually specified with a command-line switch (--season=X)
• Group-tags can be stripped completely if not desired (--nogroup)
• Gap character can be specified (i.e. instead of “House 2×01 - Acceptance.mkv”, you get “House.2×01 - Acceptance.mkv” which is more script-friendly as the header no long contains spaces).
• Handles episodes “specials”
  • Anime: Does seperate renaming for 'S'-type specials on AniDB.info, naming them (S01, S02, S03..)
  • Auto-Ranges input, discarding everything after large gaps by default (can be overridden with --noautoranging) — this takes care of “specials” on TV.com
• Multiple season/episode number formats in file names are recognised (EG season 1, episode 8):
  • “Season 01 Episode 08”
  • “s01.e08”
  • “s01e08”
  • “1×08”
  • “S08”
  • “08”
  • “108” (you use the --dubious command-line argument to detect this as 1×08, instead of 1×108)
• Various numbering schemes for new file names (more can be very easily added):
  • “s01e08”
  • “1×08”
  • “08”
  • Default behaviour is “1×08” when the season number is explict, and “08” otherwise.
• Double-episodes of all variants above, such as “1×08-09”
• Dubious number extractor emmits warning when a file's episode number “108” is assumed to be season 1, episode 08, instead of episode 108 of whatever series the script thinks it's looking at (typically “1” unless told otherwise)
• Episode numbers are padded so they are all the same number of digits. For instance “1” → “01” if the input has 10 or more eps
• “Unixy” mode, for those that prefer underscores (“_”) to be used instead of spaces in file names (--unixy)
• “Clean up” mode, which does not require input and simply discards CRC32 checksums (such as “[037AF5A]”) from filenames, moves group tags to the end, and swaps underscores for spaces (or vice versa if “Unixy” mode is enabled) (--cleanup)
• Supports ANSI colour, allowing a prettier interface if your terminal supports it (--ANSI). If you see gibberish on your screen, disable this with --noANSI!
• Pre/Post Processor which evalutates PERL which has been given on the command line before/after internal filename processing. (For experts only, and silently ignored by the .EXE version)
• Ability to cache downloaded webpages (--cache), which creates a .cache file — this is useful if you want to experiment with different settings, or are debugging / altering the script.
• Unattended mode for batch processing and scripting
• Interactive mode to select changes on a file-by-file basis for those tricky situations

The script makes a few assumptions about your setup:

• All files to be renamed in the current directory are from the same series (there is limited support for files from different seasons of the same series being in the same directory, but only if the file names are distinctive enough to allow this)
• All filenames contain their episode number (in any notation supported, EG: 08, 1×08, s01e08…)

It also makes a few assumptions in an attempt to be helpful (these can be overridden):

• If a file called AniDB.txt is in the current directory, it uses it as input, reading it as AniDB data.
• If a file called TVtorrents.txt is in the current directory, it uses it as input, reading it as TVtorrents data.
• If a file called TVtome.txt is in the current directory, it uses it as input, reading it as TVtome data.
• If a file called TV.txt is in the current directory, it uses it as input, reading it as TV.com data.
• If a file called TV2.txt is in the current directory, it uses it as input, reading it as TV.com “All Seasons” data.
• If a file called EpGuides.txt is in the current directory, it uses it as input, reading it as EpGuides data.
• If a .URL or .desktop file exists, it is read and checked for an URL (http://...), if found this is fetched and used as input
• If you none of the above apply, and you didn't specifically tell it otherwise, you would like it to search EpGuides.com and then TV.com for you.
• The current directory's name is also the series' name.
• You only want to rename files which end in one of: avi|mkv|ogm|mpg|mpeg|rm|wmv|mp4