Configuration and Presets

Parsec uses a TOML-based configuration system. By default, it looks for a configuration file in the following locations:

1. $HOME/.config/parsec/config.toml (Linux/macOS) or %AppData%\parsec\config.toml (Windows)
2. parsec.toml in the current working directory or the config directory
3. .parsec.toml in the current working directory

Managing Configuration

You can use the config command to manage your configuration.

Initialize Configuration

To create a default configuration file in the default location ($HOME/.config/parsec/config.toml), run:

parsec config init

View complete default config.toml

# ╔═════════════════════════════════════════╗
# ║      ____                               ║
# ║     / __ \____ __________ ___  _____    ║
# ║    / /_/ / __ `/ ___/ ___/ _ \/ ___/    ║
# ║   / ____/ /_/ / /  (__  )  __/ /__      ║
# ║  /_/    \__,_|_|  |___/\___|\___/       ║
# ║       .: SYSTEM ADMINISTRATION :.       ║
# ╚═════════════════════════════════════════╝

# Configuration documentation is available at
# https://codeberg.org/upPollo/parsec/src/branch/main/docs/config.md

# Your release group Name (should only contain alphanumeric characters and be unique)
group = "NoRealGrpPlsChange"

# Default source for releases (Value in Filename or from flag is prioritized over this setting)
source = "WEB-DL"

# Preferred language for identification, tagging, and track ordering
preferred_language = "de"

# Place original language audio tracks before preferred language tracks in track ordering
original_audio_first = false

# If true, sets {language} to preferred_language and {language_ext} to "SUBBED"
# if no audio is present but subs are available in the preferred language
subbed_tagging = true

# Naming template for releases
# for what is available see https://codeberg.org/upPollo/parsec/src/branch/main/docs/templates.md
template = '{{join "." .Title .YearTag .SeasonEpisode .Edition .EpisodeTitle .VersionTag .RepackTag .LanguageName .LanguageExtra .Accessibility .Resolution .Service .Source (when .IsRemux "REMUX") .AudioSpec .HDR .VideoCodec}}-{{.Group}}'

# Default template to use for NFO generation
nfogen_template = "default"

# Character used to replace spaces in titles, episode titles, and codecs.
word_separator = "."

# Replace diacritics and special characters with their ASCII equivalents (e.g., ä -> ae, ß -> ss)
normalize_diacritics = true

# Path where to move files after renaming (absolute or relative to cwd)
# output_path = ""

# Video codec styling matrix
# Automatically maps video codecs based on release type (web_dl, remux, encode)
# To set a default profile fallback, define a [codec_matrix.default] table or alias (e.g. default = "web_dl")
[codec_matrix]
default = "web_dl"

[codec_matrix.web_dl]
AVC = "H.264"
HEVC = "H.265"

[codec_matrix.remux]
AVC = "AVC"
HEVC = "HEVC"

[codec_matrix.encode]
AVC = "x264"
HEVC = "x265"

# Custom regex replacements applied to the Title and Episode Title before normalization.
# Replaces `title_cleaning_regex`.
[[replacements.title]]
pattern = '(?i)(\s*\|.*|\s*\((Teil|Part)\s*\d+\))'
replacement = ''

[[replacements.title]]
pattern = '&'
replacement = 'und'

[[replacements.input]]
pattern = '(?i)(Fernseh|Dokumentar|Spiel|Kurz|Animations|Maerchen|Märchen)film.*(Deutschland|Oesterreich|Österreich|Schweiz|DDR)'
replacement = ''

# Regex replacements applied to the raw filename before parsing.
# They are processed in the order they appear.
[[replacements.input]]
pattern = '(?i)(Fernseh|Dokumentar|Spiel|Kurz|Animations|Maerchen|Märchen)film.*(Deutschland|Oesterreich|Österreich|Schweiz|DDR)'
replacement = ''


# Regex replacements applied to the final generated filename string.
# [[replacements.output]]
# pattern = 'BluRay'
# replacement = 'Blu-Ray'

# Episode ordering to use when fetching episodes from TVDB for identification.
# Options: default/aired, official, dvd, absolute, alternate, regional
tvdb_order = "default"

# Remap episode numbers to a different ordering in the output filename.
# Leave unset (or same as tvdb_order) to skip remapping.
# tvdb_remap_order = "absolute"

# Api keys for Media Databases (required for most features)
[api_keys]
tmdb = "your_tmdb_api_key" # https://developer.themoviedb.org/docs/getting-started
tvdb = "your_tvdb_api_key" # https://thetvdb.com/api-information
# Optional. Used only by `correct` if a missing subtitle font is not available from
# local system fonts or the keyless Google Fonts GitHub repository.
google_fonts = "" # https://developers.google.com/fonts/docs/developer_api

# Prowlarr configuration for release searching
[prowlarr]
url = "http://localhost:9696" # e.g. http://localhost:9696
api_key = "your_prowlarr_api_key"
indexers = [] # Array of indexer IDs to limit the search (empty for all)

[update]
# Automatically check for updates in the background
check = true

# Automatically download and install updates in the background
auto = false

# Check for prerelease/nightly updates
prerelease = false


# ---------------------------------- #
#        SOME EXAMPLE PRESETS        #
# ---------------------------------- #

# ------------------------------------------------------------------------------
# PRESET: mandalorian
# Use case: Automatically identify a specific show without needing to parse it.
# Useful for automation or when the file name is ambiguous.
# ------------------------------------------------------------------------------
[preset.mandalorian]
description = "Mandalorian on DSNP"
title = "The Mandalorian"
tmdb_id = 82856
is_tv = true
service = "DSNP"
# source = "WEB-DL" # Doesn't need to be set since it's already set in default preset

# ------------------------------------------------------------------------------
# PRESET: remux
# Use case: High-quality BluRay Remuxes.
# ------------------------------------------------------------------------------
[preset.movie-remux]
description = "HEVC/AVC codec labels"
source = "BluRay"
codec_profile = "remux"
template = '{{join "." .Title .YearTag .Resolution .Source "REMUX" .AudioSpec .HDR .VideoCodec}}-{{.Group}}'

# ------------------------------------------------------------------------------
# PRESET: encode
# Use case: Name of the encoding library is used as the video codec.
# ------------------------------------------------------------------------------
[preset.encode]
description = "x264/x265 codec labels"
source = "BluRay"
codec_profile = "encode"

# ------------------------------------------------------------------------------
# PRESET: quick-check
# Use case: Fast validation during ingest.
# Disables some verbose and opinionated checks.
# ------------------------------------------------------------------------------
[preset.quick-check]
description = "disables verbose/opinionated checks"
disabled_checks = [
    "filename_sequences",
    "mediainfo_bitrate",
    "matroska_track_order",
    "matroska_name_quality"
]

# ------------------------------------------------------------------------------
# PRESET: tvnation
# Use case: disable all checks except for disallowed filename characters
# ------------------------------------------------------------------------------
[preset.tvnation]
description = "disable almost all checks"
enabled_checks = ["filename_characters"]

# ------------------------------------------------------------------------------
# PRESET: special
# Use case: For handling TV specials and extras.
# Enables matching title/Aired date against Season 0 for TVDB
# ------------------------------------------------------------------------------
[preset.special]
description = "TV specials and extras"
allow_special_matches = true
season = 0
is_tv = true
template = '{{join "." .Title .YearTag .SeasonEpisode .Date .EpisodeTitle .Resolution .Service .Source .VideoCodec}}-{{.Group}}'

# ------------------------------------------------------------------------------
# PRESET: anime
# Use case: Naming scheme following the parsec naming guide for anime.
# ------------------------------------------------------------------------------
[preset.anime]
description = "CRC32 brackets and spaces"
is_tv = true
word_separator = " "
template = '[{{.Group}}] {{.Title}} - {{.SeasonEpisode}} - ({{join " " .Source .Resolution .VideoCodec .AudioCodec}}){{when .IsDualAudio " Dual-Audio"}} [{{.CRC32}}]'

Validate Configuration

To verify your current configuration and check if API keys are set, run:

parsec config validate

Presets

Presets allow you to define groups of settings that can be activated via the --preset flag. This is useful for recurring release types or specific shows.

Defining Presets

Presets are defined under the [preset.NAME] section. Almost all configuration options (except API keys) can be used within a preset to override global settings.

An optional description field can be added to any preset. It is displayed as a hint in shells that support completion descriptions (zsh, fish, PowerShell) when tab-completing the --preset flag.

# Global defaults
source = "WEB-DL"
group = "YourGroup"

[codec_matrix.web_dl]
AVC = "H.264"
HEVC = "H.265"

[api_keys]
tmdb = "your_tmdb_api_key"
tvdb = "your_tvdb_api_key"
google_fonts = "" # optional; only needed for missing subtitle font downloads

[preset.marvel]
description = "Pin metadata to Loki (2021)"
title = "Loki"
is_tv = true
tmdb_id = 84958

[preset.remux]
description = "AVC/HEVC codec names"
source = "BluRay"
codec_profile = "remux"
template = '{{join "." .Title .YearTag .Resolution .Source "REMUX" .VideoCodec .AudioSpec}}-{{.Group}}'

Using Presets

Activate a preset using the --preset flag with any command:

parsec rename --preset marvel Episode01.mkv

When a preset is active, Parsec will first look for a value in the preset's configuration. If not found, it falls back to the global configuration, and finally to the project's internal defaults.

Note: Flags provided on the command line always take precedence over configuration and presets.

Configuration Options

Global-only Options

These options can only be set at the top level of the configuration file and are not affected by presets.

Key	Type	Description
api_keys.tmdb	string	API key for TMDB.
api_keys.tvdb	string	API key for TVDB.
api_keys.google_fonts	string	Optional Google Fonts Developer API key. Used by autocorrect only when a missing subtitle font is not found locally or in the keyless Google Fonts GitHub repository.

Video Codec Matrix

codec_matrix defines named codec profiles — mappings from internal codec identifiers to their display strings in the generated filename. The three built-in profiles are:

Profile	AVC	HEVC
web_dl	H.264	H.265
remux	AVC	HEVC
encode	x264	x265

The active profile is selected by setting codec_profile to a profile name — either globally or within a preset. If codec_profile is not set, the default alias is used, which points to web_dl out of the box.

You can define your own named profiles alongside the built-ins:

[codec_matrix]
default = "web_dl"   # built-in profiles are still available

[codec_matrix.custom]
AVC  = "AVC"
HEVC = "H.265"

To use a custom profile in a preset:

[preset.my-preset]
codec_profile = "custom"

Key	Type	Description
codec_matrix	table	Named codec profiles. Each profile maps codec identifiers (AVC, HEVC) to display strings.
codec_matrix.default	string	Name of the profile to use when codec_profile is not set (default: web_dl).

Prowlarr Settings

These settings are used for release searching via Prowlarr.

Key	Type	Description
prowlarr.url	string	URL of your Prowlarr instance (e.g., http://localhost:9696).
prowlarr.api_key	string	API key for Prowlarr.
prowlarr.indexers	array of integers	Array of indexer IDs to limit the search (empty for all).
prowlarr.movie_categories	array of integers	Prowlarr categories to search for movies (default: [2000]).
prowlarr.tv_categories	array of integers	Prowlarr categories to search for TV shows (default: [5000]).

Update Settings

These settings control the automatic update behavior of Parsec.

Key	Type	Description
update.check	boolean	Automatically check for updates in the background (default: true).
update.auto	boolean	Automatically download and install updates silently in the background (default: false).
update.prerelease	boolean	Check for prerelease/nightly updates instead of just stable releases (default: false).

Preset-aware Options

These options can be set globally OR within a [preset.NAME] block.

General Settings

Key	Type	Description
template	string	The naming template used for renaming and checking. See Naming Templates for available fields, helper functions, and formatting rules.
nfogen_template	string	The default template used when generating NFO files with the nfogen command (default: default).
preferred_language	string	Preferred language code (default: de).
original_language	string	Override original language of the media file used in integrity checks (default: "").
original_audio_first	boolean	Order original language audio tracks before preferred language tracks (default: false).
subbed_tagging	boolean	If there are subtitles but no audio for the preferred language (e.g. de) set language Info to GERMAN.SUBBED (default: true).
tag_preview	boolean	Display a simplified preview of the Matroska tags before applying them (default: true).
codec_profile	string	Selects the active video codec profile by name (e.g. web_dl, remux, encode). See Video Codec Matrix for details.
word_separator	string	The character used to replace spaces in the generated filename, such as in the Title, Episode Title, and Audio Codec names. Use " " to preserve spaces (default: . ).
allow_special_matches	boolean	Allow fallback matching of episodes by Air Date or Episode Title against Specials (Season 0). Prevents incorrectly matching a regular episode without season/episode numbers to a TV special (default: false).
normalize_diacritics	boolean	Replace diacritics and special characters with their ASCII equivalents (e.g., ä -> ae, ß -> ss) (default: true).
output_path	string	Output path where files should be moved after renaming. Can be absolute or relative to the current working directory.

Regex Replacements

Parsec supports powerful regex replacements for input filenames, title cleaning, and output filenames. See the Regex Replacements Documentation for detailed configuration instructions and examples.

Metadata Overrides

These are especially useful within presets to provide missing information or override parsed data.

Key	Type	Description
title	string	Title of the movie or TV show.
original_title	string	Original foreign or alternative title.
year	integer	Release year.
season	integer	Season number.
episode	integer	Episode number.
date	string	Episode air date (YYYY-MM-DD).
episode_title	string	Title of the episode.
cut_edition	string	Override for the release edition (e.g., Director's Cut).
hdr	string	Override for HDR information (e.g., HDR10, DV).
service	string	Streaming service (e.g., DSNP, NF).
source	string	Default source (e.g., WEB-DL, BluRay).
group	string	Default release group name.
repack	boolean / integer	Mark as repack (boolean or numeric level, e.g. 2 for REPACK2).
remux	boolean	Force identification as a REMUX.
version_tag	integer	Quality upgrade version iteration (e.g. 2 for v2).
is_tv	boolean	Force identification as a TV show.
is_movie	boolean	Force identification as a movie.

Database IDs

Provide specific IDs to ensure the correct metadata is fetched from databases.

Key	Type	Description
imdb_id	string	IMDb ID (e.g., tt1234567).
tmdb_id	integer	TMDB ID.
tvdb_id	integer	TVDB ID.
tvdb_order	string	Episode ordering to use when querying TVDB for identification (default/aired, official, dvd, absolute, alternate, regional; default: default).
tvdb_remap_order	string	Remap matched episodes to a different ordering in the generated output filename (e.g., identify using dvd order, but rename to absolute order). Leave unset or empty to disable remapping (default: "").

Check Control

You can enable or disable specific quality checks on a per-preset basis. See Validation Checks for more details about what checks are availible

This setting is also respected by the autocorrect command: a disabled check is neither reported nor auto-fixed.

Key	Type	Description
enabled_checks	array of strings	If set, only the listed checks will be performed. Use ["all"] to enable all possible checks.
disabled_checks	array of strings	Listed checks will be skipped. (Ignored if enabled_checks is set)

The checks disabled by default are:
matroska_subtitle_inline_fonts, matroska_srt_validation, matroska_ass_events, matroska_ass_unused_styles, matroska_creation_time_privacy and matroska_chapters_existence

Available Checks

• filename_characters: Check for disallowed characters in filename.
• filename_sequences: Check for disallowed character sequences (e.g., ..).
• filename_generation_mismatch: Warn if the current filename does not match the generated name from template.
• mediainfo_interlaced_web: Warn if WEB source is interlaced.
• mediainfo_framerate: Check for non-standard framerates.
• mediainfo_bitrate: Check for low bitrates.
• mediainfo_durations: Check for inconsistent track durations.
• mediainfo_redundant_audio: Check for redundant audio tracks.
• mediainfo_resolution: Check for non-standard resolutions.
• mediainfo_dialogue_normalization: Check for dialogue normalization in lossless audio tracks.
• mediainfo_stereo_lossless: Warn if an audio track with 2 or less channels uses a different lossless codec than FLAC.
• mediainfo_empty_tracks: Warn (with error severity) if an audio track has zero channels or a subtitle track has zero elements.
• mediainfo_missing_statistics: Warn if a track is missing statistics tags.
• mediainfo_fixed_gop: Warn if video has a fixed GOP length with an encoder tag (x264/x265) in the filename.
• matroska_track_order: Verify track ordering rules.
• matroska_language_tag: Verify valid ISO language tags on tracks.
• matroska_multi_lang: Ensure 'mul' tracks have at least two full language names.
• matroska_original_language: Verify consistent OriginalLanguage flag.
• matroska_name_quality: Check for junk keywords (STEREO, ENCODED, etc.).
• matroska_name_codecs: Detect simple codecs (AC3, AAC, DTS) in track names.
• matroska_name_redundant_lang: Detect redundant language names (matching track tag).
• matroska_name_keywords: Ensure names match flags (SDH, Forced, AD, etc.).
• matroska_duplicate_tracks: Identify identical tracks.
• matroska_default_flags: Ensure specialized tracks (Forced, SDH, etc.) are NOT default and standard tracks have correct default flags.
• matroska_subtitle_format: Verify SRT or ASS requirement for text subtitles.
• matroska_subtitle_fonts: Ensure all fonts used in SubStationAlpha subtitles are attached.
• matroska_subtitle_inline_fonts: Verify fonts used in inline tags (slow).
• matroska_unused_fonts: Identifies font attachments that are not used by any subtitle track.
• matroska_font_filename_compliance: Verify that font attachment filenames match their internal names.
• matroska_ass_script_info: Verify ASS Script Info headers.
• matroska_ass_styles: Deep validation of ASS styles.
• matroska_ass_events: Validation of ASS event lines.
• matroska_ass_unused_styles: Identifies styles defined but never used in events.
• matroska_zlib_compression: Detect tracks using zlib compression.
• matroska_track_delay: Warn if a track has container delay exceeding ±1001ms (excluding TrueHD audio).
• matroska_video_cropping: Warn if resolution-based black bars are detected but no MKV crop values are set.
• matroska_title_hygiene: Verify container title doesn't contain technical metadata noise.
• matroska_app_hygiene: Verify writing application metadata is clean of local paths/UUIDs.
• matroska_data_layout: Verify that the Info and Tracks Elements are placed before the first Cluster.
• matroska_commentary_channels: Warn if a commentary audio track has more than 2 channels.
• matroska_commentary_bitrate: Warn if a commentary audio track has a bitrate exceeding 128 kbps.
• matroska_commentary_prefix: Verify commentary track names start with a standard prefix.
• matroska_commentary_pairing: Verify that subtitle commentary tracks have a corresponding audio commentary track.
• matroska_truehd_compatibility: Verify Dolby TrueHD tracks are followed by a lossy compatibility track (AC3/E-AC3) in the same language.
• matroska_chapters_existence: Verify that there is at least one chapter in the file (Disabled by default).
• matroska_chapters_start_non_zero: Verify that the first chapter starts at exactly 00:00:00.000.
• matroska_chapters_non_monotonic: Verify that chapter start times are strictly increasing.
• matroska_chapters_duplicate: Check for duplicate chapter timestamps.
• matroska_chapters_too_close: Warn if consecutive chapters are less than 10 seconds apart.
• matroska_chapters_exceed_duration: Verify that no chapter start time exceeds the total video duration.
• matroska_chapters_name_hygiene: Flags missing/whitespace-only names or consecutive duplicate names.
• matroska_chapters_language_hygiene: Flags undetermined (und) or missing display languages, or inconsistent languages.
• matroska_chapters_keyframe_alignment: Verify that chapter timestamps align with video keyframes (seek points) using the container's Cues index.
• filename_year_missing: Ensure movies have a year tag.
• filename_year_redundant: Check for redundant year tags in series.
• filename_streaming: Check for service tags on WEB sources.
• filename_tv_special: Check required tags for TV Specials.
• mdb_title: Verify title against TMDB/TVDB.
• mdb_movie_year: Verify movie release year.
• mdb_series_year: Verify series start year.
• mdb_unknown_original_lang: Warn if the original language is missing or unrecognized by MDB.
• mdb_unwanted_audio_lang: Flag audio tracks in languages other than preferred/original.
• mdb_episode_existence: Check if episode exists in database.
• mdb_episode_title: Verify episode title.
• mdb_episode_date: Verify episode air date.
• mdb_runtime: Verify video duration matches expected TMDB/TVDB runtime.
• mdb_title_type_mismatch: Warn if the file's movie/TV packaging contradicts the title type from IMDb/TMDB.
• mdb_track_languages: Verify presence of preferred and original language tracks.

Examples

Blacklisting (Disable specific checks globally)

# Skip bitrate and resolution warnings by default
disabled_checks = ["mediainfo_bitrate", "mediainfo_resolution"]

Whitelisting (Enable only specific checks in a preset)

[preset.fast]
# For this preset, skip everything EXCEPT filename and track order
enabled_checks = ["filename_characters", "matroska_track_order"]

Overriding global settings in a preset

# Global setting
disabled_checks = ["mediainfo_bitrate"]

[preset.strict]
# Enable everything (including bitrate) for this preset
disabled_checks = []