prefetcharr

Have Sonarr automatically fetch the next episodes of the show you’re watching on Jellyfin/Emby/Plex.

Details

prefetcharr periodically polls your media server for active playback sessions of TV shows. It then checks whether a configured number of successive episodes is available. If there are episodes missing, it asks Sonarr to search for them. Depending on the configuration, it searches the missing episodes individually or tries to fetch all seasons that contain them. If there are no more seasons left, the series is monitored for new seasons instead.

Build and install

To install, first ensure Rust is installed on your system by following the instructions at Install Rust, then run:

cargo install --git https://github.com/p-hueber/prefetcharr

Or with docker compose:

services:
  prefetcharr:
    image: phueber/prefetcharr:latest
    container_name: prefetcharr
    environment:
      - |
        PREFETCHARR_CONFIG=
        # Start of the configuration in TOML format.
       
        interval = 900           # Polling interval in seconds
        log_dir = "/log"         # Logging directory
        log_level = "Debug"      # `Trace`, `Debug`, `Info`, `Warn` or `Error`
        prefetch_num = 2         # Number of episodes to make available in advance
        request_seasons = true   # Always request full seasons to prefer season packs
        append_to_queue = false  # Experimental: Append upcoming episodes to the player's active queue.
                                 # Not supported by all clients. Not compatible with Tautulli.
        connection_retries = 6   # Number of retries for the initial connection probing

        [media_server]
        type = "Jellyfin"                       # `Jellyfin`, `Emby`, `Plex` or `Tautulli`
        url = "http://example.com/jellyfin"     # Jellyfin/Emby/Plex/Tautulli baseurl
        api_key = "<YOUR KEY HERE>"             # Jellyfin/Emby/Tautulli API key or plex server token
        # users = [ "John", "12345", "Axel F" ] # Optional: Only monitor sessions for specific user IDs or names
        # libraries = [ "TV Shows", "Anime" ]   # Optional: Only monitor sessions for specific libraries

        [sonarr]
        url = "http://example.com/sonarr" # Sonarr baseurl
        api_key = "<YOUR KEY HERE>"       # Sonarr API key
        # exclude_tag = "no_prefetch"     # Optional: Exclude series by tag

    volumes:
      - /path/to/log/dir:/log
      # Keep the config in a file instead of PREFETCHARR_CONFIG
      # - /path/to/config.toml:/config

Configuration

The configuration is written in TOML format. When running prefetcharr directly, you can pass the path of the configuration file using the --config command-line flag. For the Docker container, provide the entire configuration via the PREFETCHARR_CONFIG environment variable. A complete example can be found in the installation instructions for docker-compose above.

API keys

prefetcharr needs two different API keys to do its job.

sonarr.api_key

Go to Settings -> General -> Security and copy the API key.

media_server.api_key

The key to use and how to obtain it differs on the type of media server you use:

Jellyfin

Log in as an administrator and go to Administration -> Dashboard -> Advanced -> Api Keys. Add a new key or use an existing one.

Emby

Log in as an administrator, click on the gear on the top right and go to Advanced -> Api Keys. Add a new key or use an existing one.

Plex

You need to extract the server token from a configuration file and use it as the API key.

Plex via Tautulli

Log in and go to Settings -> Web Interface -> API. Copy the key and make sure Enable API is ticked.

Upgrading pilots

If you want to store pilot episodes only, prefetcharr can fetch the first season for you on demand.
This method works well for individual episodes but may encounter issues with season packs.
For this to function in Sonarr, grabbing the season pack must be considered an upgrade of the pilot episode. This can be achieved through a custom format. Import the custom format and configure a quality profile to prefer it.

How to use

Host installation

If you installed prefetcharr through cargo, you can get a description of the command-line interface by running prefetcharr --help.

Docker installation

Users utilizing Docker only need to start the container, e.g. using docker compose up -d prefetcharr. Once the container is running, you may want to check the logs for errors. You can do so by either calling docker logs prefetcharr or by checking the logging directory you configured.