Package: beets-check
beets-checkThebeetsplugin for paranoid obsessive-compulsive music geeks.beets-checklets you verify the integrity of your audio files. It computes
and validates file checksums and uses third party tools to run custom
tests on files.This plugin requires at least version 1.6.0 of beets and at least Python 3.8pip install --upgrade beets>=1.6.0
pip install git+git://github.com/geigerzaehler/beets-check.git@masterThen addcheckto the list of plugins in your beet configuration.
(Runningbeet config --editmight be the quickest way.)If you want to use third-party tools to test your audio files you have
to manually install them on your system. Runbeet check --list-toolsto see a list of programs the plugin can use oradd your
own.UsageLet’s get started and add some checksums to your library.$ beet check -a
WARNING integrity error: /music/Abbey Road/01 Come Together.mp3
Adding unknown checksums:  1032/8337 [12%]Thecheckcommand looks for all files that don’t have a checksum yet.
It computes the checksum for each of these files and stores it in the
database.  The command also prints a warning if one of the third-party
tools finds an error. (More on thoselater.)After some time (or maybe a system crash) you’ll probably want to go back to
your library and verify that none of the files have changed. To do this run$ beet check
FAILED: /music/Sgt. Pepper/13 A Day in the Life.mp3
Verifying checksums:  5102/8337 [53%]For later inspection you might want to keep a log.  To do that just
redirect the error output withbeet check 2>check.log. AllWARNINGandERRORlines are sent to stderr, so you will still see the
progressbar.When you change your files through beets, using themodfiycommand
for example, the plugin willupdate the checksums
automatically. However, if you change files
manually, you also need to update the checksums manually.$ beet check -u 'album:Sgt. Pepper'
Updating checksums:  2/13 [15%]Third-party TestsThe plugin allows you to add custom file checks through external tools.
The plugin supportsflac --test,oggz-validate, andmp3valout of
the box, but you can alsoconfigure your own.Custom tests are run when on the following occasions.Before importing a file (see below)Before adding checksums with the-aflagWhen runningbeet check --externalThe file checks are not run when updating files. The rationale is that
if the checksum of a file is correct, the file is assumed to be clean
and pass all the custom tests.If some file fails a test the lineWARNING error description: /path/to/fileis printed.Usage withimportSince it would be tedious to runcheck -aevery time you import new music
into beets,beets-checkwill add checksum automatically. Before file
is imported the plugin will also check the file with the provided
third-party tools. If the check fails beets will ask you to confirm the
import.$ beet import 'Abbey Road'
Tagging:
    The Beatles - Abbey Road
URL:
    http://musicbrainz.org/release/eca8996a-a637-3259-ba07-d2573c601a1b
(Similarity: 100.0%) (Vinyl, 1969, DE, Apple Records)
Warning: failed to verify integrity
  Abbey Road/01 Come Together.mp3: MPEG stream error
Do you want to skip this album? (Y/n)After a track has been added to the database and all modifications to the tags
have been written, beets-check adds the checksums. This is virtually the same as
runningbeets check -aafter the import.If you runimportwith the--quietflag the importer will skip
files that do not pass third-party tests automatically and log an
error.Automatic UpdateThewriteandmodifycommands as well as some plugins will
change a file’s content and thus invalidate its checksum. To relieve you from
updating the checksum manually,beets-checkwill recalculate the checksums of
all the files that were changed.$ beet check -e 'title:A Day in the Life'
ded5...363f */music/life.mp3

$ beet modify 'artist=The Beatles' title:A Day in the Life'

$ beet check -e 'title:A Day in the Life'
d942...5a82 */music/life.mp3This is basically equivalent to runningbeets check -u QUERYafter a modifying
command.To make sure that a file hasn’t changed before beets changes it, the
plugin will verify the checksum before the file is written.  If the
check fails, beets will not write the file and issue a warning.$ beet modify 'artist=The Beatles' 'title:A Day in the Life'
could not write /music/life.mp3: checksum did not match value in libraryUsage withconvertTheconvertplugin can replace an audio file with a
transcoded version using the--keep-newflag. This will invalidate you
checksum, butbeets-checkknows about this and will update the
checksum automatically. You can disable this behaviour in the plugin
configuration. Note that, at the moment we do not verify the checksum
prior to the conversion, so a corrupted file might go undetected. This
feature is also only available with the master branch of beetsCLI Referencebeet check [--quiet]
                 [ --external
                 | --add
                 | --update [--force]
                 | --export
                 | --fix [--force]
                 ] [QUERY...]
beet check --list-toolsThe plugin has subcommands for checking files, running integrity checks,
adding, updating and exporting checksums and listing third-party tools. All but
the last accepty aQUERYparamter that will restrict the operation to files
matching the query.  Remember, if a query contains a slash beets willinterpret it as a pathand match all files that are contained in
a subdirectory of that path.The defaultcheckcommand, as well as the--add,--update, and--externalcommands provide structured output tostderrto be easily parseable
by other tools. If a file’s checksum cannot be verified the lineFAILED: /path/to/fileis printed to stdout. If an external test
fails, the lineWARNING error description: /path/to/fileis printed.In addition, the commands print a progress indicator tostdoutifstdoutis connected to a terminal. This can be disabled with the-q, --quietflag.beet check [-q] [QUERY...]The default command verifies all
file checksums against the database. The output is described above.
Exits with status code15if at least one file does not pass a
test.-e, --externalRun third-party tools for the given file. The
output is described above. Exits with status code15if at least
one file does not pass a test.-a, --addLook for files in the database that don’t have a
checksum, compute it from the file and add it to the database. This will also
print warnings for failed integrity checks.-u, --updateCalculate checksums for all files matching the
query and write the them to the database. If no query is given this will
overwrite all checksums already in the database. Since that is almost
certainly not what you want, beets will ask you for confirmation in that
case unless the--forceflag is set.--exportOutputs a list of filenames with corresponding
checksums in the format used by thesha256sumcommand. You can then use
that command to check your files externally. For examplebeet check -e | sha256sum -c.-x, --fix [--force | -f]Sincev0.9.2. Fix files with
third-party tools. Since this changes files it will ask for you to
confirm the fixes. This can be disabled with the--forceflag.-l, --list-toolsOutputs a list of third party programs thatbeets-checkuses to verify file integrity and shows whether they are
installed. The plugin comes with support for theoggz-validate,mp3valandflaccommands.ConfigurationBy defaultbeets-checkuses the following configuration.check:import:yeswrite-check:yeswrite-update:yesconvert-update:yesthreads:num_of_cpusThese option control at which pointbeets-checkwill be used automatically by
other beets commands. You can disable each option by setting its value tono.import: noDon’t add checksums for new files during the import process.
This also disables integrity checks on import and will not ask you to skip
the import of corrupted files.write-check: noDon’t verify checksums before writing files withbeet writeorbeet modify.write-update: noDon’t update checksums after writing files withbeet writeorbeet modify.convert-update: noDon’t updated the checksum if a file has been
converted with the--keep-newflag.threads: 4Use four threads to compute checksums.Third-party Toolsbeets-checkallows you to configure custom tests for your files.Custom tests are shell commands that are run on an audio file and
may produce an error.check:tools:mp3val:cmd:'mp3val{}'formats:MP3error:'^WARNING:.*\(offset0x[0-9a-f]+\):(.*)$'fix:'mp3val-f-nb{}'Each tool is a dictionary entry undercheck.tools, where the key is
the tools name and the value is a configuration dictionary with the
following keys.cmdThe shell command that tests the file. The string is
formatted with python’sstr.format()to replace
'{}' with the quoted path of the file to check.formatsA space separated list of audio formats the tool can
check. Valid formats include 'MP'errorPython regular expression to match against the tools
output. If a match is found, an error is assumed to have occured
and the error description is the first match group.fixShell command to run when fixing files. The command is
formtted similar tocmd.A test run with a given tool is assumed to have failed in one of the
following two cases.The combined output ofstdoutandstderrmatches theerrorRegular Expression.The shell command exits with a non-zero status code.LicenseCopyright (c) 2014 Thomas ScholtesPermission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"), to
deal in the Software without restriction, including without limitation the
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
sell copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.