Nielsen helps rename and organize digital media collections.

Consider a filename such as The.Wheel.of.Time.S01E06.720p.WEB.x265-MiNX.mkv. If you'd prefer something more along the lines of The Wheel of Time -01.06- The Flame of Tar Valon.mkv, Nielsen can help.

Nielsen endeavors to automatically handle these types of renaming operations, as well as move the files into a more hierarchical folder structure that keeps your media directories tidy.

• Python 3.12 (or newer)
• Poetry (for source installations)

This package is published on PyPI and can be installed from there with the following command.

pip install nielsen

This package can also be installed from source by cloning this repository and using Poetry.

poetry install

• Media - Represents a file on disk and its metadata. The specific subclass determines how metadata is inferred and which Fetcher should be used.
• Fetcher - Queries external systems/services for metadata about a given Media instance.
• Processor - A grouping of a MediaType and Fetcher. Given a file, the Processor creates the appropriate Media (based on the MediaType) and Fetcher to query for metadata.

Under the hood, "processing" a file will create a Media object from the given path and MediaType, infer metadata based on the filename (e.g. TV series name, season number, episode number, and episode title).

If the fetch option is enabled, then a Fetcher will also be created to query more information (e.g. Ted.Lasso.S01.E01.mp4 doesn't give us an episode title, but the Fetcher can ask TVMaze for it).

nielsen can then rename the file (e.g. Ted Lasso -01.04- For the Children.mp4) and move it to your media library (e.g. ~/Videos/TV/Ted Lasso/Season 01/).

See the ARCHITECTURE file for more detailed information.

The primary use case nielsen is intended to handle is that of renaming a file and moving it into the correct location on disk. This is done with the process subcommand.

All commands (and subcommands) will accept a --help flag to provide more information about usage.

# Process a given file
nielsen process PATH_TO_FILE

# See a list of all subcommands
nielsen --help

nielsen uses an INI file for configuration. The module will look for files in the following locations, and load them in order (overwriting old values with newer values as they're loaded):

• /etc/nielsen/config.ini
• ~/.config/nielsen/config.ini

The CLI uses these configuration files to determine its default behavior, but also accepts a few command line flags (e.g. --[no-]organize) to modify its behavior at runtime. Command line arguments will take precedence over the configuration files.

Each section (denoted with square-brackets around the name) may contain multiple options.

Contains options about the behavior of the application itself.

Whether or not to create and use a Fetcher to obtain additional metadata about a file. If there is sufficient information in the filename or there is no network connection, the data fetching process can be skipped altogether.

Values: True or False

Default: True

Whether or not to prompt the user to select their desired result when a Fetcher yields multiple results (e.g. "The Office"). In non-interactive mode, the first result is used.

Values: True or False

Default: True

The location on disk to which nielsen log output should be written.

Value: A file the user can write to

Default: ~/.local/log/nielsen/nielsen.log

The Python logging level at which to filter log messages.

Values: NOTSET, DEBUG, INFO, WARNING, ERROR, CRITICAL

Default: WARNING

The numeric notation for the file mode (or permissions) a file should be given during processing.

Default: 644

Whether or not to move files to the media library during processing.

Values: True or False

Default: True

Whether or not to rename a file with its new metadata during processing.

Values: True or False

Default: True

Whether or not to actually modify files (e.g. rename and move them), or just print/log the actions which would otherwise be taken during processing.

Values: True or False

Default: False

Whether or not to transform (or modify) the inferred or fetched data during processing. The exact nature of these transformations are defined by the MediaType.

Values: True or False

Default: True

Contains options to apply to generic Media objects. Currently, there's no real use for this. However, options described here can be used in any other Media type section (e.g. tv).

The root directory into which a file should be moved as part of its processing. Each Media type may define its own library path.

Value: A directory the user can write to

Default: $HOME

The user name or system UID which should own the file after organizing. This value is optional, and if left undefined, the file ownership will not be changed when organizing.

Value: A system username (e.g. irish) or UID (e.g. 1000).

Default: None

The group name or system GID which should own the file after organizing. This value is optional, and if left undefined, the file ownership will not be changed when organizing.

Value: A system group name (e.g. user) or GID (e.g. 1001).

Default: None

Contains options to apply to TV objects. It is recommended that you set a library option to keep each media type separated. This value will overwrite the default [nielsen] or [media] section options for files processed as TV.

This section defines transformations for TV.series values. This can be used to normalize series names so that all files get organized into the same directory and are named consistently. Consider the series Marvel's Agents of S.H.I.E.L.D.. You may have files with various naming conventions:

1. Agents Of S.H.I.E.L.D.
2. Agents Of SHIELD
3. Agents Of Shield
4. Agents of S.H.I.E.L.D.
5. Agents of SHIELD
6. Agents of Shield
7. Marvel's Agents Of S.H.I.E.L.D.
8. Marvel's Agents Of SHIELD
9. Marvel's Agents Of Shield
10. Marvel's Agents of S.H.I.E.L.D.
11. Marvel's Agents of SHIELD
12. Marvel's Agents of Shield

By default, nielsen will see each of these as a different series. Defining a variant and a preferred name allows nielsen to treat them all as a single series. The variants used to choose a transformation are case insensitive, so you can fix capital letters/title casing with minimal repetition.

Values: Variant Series Name = Preferred Series Name

[tv/transform/series]
Agents of S.H.I.E.L.D. = Marvel's Agents of S.H.I.E.L.D.
Agents of SHIELD = Marvel's Agents of S.H.I.E.L.D.
Marvel's Agents of S.H.I.E.L.D. = Marvel's Agents of S.H.I.E.L.D.
Marvel's Agents of SHIELD = Marvel's Agents of S.H.I.E.L.D.

Its Always Sunny In Philadelphia = It's Always Sunny in Philadelphia
It's Always Sunny In Philadelphia = It's Always Sunny in Philadelphia

Fetching an episode title from TVMaze requires a series ID, season number, and episode number. Once a series name to series ID mapping has been determined, nielsen will attempt to save it in this section to avoid having to do the same lookup again in the future.

Values: Series Name = Series ID