
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:
       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.


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.
