All Checks¶

All checks and their configuration options.

Order¶

Enabled checks will run in order on each album:

1. duplicate-pathname check ("Path and Filename")
2. illegal-pathname check ("Path and Filename")
3. file-extension check ("Path and Filename")
4. unreadable-track check ("Other Tags")
5. extra-whitespace check ("Other Tags")
6. All "Numbering" checks
7. Remaining "Other Tags" checks
8. All "Pictures" checks
9. Remaining "Path and Filename" checks

Within each category, the checks run in the order they are listed below.

Dependencies¶

Individual checks are mostly independent, but some checks will not run on an album unless a previous check ran and passed. For example, the specific fix from the disc-in-tracknumber check should be applied before invalid-track-or-disc-number flags the track number as invalid. And, when the invalid-image check doesn't pass, none of the other "Pictures" checks can run. Other dependencies are listed below.

Checks: Path and Filename¶

duplicate-pathname¶

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.

illegal-pathname¶

Filenames should not include invalid characters or be operating system reserved words. This check flags filenames that might cause a problem. What is allowed and how illegal filenames are sanitized depends on the path_compatibility and related settings (see Usage).

Automatic fix: Rename any tracks with illegal names, according to configuration.

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.

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:

Automatic fix: Rename the album folder according to the configured format.

track-filename¶

Track filenames should match tags. 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:

The zero-padding on track number and disc number (if any) normally comes from formatting applied to the corresponding tag value. albums can format the tags with the zero-pad-numbers check/fix. But in some formats like M4A, the tracknumber and discnumber tags don't support formatting. For such formats, if the zero-pad-numbers check is enabled, the tracknumber_pad and discnumber_pad options from that check will be used to generate possibly zero-padded $tracknumber and $discnumber substitutions in this check.

The default template "$track_auto $title_auto" generates filenames like this:

Automatic fix: Rename all tracks according to configuration.

cover-filename¶

If the front cover image is in a file with a recognizable name, it should have a consistent 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.

album-under-album¶

This check reports when an album has another album in a subfolder. Maybe they should be in separate folders or this check should be disabled. No fix offered.

Checks: Numbering¶

Track number and disc number tag issues.

disc-in-track-number¶

If the disc number and track number are combined in the track number tag with a dash (i.e. track number="2-03") instead of being in separate tags, this is treated as an error. Subsequent checks require track numbers to be numeric.

Automatic fix: Split the values into track number and disc number tags.

invalid-track-or-disc-number¶

This check reports when an album has invalid or ambiguous values for track number, track total, disc number or disc total. If these fields cannot be resolved to a single valid number, they are not useful and should be removed.

Rule: for each track, if present, track/disc number/total tags should each have a single value and that value should be a positive number (0 is not valid).

Automatic fix: For each of the noted tags in each track, discard all values that are non-numeric or 0. If exactly one unique value remains, save it. Otherwise, delete the tag.

disc-numbering¶

Reports on issues with disc number and disc total (TPOS in ID3). Optionally, removes redundant disc number tag for sets of one. See configuration to control whether multiple disc sets should be required to have all tracks in one folder. Mismatching disc total values are one reason players incorrectly split albums.

Rules:

• If any track has disc number, all tracks should have disc number
• Disc numbers should start at 1 and be sequential (1, 2, 3...)
• If present, the disc total should be the number of distinct disc number values which should be the same as the highest disc number
• All tracks with disc total should also have disc number
• The legacy tag "totaldiscs" should be removed if it is present
• The selected disc total presence policy should apply
  • "consistent": either all tracks have disc total, or none do
  • "always": all tracks should have disc total
  • "never": disc total should be removed

Automatic fix if any track has "totaldiscs" tag, remove it.

Automatic fix for disc total policy: If the policy is "never", always remove the tag. If the policy is "always", and a consistent total is set on some tracks, set the same total on the others.

When discs_in_separate_folders is enabled (default), this check will ignore when an album has only one disc of a multiple disc set. But that also means it cannot tell whether an album is missing a disc number or whether disc total is correct. If you can put multiple-disc albums together in one folder, do that and set discs_in_separate_folders to false. Then, if wanted, you can also set remove_redundant_discnumber to true.

track-numbering¶

Reports on several issues with track numbers and track totals, including apparently missing tracks.

The rules are:

• Every track should have a single decimal track number
• For each disc, track numbers should start at 1 and be sequential
• For each disc, if track total is present, it should be the number of tracks on that disc
• All tracks with track total should also have track number
• The selected track total presence policy should apply:
  • "consistent": either all tracks have track total, or none do
  • "always": all tracks should have track total
  • "never": track total should be removed

Automatic fix for missing track numbers: If track number tags are missing from some tracks but all track numbers can be guessed from the filename, recreate track number tags from filenames.

Automatic fix for track total policy: If the policy is "never", always remove the tag. If the policy is "always", and a consistent total is set on some tracks, set the same total on the others.

zero-pad-numbers¶

Apply selected policies for zero-padding in the track number/total and disc number/total tags. Some media players and many file managers do not show tracks in the correct order unless the track numbers are zero-padded, because for example "2" comes after "10" when sorted alphabetically.

This check does nothing on M4A files because track numbers (and track total, disc number, disc total) are only stored as plain unformatted numbers.

Automatic fix: If no major problems detected in relevant tags, apply policy.

Choose a policy for each tag. The policy options are:

• "ignore": don't check this tag
• "never": do not use leading zeros
• "if_needed": leading zeros when required for all values to have the same number of digits (same as "never" for track/disc totals)
• "two_digit_minimum": all values should be at least two digits (three if more than 99 values)

The default settings will result in, for example, track 04 of 07 and disc 1 of 1. If you set all policies to "if_needed" instead, you get, for example, track 4 of 7 and track 04 of 12.

Other Tags¶

Tag checks that are not related to numbering or pictures.

unreadable-track¶

This check runs before all other tag checks 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.

extra-whitespace¶

None of the basic tags like album, artist, title, track number, etc. should have extra spaces or other whitespace characters at the beginning or end.

Automatic fix: Remove whitespace from the beginning and end of all values for all supported basic text tags.

album-tag¶

Tracks should have album tags. The fix attempts to guess album name from tags on other tracks in the folder, and the name of the folder. Choose from options.

Automatic fix: If there is exactly one option for the album name, use it.

album-artist¶

The "album artist" tag (e.g. albumartist, TPE2) allows many media players to group tracks in the same album when the "artist" is not the same on all the tracks.

Rules:

• If any tracks have different artists, all tracks should have the same album artist.
• If any track has album artist, all tracks should have the same album artist.
• For FLAC and other Vorbis Comment files only: the tag album artist should not be present (standard is albumartist).

The fix offers candidates found in the tags plus the option "Various Artists". It can also remove or convert legacy tags or apply a policy from options below.

Automatic fix: If the album artist is or would be redundant, and one of the optional policies below is enabled, apply the policy.

Automatic fix: If legacy album artist tag is present and standard album artist tag is not present, convert the tag to the standard.

Automatic fix: If both legacy album artist tag and standard album artist tag are present, remove the legacy album artist tag. (Value is not checked.)

artist-tag¶

An "artist" should be present on all tracks. If it is missing from any tracks, candidates to fix include the values for artist and album artist taken from all tracks in the album.

If the parent folder containing the album folder is not a prohibited name, it is also a candidate. Prohibited names can be configured with an option.

Automatic fix: If there is exactly one candidate for artist name, apply it to all tracks that do not have an artist tag.

single-value-tags¶

If present, the specified tags should not have multiple values in the same track. Many multiple-value tags are valid, but they might be unintended, and might cause unpredictable results with various media players. The fix for this check provides options to concatenate multiple values into a single value, after removing duplicates.

Other specific checks may enforce a single value for certain tags such as track number.

To configure how albums will combine multiple values, use the concatenators option. Pay attention to whether or not the separator includes extra spaces - the first option gives "Alice / Bob" and the second is "Alice/Bob".

By default, whichever concatenator is first will be used when automatic fix is requested. To disable this, change the automatic_concatenate option.

Automatic fix: If a track has duplicate values for the tag, the automatic fix will remove them. And if automatic_concatenate is enabled (default), unique values will be combined into a single value.

track-title¶

Each track should have at least one title tag. This check doesn't care if a track has more than one title. If the track doesn't have a title, it can be guessed from the filename, as long as the filename looks similar to one of these examples:

• 01 the title.flac
• 01. the title.mp3
• 01 - the title.mp3
• 1-03 - the title.flac
• the title.flac (if nothing else matches)

If the filename looks like a track number only, no title guess will be made. However, if the title doesn't match any recognized pattern, the guess will be the whole filename except for the extension.

Automatic fix: If every tag that has a missing title also has a filename from which a title can be guessed, fill in all empty titles.

genre-present¶

This check applies a user-defined policy for genre tags. By default, if genre is present on any track, the same genre must be present on all tracks in the album. The presence policy options are:

• "consistent": either all tracks have genre, or none do
• "always": all tracks should have genre
• "never": genre should be removed

Automatic fix If the policy is "never", always remove the genre. If the policy is "always", and a consistent genre is set on some tracks, set the same genre on the others.

musicbrainz-tags¶

Whether or not you use MusicBrainz, inconsistencies in MusicBrainz tags within an album can cause problems for some players. When the MusicBrainz Album Id or MusicBrainz Album Artist Id or MusicBrainz Album Release Country is not the same on all tracks in an album (or not set on every track), some music players interpret this as two separate albums even if other tags are all the same. This check reports when those tags are not set consistently across the album.

Other behaviors of this check are controlled by the options. If you don't use MusicBrainz, you might want to remove all MusicBrainz tags to avoid conflicts between them and the standard tags. If you do use MusicBrains, you may want to remove deprecated MusicBrainz tags (MusicBrainz TRM Id).

Automatic fix: If MusicBrainz Album Id or MusicBrainz Album Artist Id is not the same on all tracks (or not set on every track), remove that tag from every track.

Automatic fix: If remove_all is enabled, remove all MusicBrainz tags.

Automatic fix: If remove_deprecated is enabled, remove deprecated MusicBrainz tags.

Other Tags: Per Album¶

The checks in this section each check a different tag corresponding to the name of the check, but they also share a purpose: if one of these tags is set inconsistently on tracks in an album, some players treat this as distinct albums. So each of these tags should be set to the same value, or not set.

These checks apply a user-defined policy for the corresponding tags. The presence policy options are:

• "consistent": either all tracks have the tag, or none do
• "always": all tracks should have the tag
• "never": the tag should be removed

If any track has a value, then all values must be the same.

Automatic fix If the policy is "never", always remove the tag. If the policy is "consistent" or "always", and a consistent value is set but only on some tracks, set that value on the tracks which have no value. And if the policy is "consistent" but no single value is identified, remove the tag from all tracks.

publisher-tag¶

See "Other Tags: Per Album" above for common behavior of this check.

In addition, for Vorbis Comment tags (FLAC, etc) the label/publisher should be stored only as organization. If the legacy Vorbis Comment tags label or publisher are set, they should be removed to avoid confusion and players splitting albums.

Automatic fix: If label or publisher are present, remove them.

album-sort-tag, album-artist-sort-tag, barcode-tag, compilation-tag, release-type-tag¶

See "Other Tags: Per Album" above for details on these per-album tag checks.

release-country-tag¶

See "Other Tags: Per Album" above for common behavior of this check.

Pictures¶

These checks operate on embedded pictures and image files in the album folder.

In some media formats including FLAC files, embedded images are classified with the "picture type" codes originally defined for ID3v2 APIC frames.

When checks refer to the "cover" or "front cover" this means images classified as COVER_FRONT (0x03). If an embedded image does not have an explicit picture type (such as covr atom in M4A files), the type COVER_FRONT is assumed.

Image files are also considered front covers if they have the word "folder", "cover", "thumbnail" or "album" in the filename.

invalid-image¶

During the scan, albums tries to load every embedded image and supported image file. If it fails, the image is probably corrupt and a load_issue error will be stored. This check reports on all images that could not be loaded.

The fix will list and offer to delete all image files that cannot be loaded, and remove all embedded images that cannot be loaded.

duplicate-image¶

Each of the tracks in an album may have the same images embedded. But other duplicate image data is not useful. Rules:

• Each of the pictures embedded in a track should be a different image (don't have the same image embedded twice)
• Image files should not be exact duplicates of other image files

Automatic fix: If several image files (not embedded) contain the exact same image contents, keep the one with the shortest filename and delete the rest.

picture-metadata¶

FLAC files store metadata about embedded pictures (MIME type, dimensions). Ogg Vorbis uses a comment with the same structure. ID3 tags include the MIME type of the image in the APIC frame, etc. This check loads the image data and compares the reported MIME type and dimensions (if present) to the real image data.

Automatic fix: For each file with incorrect metadata, re-embed all the images with the same image data and correct metadata. Fix not yet available for other formats.

album-art¶

Image files embedded in tracks should be a reasonable size and in a widely-supported format.

Rules:

• Embedded images should not be very large files (see options)
• Embedded images should be in PNG or JPEG format (not GIF or other)

Automatic fix: For each unique embedded image that is too large or not a preferred image type, extract the image to a file and un-embed it. If one of the images un-embedded is cover art, the extracted file can be used by subsequent checks to re-embed proper cover art.

cover-available¶

If any track has embedded pictures, or if there are any image files in the folder, the album is expected to have front cover art, meaning one of the embedded images or filenames should indicate that it's cover art. Optionally, cover art can be required for all albums (see settings).

If there are any non-cover images available, this check offers a fix to select one of them as the front cover by renaming or extracting it to an image file with a standard name.

Rules:

• If there are any embedded images or image files, one or more of them should be in a file cover.jpg (or similar) to be recognized as the front cover image.
• When "cover_required" setting is true, a front cover image must be present. If a download tool is available, it can be tried (see below).

Automatic fix: If the album has no front cover art, but there is exactly one unique image (embedded and/or image file), make that image the cover art by renaming the image file to cover.jpg/.png/etc. or by extracting the embedded image from one of the tracks to cover.jpg or .png.

Automatic fix: If the album has no front cover art, and there is no other art embedded or in the folder that can be used as cover art, and if get_cover_command is configured or the default tool SACAD is found: try to download cover art.

The get_cover_command option is a template. The template substitutions are:

* - Cover filename is taken from *cover-filename configuration

If SACAD is installed (assumed if the command sacad and sacad_r are both found on the path), the default get_cover_command will be set to:

sacad --preserve-format --size-tolerance 60 $artist $album 1200 $filename

cover-unique¶

Usually, albums should have a single unique image as cover art, or, one cover image embedded in the tracks plus a higher-resolution image file.

Rules:

• All front cover art associated with the album should be the same image, including embedded COVER_FRONT as well as image files matching the filenames above, except:
• There can be two unique cover images, if one of them (like a high-res version of the cover) is a file and it is marked in albums as "front cover source"

Tracks may have any number of embedded images that are not marked as COVER_FRONT. Other image files in the album folder, where the filename does not match the expected cover art filenames above, will be treated as picture type OTHER.

Automatic fix: If there are multiple cover images but one of them is a file that is larger than the other files and/or embedded images, mark that file as "front cover source" so that file will no longer count as a duplicate. This might not completely fix the check if there are more front cover images. The next automatic fix would delete the other image files identified as cover art:

Automatic fix: If there are multiple image files (not embedded) recognized as front cover source by their filenames, and one of them has already been marked as "front cover source", delete the other front cover art image files.

conflicting-embedded¶

Within each track, there should not be more than one picture for a given picture type (or optionally only for front cover pictures -- see options). For example, even if tracks have unique "front cover" images, a single track should not have more than one embedded image marked as "front cover".

No automated fix yet.

cover-dimensions¶

Images treated as picture type COVER_FRONT should be square and within a range of acceptable sizes.

Rules:

• If an image is marked as front cover source, only that image is evaluated. Using the front cover source to fix embedded images is a separate task.
• The width/height of cover art should not be too small or large (see options)
• Cover art should be square (see options)

Automatic fix: If the front cover image (embedded or in a file) is not as square as the squareness setting but at least as square as the fixable_squareness setting, fix it by cropping first (see options), and if necessary squashing it the rest of the way. The new square cover image will be saved as a file with the configured type and marked as "front cover source" for the album. If the unsquare source was an image file, it will be deleted.

If embedded front cover images are present they are not changed by this fix. The new cover image file is set as "front cover source".

cover-embedded¶

If there is any front cover image (file or embedded), all tracks should have some front cover image embedded. It should not be larger than the maximum size and should be the required MIME type if set (see max_height_width and require_mime_type options).

Furthermore, if there is a front cover image that has been marked as "front cover source" in albums, all tracks should have a front cover image that exactly matches the specs (dimensions and MIME type) configured in this check (see create_* options).

When there are existing embedded covers that do not meet the above requirements, the presence of more than one unique front cover image will prevent automatic fixes by this check, to avoid automatically overwriting per-track cover art.

When the above requirements above are met, this check will pass. To cause albums to embed new cover art when there is "good enough" cover art already, place high resolution cover art in the folder named cover.jpg (or another recognized front cover filename) and run the cover-unique check, which should offer to mark the new art as "front cover source". Subsequently, as long as the size or MIME type of the previous embedded cover is not exactly the same as what this check is configured to generate, the new cover can be embedded into tracks by this check.

Automatic fix: When there is a front cover source file and there is not more than one unique front cover image embedded in the tracks, generate a new cover from the cover source and embed it in every track, replacing any existing cover.

Automatic fix: When there is no front cover source, but there is only one unique cover image, that image can be extracted to a file (if it is not already a file) and marked as front cover source. Rechecking will then offer the automatic fix above.

Note: The max_height_width and require_mime_type settings only apply to albums where no "front cover source" image is defined.