moscardino.net 馃攳
2020-02-19

Renamer Core

A CLI tool for renaming files for Plex.

Plex is picky about naming things. Movies and TV shows must be named according to specific rules in order to be picked up and matched correctly. Sometimes though, renaming files for Plex is a chore. You get a movie and the name is a garbled mess. Or you have a folder of TV show episodes and you need them all cleaned up.

There are other tools that can help with this, but I didn鈥檛 like them so I wrote my own. And now I made it public, so you can try it, too.

Renamer Core

Renamer Core is my CLI tool for renaming movies and TV show episode files to match Plex鈥檚 naming conventions. It鈥檚 nice to use, works most of the time, and has made my life a bit easier. It was also fun to make. I鈥檝e been using it for probably a year or so now and have been tweaking it non-stop.

This is actually the second time I鈥檝e written this tool. The first was written in TypeScript and was a CLI using node. It was fine, but I wanted to try doing the same thing in .NET Core, hence Renamer Core.

The current version, 2.2.0, uses semantic versioning. Version 1.X didn鈥檛 use the CommandLineUtils library I like so much so the major version was bumped when I completely changed how the project was structured and how the renamers were called from the command line.

Renamer Core contains two tools which I call renamers: one for movie files and one for TV show episode files. Both renamers can be pointed at any directory and can output to any directory. And because it鈥檚 a .NET Global Tool, it can be run from any directory.

Making It Public

Recently, I made the repo public so anyone can clone and try it. Specifically, I deleted my old repo and created a new one with the current code. This was because I did a stupid thing a while back and had my API keys hard-coded in some of the source files. Changing those API keys is annoying and difficult, so I decided to just lose the history. There wasn鈥檛 a lot to see there any way.

Installing It

  1. You鈥檒l need the latest .NET Core SDK (3.1 at the time of writing). Get that first.
  2. Then you need to clone the repo to your computer.
  3. Run some commands:
    1. dotnet build to build the project.
    2. dotnet pack to package it up for installation
    3. dotnet tool install -g --add-source ./dist renamer-core to install the project as a global tool.

Once installed as a global tool, you can cd to any directory and invoke it with renamer.

To update it, pull the latest changes from the repo, run dotnet tool uninstall -g renamer-core to remove the old version, then use the commands above to re-install.

Configuring It

In order to use a renamer, you need an API key for the respective service. For the movie renamer, you need an API key for The Movie DB (v3 Auth Key). For the show renamer, you need an API key for The TV DB. Both services are free to use.

You can set your API keys using one of the following commands:

> renamer config -tmdb YourTheMovieDbApiKey
> renamer config -tvdb YourTVDBApiKey

You can also call renamer config to see your saved API keys.

Using the Movie Renamer

> renamer m
Found 1 files.

star.wars.1977.1080p.h264.foo.bar.baz.txt =>
        Star Wars (1977) - 1080p.txt

Look good? [Y/n] y
Renamed 1 files.

The movie renamer works by repeatedly searching The Movie DB for the movie by using the file name and dropping off bits until it either gets a match or runs out of name. You can see this process in action using the --verbose option:

> renamer m --verbose
* Using Input Path: C:\Projects\renamer-core\testfiles
* Using Output Path: C:\Projects\renamer-core\testfiles

Found 1 files.

star.wars.1977.1080p.h264.foo.bar.baz.txt =>
                * Searching for: "star wars 1977 1080p h264 foo bar baz"
                * Searching for: "star wars 1977 1080p h264 foo bar"
                * Searching for: "star wars 1977 1080p h264 foo"
                * Searching for: "star wars 1977 1080p h264"
                * Searching for: "star wars 1977 1080p"
                * Searching for: "star wars 1977"
                * Searching for: "star wars"
        Star Wars (1977) - 1080p.txt

Look good? [Y/n] y
Renamed 1 files.

The general idea is that by the time we get to the end, we should have gotten a result back and can rename the movie using the data from The Movie DB. In our example, we end up with a file using the pattern Movie Name (YEAR).ext. The movie renamer will also add in - 1080p and - 4k if it finds 1080, 2160, or 4k in the original name. It will also look at the extension and add .en before the extension if it thinks the file is a subtitles file.

This isn鈥檛 a perfect method, but it works most of the time and is pretty quick.

Use renamer m -? for an explanation of all the options.

Using the Show Renamer

> renamer s
Found 1 files.

doctor.who.2005.s01e01.rose.1080p.h264.foo.bar.baz.txt =>
        Doctor Who (2005)\Season 1\Doctor Who (2005) - s01e01 - Rose.txt

Look good? [Y/n] y
Renamed 1 files.

The show renamer works differently than the movie renamer. The show renamer looks for a part in the middle of the file specifying the season and episode numbers. Something like s01e01 or 02x23 or something similar. Using that, it extracts the season and episode number, then uses anything before that segment as the show name and discards anything after that segment. The show name is then searched against The TV DB using the similar method to the movies. Once a show is found, the episode is looked up using the season and episode number from the name. Once we have an episode match, the new filename is built using the pattern Show Name (YEAR) - sXXeYY - Episdode Name.ext.

There are options to treat the season and episode numbers from the input as DVD order and another option to use the DVD order numbers to create the resulting filename. Having those as separate options means you can (in theory) convert between aired and DVD ordering if you would like. There is also a recursive option to traverse the input directory for all files. Note that any file will be picked up, not just video files.

Like the movie renamer, the show renamer isn鈥檛 perfect. Sometimes it just doesn鈥檛 match, but the hit rate is really good and thanks to some caching it鈥檚 pretty quick when renaming lots of episodes of the same show.

Use the --verbose option to see the search as it happens! Also renamer s -? for an explanation of all the options.

Future Plans

Now that this is out there, I would like to get it packaged up and upload it to nuget.org so it can be installed without cloning the repo. I鈥檓 also open to suggestions on improvements and bug fixes.

Photo by Jon Tyson on Unsplash