aljohn92/plex-auto-collections repository overview

⁠Plex Auto Collections

⁠Version 2.8.0

Plex Auto Collections is a Python 3 script that works off a configuration file to create/update Plex collections. Collection management with this tool can be automated in a varying degree of customizability. Supports IMDB, TMDb, and Trakt lists as well as built in Plex Searches using actors, genres, year, studio and more.

⁠Table of Contents

1. Usage⁠
   • Local Installation⁠
   • Docker⁠
2. Configuration⁠
   • Collections⁠
     • List Type⁠
       • Plex Search (List Type)⁠
       • Plex Collection (List Type)⁠
       • TMDb Collection (List Type)⁠
       • TMDb People (List Type)⁠
       • TMDb Company (List Type)⁠
       • TMDb Network (List Type)⁠
       • TMDb Popular (List Type)⁠
       • TMDb Trending (List Type)⁠
       • TMDb Top Rated (List Type)⁠
       • TMDb Now Playing (List Type)⁠
       • TMDb Discover (List Type)⁠
       • TMDb List (List Type)⁠
       • TMDb Movie (List Type)⁠
       • TMDb Show (List Type)⁠
       • TVDb Show (List Type)⁠
       • IMDb List or Search (List Type)⁠
       • Trakt List (List Type)⁠
       • Trakt Trending List (List Type)⁠
       • Trakt Watchlist (List Type)⁠
       • Tautulli List (List Type)⁠
     • Collection Filters (Collection Attribute)⁠
     • Sync Mode (Collection Attribute)⁠
     • Sort Title (Collection Attribute)⁠
     • Content Rating (Collection Attribute)⁠
     • Summary (Collection Attribute)⁠
     • Collection Mode (Collection Attribute)⁠
     • Collection Order (Collection Attribute)⁠
     • Poster (Collection Attribute)⁠
     • Background (Collection Attribute)⁠
     • Name Mapping (Collection Attribute)⁠
   • Plex⁠
   • Image Server⁠
     • Poster and/or Background Directory⁠
     • Image Directory⁠
   • TMDb⁠
   • Tautulli⁠
   • Trakt⁠
   • Radarr⁠
3. Acknowledgements⁠

⁠Usage

This script can be used as an interactive Python shell script as well as a headless, configuration-driven script.

The interactive shell script has some limited abilities including the ability to add new collections based off searches, delete collections, search for collections and manage existing collections. The bulk of the feature-set is focused on configuration-driven updates.

⁠Local Installation

Some limited testing has been done only on Python 3.7 and 3.8 on Linux and Windows. Dependencies must be installed by running:

pip install -r requirements.txt

If there are issues installing dependencies try:

pip install -r requirements.txt --ignore-installed

To run the script in an interactive terminal run:

python plex_auto_collections.py

A config.yml file is required to run the script. The script checks for a config.yml file alongside plex_auto_collections.py as well as in config/config.yml. If desired, a different configuration file can be specified with -c <path_to_config> or --config-path <path_to_config>. This could be useful for creating collections against different libraries, such as a Movie and TV library (in this case, be sure to update the library_type in the configuration file).

python plex_auto_collections.py --config-path <path_to_config>

If you would like to run the script without any user interaction (e.g. to schedule the script to run on a schedule) the script can be launched with -u or --update:

python plex_auto_collections.py --update

If you would like the -u or --update option to update without updating metadata you can add -nm or --no_meta along with -u or --update:

python plex_auto_collections.py --update --no_meta

If you would like the -u or --update option to update without updating images you can add -ni or --no_images along with -u or --update:

python plex_auto_collections.py --update --no_images

Example command if you only want the collection to update without constantly updating metadata and images that don't change much

python plex_auto_collections.py --update --no_meta --no_images

⁠Docker

A simple Dockerfile is available in this repo if you'd like to build it yourself. The official build is also available from dockerhub here: https://hub.docker.com/r/mza921/plex-auto-collections⁠

The docker implementation today is limited but will improve over time. To use, try the following:

docker run --rm -v '/mnt/user/plex-auto-collections/':'/config':'rw' 'mza921/plex-auto-collections' -u

The -v '/mnt/user/plex-auto-collections/':'/config' mounts a persistent volume to store your config file. Today, the docker image defaults to running the config named config.yml in your persistent volume (eventually, the docker will support an environment variable to change the config path).

Lastly, you may need to run the docker with -it and without -u in order to interact with the script. For example, if you'd like to use Trakt lists, you need to go through the OAuth flow and interact with the script at first-run. After that, you should be able to run it without the -it flag.

⁠Configuration

The script allows utilizes a YAML config file to create collections in Plex. This is great for a few reasons:

• Setting metadata manually in Plex is cumbersome. Having a config file allows template to be reused, backed-up, transferred, etc.
• Plex often loses manually set metadata. Having a config file fixes metadata creep.
• Collections change often. Having a config file pointing to dynamic data keeps collections fresh.

There are currently six YAML mappings that can be set:

• collections (required)⁠
• plex (required)⁠
• image_server (optional)⁠
• tmdb (optional, but recommended)⁠
• tautulli (optional)⁠
• trakt (optional)⁠
• radarr (optional)⁠

You can find a template config file in config/config.yml.template⁠

⁠Collections

Each collection is defined by the mapping name which becomes the name of the Plex collection. Additionally, there are many different attributes you can set for each collection:

• List Type (required)⁠
• Collection Filters (optional)⁠
• Sync Mode (optional)⁠
• Sort Title (optional)⁠
• Content Rating (optional)⁠
• Summary (optional)⁠
• Collection Mode (optional)⁠
• Collection Order (optional)⁠
• Poster (optional)⁠
• Background (optional)⁠
• Name Mapping (optional)⁠

⁠List Type (Collection Attribute)

The only required attribute for each collection is the list type. There are many different list types to choose from:

• Plex Search⁠
• Plex Collection⁠
• TMDb Collection⁠
• TMDb People⁠
• TMDb Company⁠
• TMDb Network⁠
• TMDb Popular⁠
• TMDb Trending⁠
• TMDb Top Rated⁠
• TMDb Now Playing⁠
• TMDb Discover⁠
• TMDb List⁠
• TMDb Movie⁠
• TMDb Show⁠
• TVDb Show⁠
• IMDb List or Search⁠
• Trakt List⁠
• Trakt Trending List⁠
• Trakt Watchlist⁠
• Tautulli List⁠

Note that most list types supports multiple lists, with the following exceptions:

• TMDb Popular
• TMDb Trending
• TMDb Top Rated
• TMDb Now Playing
• TMDb Discover
• Trakt Trending Lists
• Trakt Watchlist
• Tautulli Lists

⁠Plex Search (List Type)

⁠Works with Movie and TV Show Libraries

You can create a collection based on the Plex search feature using the plex_search attribute. The search will return any movie/show that matches at least one term from each search option. You can run multiple searches. The search options are listed below.

Here's some high-level ideas:

collections:
  Documentaries:
    plex_search:
      genre: Documentary

collections:
  Dave Chappelle Comedy:
    plex_search:
      actor: Dave Chappelle
      genre: Comedy

collections:
  Pixar:
    plex_search:
      studio: Pixar

collections:
  90s Movies:
    plex_search:
      year:
        - 1990
        - 1991
        - 1992
        - 1993
        - 1994
        - 1995
        - 1996
        - 1997
        - 1998
        - 1999

collections:
  90s Movies:
    plex_search:
      year: 1990-1999

collections:
  2010+ Movies:
    plex_search:
      year: 2010-NOW

collections:
  90s Movies:
    plex_search:
      decade: 1990

Note if you only want to search using a single attribute you can do so without plex_search.

collections:
  90s Movies:
    year: 1990-1999

Notes:

• You can only use each search option once per plex_search but you can give the search multiple values.
• If you want to restrict the search by multiples of the same attribute (i.e. You want every movie that is a Romance and Comedy) try using filters⁠.

⁠Plex Collection (List Type)

⁠Works with Movie and TV Show Libraries

You can create Collections based on collections already in Plex

collections:
  Dinosaurs:
    plex_collection: Jurassic Park

Note if you want to add multiple collections you have to use a list. Comma separated values will not work.

collections:
  Dinosaurs:
    plex_collection:
      - Jurassic Park
      - The Land Before Time

⁠TMDb Collection (List Type)

⁠Works with Movie Libraries

The Movie Database (TMDb) strives to group movies into logical collections. This script can easily leverage that data. You can use the full url or just type in the TMDb ID for the collection:

collections:
  Jurassic Park:
    tmdb_collection: https://www.themoviedb.org/collection/328

collections:
  Jurassic Park:
    tmdb_collection: 328

collections:
  Alien (Past & Present):
    tmdb_collection:
      - https://www.themoviedb.org/collection/8091
      - 135416

Alternatively you can specify which tmdb_collection⁠, tmdb_summary⁠, tmdb_poster⁠, and tmdb_background⁠ all at once by using tmdb_id and setting it to the collections page ID or URL:

collections:
  Jurassic Park:
    tmdb_id: 328

collections:
  Alien (Past & Present):
    tmdb_id: 8091, 135416
  Anaconda:
    tmdb_id: 105995, 336560

Notes:

• The tmdb_id can be either from a collection or an individual movie
• You can specify more than one tmdb_id but it will pull the summary, poster, and background from only the first one.
• Local posters/backgrounds are loaded over tmdb_poster/tmdb_background if they exist unless tmdb_poster/tmdb_background is also specified
• tmdb_summary will load unless summary,tmdb_summary, or tmdb_biography is also specified

⁠TMDb People (List Type)

Similarly to tmdb_id, tmdb_actor, tmdb_director, tmdb_writer can specify tmdb_biography⁠ and tmdb_profile⁠ of the person's TMDb page ID or URL as well as search Plex using their respective Plex Search⁠ all with one attribute.

⁠TMDb Actor (List Type)

⁠Works with Movie and TV Show Libraries

collections:
  Robin Williams:
    tmdb_actor: 2157

collections:
  Robin Williams:
    tmdb_actor: https://www.themoviedb.org/person/2157-robin-williams

⁠TMDb Director (List Type)

⁠Works with Movie Libraries

collections:
  Steven Spielberg:
    tmdb_director: 488

collections:
  Steven Spielberg:
    tmdb_director: https://www.themoviedb.org/person/488-steven-spielberg

⁠TMDb Writer (List Type)

⁠Works with Movie Libraries

collections:
  Quentin Tarantino:
    tmdb_writer: 138

collections:
  Quentin Tarantino:
    tmdb_writer: https://www.themoviedb.org/person/138-quentin-tarantino

Notes:

• You can specify more than one tmdb_actor, tmdb_director, or tmdb_writer but it will pull the summary and poster from only the first one.
• Local posters are loaded over tmdb_profile if they exist unless tmdb_profile is also specified
• tmdb_biography will load unless summary,tmdb_summary, or tmdb_biography is also specified

⁠TMDb Company (List Type)

⁠Works with Movie and TV Show Libraries

You can use a TMDb Company to build a collection based on all it's movies/shows by using tmdb_company. You can use the full url or just type in the TMDb ID for the collection:

collections:
  Studio Ghibli:
    tmdb_company: 10342

collections:
  Studio Ghibli:
    tmdb_company: https://www.themoviedb.org/company/10342

⁠TMDb Network (List Type)

⁠Works with Show Libraries

Similarly to using a TMDb Company, you can also use a TMDb Network to build a collection based on all it's shows by using tmdb_network. You can use the full url or just type in the TMDb ID for the collection:

collections:
  CBS:
    tmdb_network: 16

collections:
  CBS:
    tmdb_network: https://www.themoviedb.org/network/16

⁠TMDb Popular (List Type)

⁠Works with Movie and TV Show Libraries

You can build a collection using TMDb's most popular movies/shows by using tmdb_popular. The tmdb_popular attribute only supports a single integer value. The sync_mode: sync option is recommended since the list is continuously updated.

collections:
  TMDb Popular:
    tmdb_popular: 30
    sync_mode: sync

⁠TMDb Trending (List Type)

⁠Works with Movie and TV Show Libraries

You can build a collection using TMDb's daily or weekly trending movies/shows by using tmdb_trending_daily or tmdb_trending_weekly. Both attributes only support a single integer value. The sync_mode: sync option is recommended since the lists are continuously updated.

collections:
  TMDb Daily Trending:
    tmdb_trending_daily: 30
    sync_mode: sync

collections:
  TMDb Weekly Trending:
    tmdb_trending_weekly: 30
    sync_mode: sync

⁠TMDb Top Rated (List Type)

⁠Works with Movie and TV Show Libraries

You can build a collection using TMDb's top rated movies/shows by using tmdb_top_rated. The tmdb_top_rated attribute only supports a single integer value. The sync_mode: sync option is recommended since the list is continuously updated.

collections:
  TMDb Top Rated:
    tmdb_top_rated: 30
    sync_mode: sync

⁠TMDb Now Playing (List Type)

⁠Works with Movie Libraries

You can build a collection using TMDb's release_type to get movies that are now in theaters by using tmdb_now_playing. The tmdb_now_playing attribute only supports a single integer value. The sync_mode: sync option is recommended since the list is continuously updated.

collections:
  TMDb Now Playing:
    tmdb_now_playing: 30
    sync_mode: sync

⁠TMDb Discover (List Type)

⁠Works with Movie and TV Show Libraries

You can use TMDb's discover engine⁠ to create a collection based on the search for movies/shows using all different sorts of parameters shown below. The parameters are directly from TMDb Movie Discover⁠ and TMDb TV Discover⁠

⁠Discover Movies

⁠Discover Shows