htagcli.toml

# Default configuration

# Settings under [filename] are used by:
# - the `fix-path` command
# - the `check` command’s `filematches` check (see also [checks.check_files])
[filename]

# Pattern used to generate or validate file paths
# Available placeholders:
# - {artist}: artist tag
# - {albumartist}: album artist tag
# - {album}: album tag
# - {title}: title tag
# - {genre}: genre tag
# - {track}: track number (see `pad_track_numbers`)
# - {year}: year tag
# - {disc}: disc number (see `pad_disc_numbers`)
# Additional syntax:
# - {albumartist|artist}: use albumartist tag; if missing, fall back to artist
# - {prefix-?disc?-suffix}: if the disc tag is present, include it with the
# given prefix and suffix; otherwise, omit everything between the braces
filename_matches = "{albumartist|artist}/{album}/{Disc-?disc?}/{track}-{title}"

# Characters to sanitize in file paths and how to handle them
# Each entry defines:
# - `char`: the character to match
# - `action`: one of:
#   - "remove": delete the character
#   - "replace:<new_char>": replace it with `<new_char>`
unwanted = [
  { char = " ", action = "replace:_" },
  { char = "/", action = "remove" },
  { char = "?", action = "remove" },
  { char = ":", action = "remove" },
  { char = "\"", action = "remove" },
  { char = "*", action = "remove" },
  { char = ">", action = "remove" },
]

# How to pad track numbers in the {track} placeholder
# Accepted values:
# - "ignore": ignore padding when checking; no padding when fixing
# - "1": no padding
# - "2": pad to 2 digits (01, 02, ..., 10, 11, ...)
# - "3", "4", ...: pad to N digits
pad_track_numbers = "2"

# Same for disc numbers
pad_disc_numbers = "ignore"

# htagcli will truncate any placeholder value exceeding this length. Useful for
# tracks with very long titles.
placeholder_max_length = 30

# Settings for the `fix-path` command
[fix_paths]

# Directory where music files are moved when fixing their paths
base_dir = "/absolute/path/to/your/Music"

# Used to move cover files along the audio files. `checks.disc_cover.filenames`
# must be enabled for this to work.
# Any file that matches `checks.disc_cover.filenames` in the same directory as
# the current audio file will be moved along with it.
move_cover = true

# Configuration for validation checks
[checks]

# Ensure required tags are present
[checks.track_tags]
enable = true
tags = ["title", "artist", "album", "genre", "year", "track"]

# Ensure the genre tag matches one of the allowed values
[checks.track_genre]
enable = true
among = [
  "Pop/Rock",
  "Jazz",
  "Country",
  "Blues",
  "Latin",
  "International",
  "Classical",
  "Hip-Hop",
]

# Verify that file paths match the expected naming pattern and formatting
# options
[checks.track_filename]
enable = true

# Verify that each disc directory contains a cover image
[checks.disc_cover]
enable = true
filenames = ["cover.jpg", "cover.png", "cover.gif"]
# optional size constraints in pixels, not taken into account if left
# unspecified.
# Warning: this makes the check significantly slower
min_size = { width = 300, height = 300 }
max_size = { width = 1000, height = 1000 }

# Verify that all tracks from the same disc reside in a single directory
# Note: htagcli groups files by disc while scanning input paths recursively.
[checks.disc_same_dir]
enable = true

# Verify that disc-level tags are consistent across all tracks of a disc. No
# need to check for album, artist, or albumartist tags here as it is already
# enforced by htagcli when grouping tracks into discs.
[checks.disc_tags] enable = true tags = ["year", "genre"]

# Verify that track numbers in each disc are sequential starting from 1
[checks.disc_tracks_sequential]
enable = true

# Verify that album-level tags are consistent across all discs of an album.
# Same as above, no need to check for album, artist, or albumartist tags here.
[checks.album_tags]
enable = true
tags = ["year", "genre"]

# Verify that disc numbers within an album are sequential starting from 1
[checks.album_discs_sequential]
enable = true

# Verify that all tracks from an artist have the same genre
[checks.artist_same_genre]
enable = true
# In some cases, an artist may legitimately span multiple genres. One can list
# them here to have the check pass for those artists.
except = [
  { artist = "Some Artist", genres = ["Pop/Rock", "Original Soundtracks"] }
]