Bad Files Plugin

The badfiles plugin adds a beet bad command to check for missing and corrupt files.

Configuring

First, enable the badfiles plugin (see Using Plugins). The default configuration defines the following default checkers, which you may need to install yourself:

• mp3val for MP3 files

• FLAC command-line tools for FLAC files

You can also add custom commands for a specific extension, like this:

badfiles:
    check_on_import: yes
    commands:
        ogg: myoggchecker --opt1 --opt2
        flac: flac --test --warnings-as-errors --silent

Custom commands will be run once for each file of the specified type, with the path to the file as the last argument. Commands must return a status code greater than zero for a file to be considered corrupt.

You can run the checkers when importing files by using the check_on_import option. When on, checkers will be run against every imported file and warnings and errors will be presented when selecting a tagging option.

Using

Type beet bad with a query according to beets’ usual query syntax. For instance, this will run a check on all songs containing the word “wolf”:

beet bad wolf

This one will run checks on a specific album:

beet bad album_id:1234

Here is an example where the FLAC decoder signals a corrupt file:

beet bad title::^$
/tank/Music/__/00.flac: command exited with status 1
  00.flac: *** Got error code 2:FLAC__STREAM_DECODER_ERROR_STATUS_FRAME_CRC_MISMATCH
  00.flac: ERROR while decoding data
             state = FLAC__STREAM_DECODER_READ_FRAME

Note that the default mp3val checker is a bit verbose and can output a lot of “stream error” messages, even for files that play perfectly well. Generally, if more than one stream error happens, or if a stream error happens in the middle of a file, this is a bad sign.

By default, only errors for the bad files will be shown. In order for the results for all of the checked files to be seen, including the uncorrupted ones, use the -v or --verbose option.