Automatically rename TV show files with Hazel

Breaking Bad
Breaking Bad

I had a huge amount of TV show video files and I wanted them to easily be recognized by multimedia players such as ‘KODI‘ and ‘Plex‘. However, the existing file names as well as the folder structure were not optimized for such players.

My goal was to automatically rename and sort all files into a logical folder hierarchy such as:

  • TV show X
    • Season 1
      • TV show X S01E01.mp4
      • TV show X S01E02.mp4
    • Season 2
      • TV show X S02E01.mkv
  • TV show Y
    • Season 1
      • TV show Y S01E1.avi


The original file names had the following structure (examples):

  • (Season 1, Episode 1 of ‘The Crown’)
  • got.305.webrip.x264.480p.mp4 (Season 3, Episode 5 of ‘Game of Thrones’)
  • handmaid.webrip.S1E7.720p,x265.avi (Season 1, Episode 7 of ‘The Handmaid’s Tale’)
  • etc.


I was looking for an existing tool to handle the renaming and folder sorting tasks but didn’t find an appropriate solution. Therefore, I decided to us ‘Hazel‘ to perform the above mentioned tasks. However, the file renaming needed some custom programming. As ‘AppleScript’ is not really strong in string manipulation I gave ‘JavaScript’ in combination with ‘Hazel’ a try.

The whole ‘Hazel’ rule set works as following (also see image below):

  1. Hazel is monitoring a folder for new movie files, such as *.avi, *.mp4, *.mkv, etc.
  2. As soon as a new movie file is detected in the folder the ‘JavaScript’ is started. From the already existing file name the script tries to identify the correct TV show name, the season number as well as the episode number.
  3. If the script was succesful the movie file will be renamed according to the pattern <TV show name> S<season number>E<episode numbery>.<file ending>, e.g. ‘Game of Thrones S04E05’.
  4. Thereafter, the movie file is copied into the a sub-folder according to the pattern ‘/<TV show name>/<season number>/’.
  5. The folder structure as well as the movie file are then copied to my Synology NAS.
  6. Last but not least the movie file is then deleted from the hard drive.
  7. A second, separate ‘Hazel’ rule set (not visible in the image below) observes whether there are some unused sub-folders in my monitored folder after the movie files has been deleted from the hard drive.
Renaming TV show files - Hazel rule set
Renaming TV show files – Hazel rule set

If you want to use this solution as well just rebuild the above pictured ‘Hazel’ rule set on your Mac. The required ‘JavaScript’ code is listed below.

Some additional notes about the ‘Hazel’ rule set as well as the ‘JavaScript’

  1. After you have copied the ‘JavaScript’ code into your ‘Hazel JavaScript action’ (see step 2 above) you will need to customize  the array with your TV show names. Apply the following guidelines:
    • Each TV shows needs at least one entry in the array.
    • An entry is written in the form of [‘<search keyword>’,'<TV show name’,'<release year of first season (optional)>’],
    • Note that there is a comma (,) at the end of each line, except for the last line.
    • Adding the release year of the first season is optional. If you leave it out two single quotation marks have to be added nonetheless. Having the release year in the folder name of the TV show helps multimedia systems like ‘KODI’ or ‘Plex’ to better identify the TV show. E.g there are two TV shows with the name ‘The Defenders’, one from 2010 and one from 2017. If you add the release year to the folder name your multimedia system will be thankful for this additional information.
    • A TV show can have more than one entry in the array. This can be helpful if you have files of the same TV show but with different file name patterns, e.g. files with ‘-got-‘ and files with ‘game.of.thrones’ in the filename.
    • Special characters in the TV show name (e.g. apostrophe) need to be escaped. Write a backslash (\) in front of these character. Also see the ‘Handmaid’s Tale’ example in the code above.
    • The code will go through the array (from top to bottom) and try to find a match between the filename and one of the listed keywords. As soon as a match is found the code will abandon the array and continue with the code. Therefore you need to be thoughtful with the ordering of the keywords. Look at the example with the TV shows ‘The Blacklist – Redemption’ and ‘The Blacklist’. If the keyword ‘blacklist’ would be before the keyword ‘blacklistred’ the code would return a match for a file with the filename e.g. ‘blacklistredemption.s01e01.mp4’ for the TV show ‘The Blacklist’ because the keyword ‘blacklist’ can be found in this filename. In this case the keyword ‘blacklistred’ would never be evaluated against the filename.
  2. You will also have to define the variables that the script should return back to ‘Hazel’. This can be done in the very last line of code within the square brackets ([…]). You can add as many variables as you want or need. The available variables are documented directly in the code. Don’t forget to define the export variables in the user interface of ‘Hazel’ as well. Also see picture below for more details.
  3. In step 3) and 4) you will use the export variable from step 2) to define the new filename as well as the sub-folder structure for the video file.
  4. In step 5) I’m using the ‘Upload’ action to upload the renamed video file to my Synology NAS using the SFTP protocol. However, you can also use the ‘Copy’ or ‘Move’ action of ‘Hazel’ to perform the required file operation.
  5. After uploading the video file to my Synology NAS I no longer need the video file on my local hard drive. Therefore, the video file is moved to ‘Trash’.
Renaming TV show files – Definition of JavaScript export values
Renaming TV show files – Definition of JavaScript export values


Please enter your comment!
Please enter your name here