Skip to content

Sub‐Zero Configuration

pannal edited this page Mar 16, 2018 · 40 revisions

Accessing the configuration

To access the configuration of Sub-Zero, first select the Channels menu, and then press the little cogs icon. You can also access Sub-Zero's settings from the Agents menu in your PMS configuration.

Channels Select Gear Icon

The configuration page will now show. Let's go through that for a short couple of steps:

Language configuration


  1. Subtitle language (1)/(2)/(3): The languages to download subtitles for
  2. Additional Subtitle languages (Use ISO-639-1 or IETF language codes, on a comma separated list)
  3. Only download foreign/forced subtitles (whose language is different from the source audio)
  4. Display languages with country attribute as ISO 639-1; this means that a pt-BR subtitle will display as Portuguese in clients)
  5. Treat languages with country attribute as ISO 639-1; this means that if a pt subtitle exists, pt-BR will not be downloaded
  6. Restrict to one language (Only use if you only download for one language, and will avoid Subtitles will show up as the first language in Plex.
  7. When detecting embedded subtitles in a media, and it's without a language code (UND/Unknown), it will be treated as selected language number 1


Sub-Zero 2.5 can look for the original filenames of renamed files, if you use Sonarr, Radarr, Filebot, a symlinking system, or any combination of those. This dramatically increases accuracy of the scanners and will give you better results. To configure this section, look here.

Provider configuration

Sub-Zero allows you to select the best subtitle from multiple providers To configure those, look here.

Scanning configuration


  1. Searches providers simultaneously. This will be faster but use slightly more resources.
  2. Automatically extract and use embedded subtitles upon media addition
    • When enabled, this will extract embedded subtitles (if any) from your media and apply your default mods to them, right when media is added.
  3. Don't search for subtitles of a language if there are embedded subtitles inside the media file
    • When enabled, if Sub-Zero detects subtitles in your media, it will not search for more subtitles of that language.
  4. Don't search for subtitles of a language if they already exist on the filesystem
    • When enabled, will stop searching for better subtitles for a language once a satisfactory subtitle has been found.
  5. Scan: Which external subtitles should be picked up
    • Exact: Only if media file and subtitle files are named identically
    • Loose: Subtitle filename contains the media filename
    • Any: Pickup any subtitle file present
  6. Scan: include "exotic" embedded or external subtitle formats (anything else than .srt/.ssa/.ass)
    • Enable this if you have subtitles in other formats than above, but do note, that they most likely require transcoding

Scores configuration


  1. Minimum score for TV-Show subtitle download (keep the default value for best results)
    • When configured, what is the minimum score for subtitles to download them? Lower scored subtitles are not downloaded. See here for more info
  2. Minimum score for Movie download (keep the default value for best results)
    • When configured, what is the minimum score for subtitles to download them? Lower scored subtitles are not downloaded.See here for more info

Hearing Impaired configuration


  1. Download hearing impaired subtitles:
    • "prefer": score subtitles for hearing impaired higher
    • "don't prefer": score subtitles for hearing impaired lower
    • "force HI": skip subtitles if the hearing impaired flag isn't set
    • "force non-HI": skip subtitles if the hearing impaired flag is set
  2. Remove Hearing Impaired tags from downloaded subtitles


These are what's called the "default mods" throughout the channel and wiki. Mods

  1. Remove Hearing Impaired tags from downloaded subtitles
  2. Remove style tags from downloaded subtitles
    • This will remove any formatting on your subtitles and change them to plain.
  3. Fix common whitespace/punctuation issues in subtitles
  4. Fix common OCR errors in downloaded subtitles
  5. Change colors of subtitles

Subtitles storage configuration


  1. Store subtitles next to media files (instead of metadata)
  2. Subtitle format to convert and save as (SRT recommended)
  3. Subtitle folder:
  4. Custom Subtitle folder
  5. Fall back to metadata storage if filesystem storage failed
    • If PMS is running on Linux, or on Windows as a service, it has to have read/write rights to media storage, in order to be able to scan/save subtitle files next to the media. If that fails, we can instead store in the PMS Library
  6. When saving a subtitle file next to a media, set file permissions as configured
  7. When scanning a filestore, if we find subtitles for a media file that is non-existant, SZ will delete it

Scheduler configuration


  1. On media playback: search for missing subtitles: current item, next episode, both, or neither
  2. Scheduler: Periodically search for recent items with missing subtitles
    • Here you can specify a scheduled interval, where SZ can catch up on missing subs
  3. Scheduler: Item age to be considered recent
    • The "Search for missing subtitles"-task only considers those items in the recently-added list, that are at most this old
  4. Scheduler: Recent items to consider per library
    • Limit the above search to a max number of items to search for per library
  5. Scheduler: Periodically search for better subtitles
    • How often to look for better subtitles
  6. Scheduler: Days to search for better subtitles (max: 30 days)
  7. Scheduler: don't search for better subtitles if the items airdate is older than
    • This reduces traffic on providers if you download a show that aired a long time ago.
  8. Scheduler: Overwrite manually selected subtitles when better found
  9. Scheduler: Overwrite subtitles with non-default subtitle modifications when better found
    • If you made a special modification to a subtitle, then override regardless, if a better one is found

Advanced configuration


  1. Number of items to store for the history

  2. How many download tries per subtitle (on timeout or error): How often should we retry a failed subtitle download?

  3. Ignore folders (...)

    • If a folder contains one of the files named subzero.ignore, .subzero.ignore, .nosz, don't process them. This applies to sections/libraries, movies, series, seasons, episodes
  4. Ignore anything in the following paths (comma-separated)

  5. Subzero mode: agent, channel, agent+channel.

    • Channel mode allows you to use Sub-Zero manually.
    • Agent mode runs Sub-Zero automatically when media is added.
  6. Access PIN (any amount of numbers, 0-9)

    • Allows you to restrict access to SZ menu or configuration
    • SZ needs to be restarted for this to take affect. See Adv. Channel menu item 2
  7. Access PIN valid for minutes

    • How many minutes above PIN is valid in a session
  8. Use PIN to restrict access to:

    • Channel menu
    • Advanced functions menu


  1. Call this executable upon successful subtitle download
    • Here you can specify a file to be executed after SZ finish downloading a subtitle
    • An example script for pushover can be found here
    • Available parameters:
      • %(subtitle_language)s
      • %(subtitle_path)s
      • %(subtitle_filename)s
      • %(provider)s
      • %(score)s
      • %(storage)s
      • %(series_id)s
      • %(series)s
      • %(title)s
      • %(section)s
      • %(filename)s
      • %(path)s
      • %(folder)s
      • %(season_id)s
      • %(type)s
      • %(id)s
      • %(season)s
  2. Check for correct folder permissions of every library on plugin start
    • if enabled, SZ checks for write permissions of your library folders and warns about them in the plugin channel
  3. Use new style caching (for subliminal)
  4. Low impact mode (for remote filesystems)
    • Enable this if your media is stored on a remote filesystem; it interacts with the remote filesystem less often
  5. Timeout for API requests sent to the PMS
    • How long to wait before timing out when talking to PMS
  6. HTTP proxy to use for providers (supports credentials)


  1. How verbose should the logging be?:

    • Controls how much info SZ writes into the log files (default: only warnings) - this is decoupled from your PMS
  2. How many log backups to keep?

    • This effectively determines the length of your log history.
  3. Log subtitle modification (debug)

  4. Log to console (for development/debugging):

    • You know when you need it
  5. Help the developers collecting anonymous usage statistics

    • Helps in planning new features

Next page

Back to main page

Go to top

You can’t perform that action at this time.