ep_rename.py
This tool can help organize episodic files into a standardized naming convention.
Usage
Consider a directory with the following files:
./fullmetal_alchemist_brotherhood_-_01_[1080p_bd-rip].mkv
./fullmetal_alchemist_brotherhood_-_02_[1080p_bd-rip].mkv
./fullmetal_alchemist_brotherhood_-_03_[1080p_bd-rip].mkv
...
Running ep_rename.py -t "Fullmetal Alchemist Brotherhood" will create the
following symbolic links in the same directory:
./Fullmetal Alchemist Brotherhood 01.mkv
./Fullmetal Alchemist Brotherhood 02.mkv
./Fullmetal Alchemist Brotherhood 03.mkv
...
You could add --strip-leading-zeros to do the obvious, or use --zero-pad 3
to add an extra zero. If you had 100 episodes, --zero-pad without an argument
will automatically deduce the width should be three.
Consider a directory with multiple seasons worth all numbered sequentially:
./Dragon Ball - 001 [x264].mkv
./Dragon Ball - 002 [x264].mkv
...
./Dragon Ball - 153 [x264].mkv
You can use the --season 1 --first 13 flags once followed by using the
--season 2 --first 13 --skip 13 flags and so forth until you end up with each
season split as follows:
./Dragon Ball s1e1.mkv
./Dragon Ball s1e2.mkv
...
./Dragon Ball s1e13.mkv
./Dragon Ball s2e1.mkv
./Dragon Ball s2e2.mkv
...
You will want to use --destination along with that so that the second
time you run ep_rename.py it doesn't try to use the files you just made.
By default, ep_rename.py will extract the first thing that looks like an
episode number. This doesn't work well if a show title includes a number.
Consider the following file name:
[a-s]_code_geass_r2_-_01_[1080p_bd-rip].mkv
[a-s]_code_geass_r2_-_02_[1080p_bd-rip].mkv
...
By default, ep_rename.py will infer that both of those are episode two.
However, the way it parses file names can be changed with the --input-fmt
flag. Using the flag --input-fmt "[a-s]_code_geass_r2_-_%n%a.%f" will
correctly parse the file name. Additionally, you can specify even less detail and
still parse the file name using more advanced patterns such as
"%b%a_r2_%n%a.%f". See the Input Format section below.
Flags
| Flag | Details |
|---|---|
-d DIR --destination DIR |
The destination directory where new files links will be created. Assumed to be the current directory. |
--output-type {symlink,hardlink,copy,move} |
Specifies the file type used for the output. Both symlink and
hardlink take negligibly additional disk space whereas copy
makes an extra copy of the file. Finally, move simply moves
the existing file from one location to another. |
--first N |
Only act on the first N files in sorted order. |
--skip N |
Skip the first N files in sorted order. Implies --renumber. |
-t TITLE --title TITLE |
The title to begin each file name with. |
-s SEASON--season SEASON |
If specified, episode numbers will follow the s1e1 s1e2 etc pattern.
The inverse can be done with --strip-season |
--renumber--no-renumber |
Number files beginning at 1 in order rather than using extracted
episode number. This is useful if you have multiple seasons and the
episode numbers do not reset to 1 at the beginning of each season.
Implies --renumber-start 1 |
--renumber-start N |
Start renumbering files beginning at N instead of 1. |
--strip-season |
If the input files follow the s1e1 s1e2 etc pattern, remove the
season prefix and renumber the files such that the first episode of
season two is numbered directly after last episode of season one.
Implies --renumber --renumer-start 1 |
--strip-leading-zeros |
Change the season or episode number from 01 to 1 etc. |
--zero-pad [WIDTH] |
Left pad episode numbers so they all are at least WIDTH length. If WIDTH is absent, it calculated based on the longest episode number. (Example: with WIDTH=3, then episode 1 becomes 001). |
--overwrite |
Overwrite the destination file if it exists. If this flag is not passed but any destination file already exists, an error will occur before creating any output files. |
--resolve-overlaps {error,newest,oldest,any} |
The method for resolving conflicts when multiple source files
generate the same output file. The newest and oldest choices
will use the source files' modified timestamp (resolving symbolic
links). Use the any choice if you don't care which file is chosen. |
--input-fmt FMT |
Specifies how the input file name should be parsed. See the INPUT
FORMAT section below for details. The default is %b%a%n%a.%f |
--dry |
Perform a dry run; don't modify the filesystem. |
-v--verbose |
Specify what files are created. Use -vv to see more details. |
Input Format
When traversing the current directory, file names are matched against the
format string specified by --input-fmt. If a name matches, the file is
kept and the desired fields are extracted. Files whose name do not match
are ignored.
A format string consists of sequence of literal characters and pattern
groups which begin with a %. Some pattern groups capture their matched
data which is used to determine metadata fields from the file name, such
as the season and episode number. The following pattern groups apply:
| Group Pattern | Details |
|---|---|
%a |
Matches any sequences of characters. |
%A |
Matches any positive-length sequence of characters. |
%b |
Optionally matches multiple pairs of square bracket and the content between them. Cannot handle nested brackets. |
%n |
Matches and captures a general episode number, which may or may not specify a season number. If it specifies a season number, it must follow the s1e1 pattern, case insensitive. In that case, both season and specific episode numbers are extracted. This pattern group may also match a single sequence of digits which will be interpreted as the specific episode number. |
%f |
Matches and captures the remaining non-dot characters of the file name and interprets it as the file name suffix to include on the output file. |
%% |
Matches the literal character %. |