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’t like them so I wrote my own. And now I made it public, so you can try it, too.
Renamer Core is my CLI tool for renaming movies and TV show episode files to match Plex’s naming conventions. It’s nice to use, works most of the time, and has made my life a bit easier. It was also fun to make. I’ve been using it for probably a year or so now and have been tweaking it non-stop.
This is actually the second time I’ve 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’t 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’s a .NET Global Tool, it can be run from any directory.
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’t a lot to see there any way.
- You’ll need the latest .NET Core SDK (3.1 at the time of writing). Get that first.
- Then you need to clone the repo to your computer.
- Run some commands:
dotnet buildto build the project.
dotnet packto package it up for installation
dotnet tool install -g --add-source ./dist renamer-coreto install the project as a global tool.
Once installed as a global tool, you can
cd to any directory and invoke it with
To update it, pull the latest changes from the repo, run
dotnet tool uninstall -g renamer-coreto remove the old version, then use the commands above to re-install.
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
You can also call
renamer config to see your saved API keys.
> renamer m
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
> renamer m --verbose
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
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’t a perfect method, but it works most of the time and is pretty quick.
renamer m -?for an explanation of all the options.
> renamer s
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
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’t perfect. Sometimes it just doesn’t match, but the hit rate is really good and thanks to some caching it’s pretty quick when renaming lots of episodes of the same show.
--verboseoption to see the search as it happens! Also
renamer s -?for an explanation of all the options.
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’m also open to suggestions on improvements and bug fixes.