joshuaboniface / mediasorter

mediasorter: media file sorting tool

mediasorter

mediasorter is a tool to automatically "sort" media files from a source naming format into something nicer for humans to read/organize, and for tools like Jellyfin to parse and collect metadata for. It uses The Movie DB for movie metadata and TVMaze for TV metadata to obtain additional information, then performs the "sort" via a user-selectable mechanism. In this aspect it seeks to be a replacement for FileBot and other similar tools.

Most aspects of mediasorter can be configured, either inside the main configuration file, or via command-line arguments; it hopes to remain simple yet flexible, doing exactly what the administrator wants and nothing more.

mediasorter is free software, released under the GNU GPL version 3 (or later). It is written as a single Python 3 script and makes use of Click (python3-click) and YAML (python3-yaml).

Usage

1. Install the required Python 3 dependencies: click and yaml.

2. Create the directory /etc/mediasorter.

3. Copy the mediasorter.yml.sample file to /etc/mediasorter/mediasorter.yml and edit it to suit your needs.

4. Install mediasorter.py somewhere useful, for instance at /usr/local/bin/mediasorter.py.

5. Run mediasorter.py --help for detailed help.

6. Profit!

Note for Jellyfin

If you use mediasorter to sort files for Jellyfin, please consider using the "TVMaze" plugin for TV shows and "TheMovieDB" plugin for movies, as the primary metadata sources. These are the metadata providers that mediasorter uses to sort media, and other metadata providers may provide conflicting information about episode orders, etc.

Metainfo Tagging

With the -tm/--tag-metainfo option, additional info can be added to the destination filename to leverage Jellyfin's "multiple movie versions" feature. Currently, this only works with Movies (not TV episodes) in Jellyfin, and thus in mediasorter as well.

When this option is specified, the information found in the metainfo_map in the configuration file which is present in the source filename will be appended, using the square-brackets format, to the end of the destination filename.

When parsing, the list is iterated through in the order specified, and then for each item, the source filename is searched for the relevant regex match. If found, the value will be appended (once) to the metainfo string. The entries are grouped by type, for example cuts/editions first, then resolutions, then media types, etc. to produce a coherent and consistent string.

A large sample of possible match values is included in the mediasorter.yml.sample file, but more can be added or some removed as desired.

As an example, the following might be a destination filename with metainfo tagging using the default map:

Lord of the Rings: The Return of the King, The (2003) - [Extended Edition 2160p BD Remux 7.x Atmos TrueHD].mkv

Replacement

By default, mediasorter will replace an existing destination file, if one exists, with a new one during a run. This is useful if new media comes in which should replace the existing media (e.g. an upgraded quality version). To disable this behaviour, use --no-upgrade.

This behaviour is redundent when metainfo tagging is enabled for Movies, since the differenting quality profile would trigger a new file to be created anyways; it is thus mostly useful for TV which does not support this feature.

Search Overrides

Sometimes, the name of a piece of media, as extracted from the file, will not return proper results from the upstream metadata providers. If this happens, mediasorter includes an option in the configuration file to specify search overrides. For example, the TV show "S.W.A.T." does not return sensible results, so it can be overridden like so:

search_overrides:
  "s w a t": "swat"

This is currently the only provided example for demonstration purposes, but it can happen to many different titles. If you find a title that returns no results consider adding it to this list on your local system.

Name Overrides

Soemtimes, the name returned by the metadata providers might not match what you want to sort as. Thus mediasorter can override titles based on a list provided in the configuration file. For example, if you want the TV show "Star Trek" to be named "Star Trek: The Original Series" instead, it can be overridden like so:

name_overrides:
  tv:
    "Star Trek": "Star Trek: The Original Series"

These overrides are specific to media type (tv or movie) to avoid conflicts, e.g. in this example, with the 2009 film "Star Trek" which would also be changed (erroneously) if this were global.

Name overrides are handled before adjusting a suffixed "The", so entries containing "The" should be written normally, e.g. "The Series" instead of "Series, The" even if the latter is what is ultimately written.

fix-episodes.sh

mediasorter isn't that smart. For instance, if a show has inconsistent episode numbers between, say, airdate and a DVD, it can give episodes the wrong numbering.

Fixing this manually is quite cumbersome, and after having to deal with it more than once, I created this quick-and-dirty script that will quickly rename such files, especially for ranges of episodes that are incorrectly numbered.

Run it with no arguments for usage information.

mediasorter's Issues

Storage of the sample file

This tool looks as it was built with linux in mind, but as it is written in Python you can probably use it on windows as well. That said, where would I need to store the mediasorter.yml.sample file on windows? There is no such thing as an /etc folder to put it into.

Titles with illegal file characters create randomized folder and file names

Some shows such as "Penn & Teller: Fool Us" contain illegal characters that cannot be used in folders and files.

The logs indicate the file was moved correctly:

>>> Parsing (redacted)/Penn.and.Teller.Fool.Us.S10E04.1080p.WEB.h264-EDITH.mkv
Sorting action:   move
Raw file info:    series='penn and teller fool us' S=10 E=4
TVMaze API URL:   http://api.tvmaze.com/singlesearch/shows?q=penn%20and%20teller%20fool%20us&embed=episodes
Sorted filename:  (redacted)/Penn & Teller: Fool Us/Season 10/Penn & Teller: Fool Us - S10E04 - We Have a Raccoon Problem.mkv
Creating target directory '(redacted)/Penn & Teller: Fool Us/Season 10'
Running sort action... done.
Creating info file... done.

But given the name contains invalid characters (I assume the :), my SMB share shows it like so:

I suggest an option (CLI or YAML) to replace these reserved characters with something else.

--upgrade is misleading, replacing higher quality with lower quality media

I suggest either renaming it to --override, or introducing logic that would only replace files if the current file quality is lower than the one being sorted.

In this example, the 1080p version was sorted before the 720p version, which replaced it.

>>> Parsing (redacted).S05E08.1080p.WEB.H264-BUSSY.mkv
Sorting action:   move
Raw file info:    series='(redacted)' S=5 E=8
TVMaze API URL:   http://api.tvmaze.com/singlesearch/shows?q=(redacted)&embed=episodes
Sorted filename:  (redacted).mkv
Creating target directory '(redacted)'
Running sort action... done.
Creating info file... done.
>>> Parsing (redacted).S05E08.720p.WEB.H264-BUSSY.mkv
Sorting action:   move
Raw file info:    series='(redacted)' S=5 E=8
TVMaze API URL:   http://api.tvmaze.com/singlesearch/shows?q=(redacted)&embed=episodes
Sorted filename:  (redacted).mkv
Removing existing destination file for upgrade... done.
Running sort action... done.
Creating info file... done.

-u and -g are required even if --chown isn't set

The code is trying to get the uid and gid of the user and group, which if not set give an error.

  File ".../mediasorter.py", line 322, in sort_file
    gid = grp.getgrnam(group)[2]
          ^^^^^^^^^^^^^^^^^^^
KeyError: "getgrnam(): name not found: 'media'"

These lines should also be guarded by an if of the chown parameter:
https://github.com/joshuaboniface/mediasorter/blob/master/mediasorter.py#L321-L322