The AbsolutelyBaching Flac Checker

1.0 What is AFC?

FLAC music files can, over time and for no very obvious reasons, become internally corrupt. The AbsolutelyBaching Flac Checker (or AFC for short) is a shell script which checks all FLAC files found in a specified location for signs of this internal corruption. If it finds any corrupt files, it will warn you and tell you which ones they are. By regularly running the script against your music collection, you can thus identify internal corruption if it happens -or get assurance that it isn’t happening.

AFC does not, however, ever attempt to repair or fix corrupt FLAC files. It advises you of their existence, but it’s entirely up to you how to fix up the problem. Fixing corrupt FLACs is usually done by re-ripping the music from the original CD or restoring a known-good copy of the FLAC file in question from an older backup.

2.0 What does AFC do?

AFC runs entirely as a command-line tool, from a terminal session window. You tell it what directory contains the music files you want validated. It will then open each file in turn. If it determines that the file was last checked for corruption sufficiently long ago (by default, 30 days), then it will re-check the file and determine if its audio component has become corrupted. If it determines that a file was checked within the last 30 days (by default), then it won’t waste CPU time and memory resources re-checking the file at all, but will simply skip over the file without taking any further action about it.

In this way, AFC is an efficient method of detecting corruption: it only checks files which, by their age since their last check, are deemed to be worth re-validating, whilst more freshly-checked files won’t be re-validated unnecessarily.

If AFC does check a FLAC file, and it passes validation, it will modify the file and write the date of the corruption check as a Vorbis Comment called TAGDATE. It is by checking the value of TAGDATE that AFC can determine when a file was last checked for internal corruption.

3.0 Obtaining AFC

To use AFC, your Linux distro needs to have some prerequisite software packages installed. Usually, these are already present in most distros, but the command to install or re-install all of them in one hit will be a variant of:

sudo pacman -Sy flac bc

Pacman -Sy is Manjaro’s command to install fresh software packages. On other distros, you may need to use equivalent apt-get install or dnf install commands instead.

Once the prerequisites are present on your system, you can download AFC (which is simply a Bash script) by clicking this link. Save it to anywhere you prefer, but I’m going to assume you save it in your Downloads folder for what follows. Once it’s been saved to disk, please feel free to open the file in a text editor and check that it’s not going to do anything that it’s not supposed to do!

Once downloaded and saved somewhere, run the following commands:

sudo mv $HOME/Downloads/afc.sh /usr/bin 
sudo chmod +x /usr/bin/afc.sh 
sudo ln -s /usr/bin/afc.sh /usr/bin/afc

That’s the equivalent of an installation script. It copies the download from wherever you stored it on disk to the /usr/bin directory (as mentioned, the specific command shown assumes that you downloaded it to your personal Downloads folder); it then makes the script executable; and finally it creates a shortcut to the script called just ‘afc’ so that you don’t have to remember the “.sh” suffix every time you want to run it. Some distros might not have a /usr/bin directory; move the file to /bin instead in that case. The key thing is to try to get the script into a directory that is already listed within your PATH environment variable, so that the script can be executed from anywhere without having to spell out the complete path to it.

Once you’ve ‘installed’ AFC in this way, you can run the Classical CD Tagger by simply typing the command:

afc --music=<path> --logdir=<path> [--force] [--checkdays=<number] [--verbose]

That is, you should supply an absolute path to wherever your music files are located and an absolute path to a folder where you want the log file written to. If you specify neither, then the current working directory (i.e., the directory you are in when you run AFC) is set to be both the music and logging directory. If you specify a music folder but not a log directory, the log directory is set to be whatever the music directory was set to. If you specify (or imply) a log directory which doesn’t exist or to which you do not have write permissions, the /tmp directory is used for logging instead.

Logging is always performed: the log file will show what folder is being checked, how many files were checked and how many have been found to be ‘clean’ or ‘corrupt’. If you specify the ––verbose option, then the full path and file name of every file being checked or skipped will be listed. The full path and file name of any files found corrupt are always recorded in the log, regardless of whether verbose mode was specified or not. Log files are automatically named in the form AFC-<timestamp>.log. The “timestamp” component of the name will be a number, consisting of year, month, date, hour, minute. So, for example, you might have a file called AFC-202004191334.log. This would be created by a run of AFC that started on April 20th, 2020 at 1:34pm.

By default, AFC will only re-check a file for corruption if it determines it was previously checked more than 30 days ago. If you prefer to check files more frequently, you can either specify ––force (which essentially forces every file to be re-checked every time AFC encounters it) or a ––checkdays=x parameter, where ‘x’ is a number of days. If you said ––checkdays=6, for example, then AFC would only re-check a file if it determined that it was previously checked more than 6 days ago. If you specify both ––force and ––checkdays parameters, then ––force takes precedence and the ––checkdays setting is simply ignored.

Whilst AFC can be run in an interactive manner, directly in a command terminal, it is most suitably run from a crontab. For example:

0 2 1 * * /usr/bin/afc.sh --music="/music/flac/hjr/classical" --logdir="/home/hjr/Logs"

…in my personal crontab would mean that on the 1st day of each month, my entire classical music collection would be checked by AFC, with the results of the scan being written to my personal Logs directory. Note that a full path to the executable is advised in crontab, because the environment that applies (including any PATH statement) when invoking a crontab entry may not be the one that you are expecting.

4.0 Worked Examples

For a complete set of worked examples using AFC, and a lengthy discussion of the logic underpinning what it does and why and how it does it, see this page, especially section 9.

Author

AFC was devised and written by Howard Rogers (hjr@dizwell.com).

License

AFC is copyright © Howard Rogers 2019, but is made available freely under the GPL v2.0 only. That license may be downloaded here.

Bugs Tracking, Feature Requests, Comments

There is no formal mechanism for reporting and tracking bugs, feature requests or general comments. But you are very welcome to email your comments to hjr@dizwell.com.