Checks: Path and File¶
duplicate-filename¶
To prevent issues with case-insensitive file systems (and software designed for
them), filenames should not be "case-insensitive duplicates". For example, an
album should not have two files named folder.jpg and Folder.JPG.
duplicate-folder-name¶
An album folder, or any folder in its path, should not have a sibling folder
that is a "case-insensitive duplicate" of it. For example, Artist/Album and
Artist/album (or Artist and artist) can coexist on a case-sensitive file
system, but they break case-insensitive pathing and conflict in synced copies.
The check reports such albums using the folders recorded by the last full scan.
There is no automatic fix: renaming folders that differ only in case can be
dangerous on some file systems or mounts. Rename the folders manually, then run
a full scan (albums scan) to update the check's data.
illegal-pathname¶
Filenames and the folders in an album's path should not include invalid
characters or be operating system reserved words. This check flags names that
might cause a problem. What is allowed and how illegal names are sanitized
depends on the path_compatibility and related settings (see
Usage).
Automatic fix: Rename any tracks or picture files with illegal names, and rename the album folder if its name is illegal, according to configuration. A target name that would collide case-insensitively with an existing file or sibling folder gets a number appended instead; the file system is checked for such collisions when the fix is applied, so a rename never clobbers another name.
If a folder above the album folder has an illegal name, the check fails
without a fix: renaming it would move other albums, so rename it manually,
then run a full scan (albums scan).
file-extension¶
For best compatibility, track filename extensions should be lowercase. For
example, an MP3 file should end with .mp3 rather than .MP3. This check
only examines scanned files with recognized extensions. Files not scanned by
albums are ignored.
Automatic fix: Rename selected files with all-lowercase file extensions.
| Option | Default | Description |
|---|---|---|
lowercase_all |
false | If true, check known image/video extensions |
folder-name¶
The folder name for each album should indicate the contents. For example, it may
be the name of the album. Folder names should be valid, as described by
path_compatibility and related settings in Usage.
The folder name format is a template string. The template substitutions are:
| Substitution | Example | Description |
|---|---|---|
$album |
Album Name |
Album name |
$artist |
The Artist |
Album artist |
Automatic fix: Rename the album folder according to the configured format.
| Option | Default | Description |
|---|---|---|
format |
"$album" |
Template to generate folder names |
ignore_folders |
["misc"] |
Ignore folders with these names |
track-filename¶
Track filenames should match relevant field values. Typically they include the
track number and title. They start with the disc number if part of a set, and
include the artist name if the album is a compilation. Filenames should be
valid, as described by path_compatibility and related settings in
Usage.
The filename format is a template string. The template substitutions are:
| Substitution | Example | Description |
|---|---|---|
$track_auto |
1-02 or 02 |
Disc#-Track# if there is a Disc#, or just Track# |
$tracknumber |
02 |
Track# only (blank if none) |
$discnumber |
1 |
Disc# only (blank if none) |
$title_auto |
Artist - Title or Title |
"Artist - Title" if artist is not album artist, or just Title |
$artist |
Artist |
Track artist |
$title |
Title |
Track title |
The zero-padding on track/disc numbers (if any) normally comes from formatting
applied to the corresponding field. albums can format the fields with the
zero-pad-numbers check/fix. But some tag types (like M4A) don't support
track number formatting. When track-filename processes such files, it checks
whether the zero-pad-numbers check is enabled in the stored configuration, and
if so, borrows its tracknumber_pad and discnumber_pad options to make
filenames consistent across file types.
The default template "$track_auto $title_auto" generates filenames like this:
| Disc | Track | Title | Artist | Album Artist | Filename |
|---|---|---|---|---|---|
| none | 01 | Foo | Bar | none | 01 Foo.mp3 |
| none | 01 | Foo | Bar | Bar | 01 Foo.mp3 |
| none | 01 | Foo | Bar | Various Artists | 01 Bar - Foo.mp3 |
| 1 | 01 | Foo | Bar | none | 1-01 Foo.mp3 |
| none | none | Foo | Bar | none | Foo.mp3 |
Dependency
Requires the album-artist, artist, track-numbering, and
track-title checks to all pass first.
Automatic fix: Rename all tracks according to configuration.
| Option | Default | Description |
|---|---|---|
format |
"$track_auto $title_auto" |
Template to generate filenames |
cover-filename¶
If the front cover image is in a file with a recognizable name, that file should
have the standard name. For example, albums recognizes .folder.png and
AlbumArtSmall.jpg and other variations as front cover images. This check flags
if one of those files exists, but the "standard" cover image file does not.
Automatic fix: If there is exactly one front cover file, rename or convert it according to the options.
| Option = default | Description |
|---|---|
filename = "cover.*" |
Cover file. .* = keep same file type, .png or .jpg = convert if needed |
jpeg_quality = 90 |
If converting to JPEG, use this quality setting |
album-under-album¶
This check reports an album that is in a subfolder of another album. Maybe they should be in separate folders or this check should be disabled. No fix offered. The check only looks at the albums included in the check run, so a filtered run may not catch an album nested in an album that is not included.
unreadable-track¶
This check runs before checking tags and fails if the tagger cannot open or
detect streams in a track. This is probably because the file is corrupt. The fix
offers to rename any unreadable tracks by adding .unreadable to the end of the
filename, preserving the file but causing it to be ignored. The fix is not
automatic.