The MAXV Report Tool (MAXVRPRT)

1.0 What is MAXVRPRT?

Quite some time ago, I wrote a little utility called MAXV which, when run in a folder full of FLACs, will measure the loudest peak volume in each FLAC. If the loudest volume found is significantly quieter than the theoretical maximum, undistorted volume, MAXV will ask you if you want to boost the volume of all the FLACs by whatever amount would get the loudest file to near that idealised maximum. In the curiously inverted world of audio volume, that maximum value is 0 decibels (dB); a track whose peak volume is  -0.6dB is very close to the maximum; a track with a peak volume of -19dB is significantly quieter than the maximum possible value. MAXV is careful to boost every FLAC found in a single folder by the same amount, so that the relative volume between the tracks doesn't change, but the absolute volume of all them is boosted. So, for example, if you've got four movements of a symphony with peak volumes of -7dB, -4dB, -5.5dB and -3dB , MAXV will take the loudest (-3dB), trim 0.5dB off of that for safety and apply a boost of 2.5dB to every file in turn, meaning you end up with files at -4.5dB, -1.5dB, -3dB and -0.5dB. The fourth movement thus becomes almost as loud as it can be without distortion, but the others are left at relatively equivalent volumes by comparison with it, though all four files will now sound louder by a significant degree.

So, that's MAXV. It works nicely and I've used it on my own music files for quite some time. Specifically, it was designed to boost the volume of rips from SACDs, which generally are deliberately mastered to have peak volumes around -6dB, but MAXV will happily boost the volume of any unnaturally quiet FLAC file, no matter whether it was generated from an ordinary CD, an SACD or simply downloaded as part of a digital music distribution.

The trouble with MAXV is that it only works on one folder of music at a time -though that was a deliberate decision on my part. Churning through a multi-Terabyte music collection and altering all the volumes in bulk just sounds like a dangerous -and, frankly, stupid- thing to do!

So, unless you physically CD to every folder in your digital music library, one at a time, and run MAXV by hand in every single one of them, you can't really tell how badly your collection as a whole might be in respect of sub-optimal volume levels.

And that's where MAXVRPRT comes in: it will visit every single folder in a music collection in turn and analyse the loudness levels of every FLAC it finds, without the need for any manual directory-changing at all. It will not, however, actually alter the volume of any FLAC it analyzes. It merely produces a report about the volume levels found and simply says what folders you could manually visit later on to boost the volume in the files stored there.

In short, MAXVRPRT alters nothing about your music collection, so is 100% safe to run. But it tells you where you could usefully run MAXV to actually change the volume levels of your music files.

I cannot emphasise enough that, by itself, MAXVRPRT changes nothing at all in any music file. You can run it, even if MAXV itself is not installed on your system. The only consequence of running it is a text report of what folders contain unusually quiet music.

2.0 Obtaining and Installing MAXV

Installing MAXV is a simple process of issuing the following commands:

wget https://absolutelybaching.com/abc_installer
bash abc_installer --maxvrprt

The first command downloads a generic installer script. The second command is an instruction to run that installer script, specifying (with a double-hyphen parameter) that it’s MAXVRPRT you want to install. You will be prompted at one point for your sudo password, without which the installer cannot install the software in the /usr/bin folder correctly.

2.1 First Run

Once installed, MAXVRPRT needs to be run (by typing maxvrprt at a terminal prompt) in a folder containing other folders which themselves (eventually) contain FLAC music files. It won’t work outside such a folder, nor will it work in a folder containing, say, MP3 or APE music files: only FLAC files need apply! If you run the program in a folder which does not contain any FLACs, or any other folders that themselves contain FLACs, you'll just get an error, like this one:

Here, I'm chosen to run the program in my Desktop folder: there are no FLACs there directly, nor are there any sub-folders that contain any, so the thing just says 'No such file or directory' and, essentially, errors out.

Assuming there are some FLACs present when first run, MAXVRPRT will begin by analysing your system to determine if necessary prerequisite software is present:

That’s an example from a system running Fedora -so, MAXVRPRT knows to prompt you to install missing packages with the ‘sudo dnf install’ command. On Ubuntu, it will tell you to use ‘sudo apt install’ and on OpenSuse, it will tell you to use ‘sudo zypper in’… and so on. It’s main-distro-aware, in other words, and will provide distro-appropriate prompts whenever it can.

Notice, too, in this specific example, that MAXVRPRT knows the ffmpeg package it needs can only be installed on Fedora if the RPM Fusion repository has been enabled. You can do that with these two commands:

sudo dnf install https://download1.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm
sudo dnf install https://download1.rpmfusion.org/nonfree/fedora/rpmfusion-nonfree-release-$(rpm -E %fedora).noarch.rpm

On OpenSuse, you will receive a similar extra message telling you to install the Packman repository (for the same sorts of reasons that Fedora needs the RPM Fusion one!). That’s done with the following one-liner:

sudo zypper ar -cfp 90 http://ftp.gwdg.de/pub/linux/misc/packman/suse/openSUSE_Leap_15.2/ packman

With that repository enabled, you can re-run MAXVRPRT and again see the ‘you are missing software’ warning -but the command to install it all will now be capable of completing successfully!

2.2 Subsequent Runs

If you have installed the prerequisite software and are running MAXVRPRT in a folder full of FLAC files, or a folder that is a parent to sub-folders that themselves contain FLACs,  you’ll see the program do its work something like this:

It isn't exactly pretty -and that's a deliberate design decision on my part! You can see in this screenshot that I've travelled to the root folder of my entire classical music folder, and have invoked the MAXVRPRT tool by it's full name. The program then immediately searches for FLACs within the folder structure it's launched from -and, if your music collection is large, that can take quite a long time of nothing apparently happening. Be patient, however, and you'll eventually see the program step through every folder containing FLACs in turn, as you see happening to my own music collection. The name of each folder being investigated is displayed as a form of progress meter. You may see the same folder name displayed more than once if it contains more than one FLAC file: in my case, for example, the "Piano Concerto (Bernstein - 1964)" folder is mentioned twice, because that piano concerto happens to consist of two independent FLAC files, representing each movement of that particular work.

Let the program complete its work and you'll see this message appear at the end of everything:

This time, I've run the program inside a very specific folder containing just a few sub-folders, so the list of folders being analysed is quite short. Nevertheless, at the end of the list of folders is a message that 'The results of this run are visible at...", and then a folder and file name are mentioned. The text at that point is actually a clickable link and, if you right-click on it, most Linux distros and their default file manager will let you select an 'Open Link' context menu option, which will cause the log file generated by MAXVRPRT to be opened in your default text editor. If you prefer doing things manually, it's just a question of yourself opening a $HOME/Logs/bulkmaxv.txt file in whatever your chosen text editor happens to be.

Note that if MAXVRPRT has not found any candidates for a volume boost, the text file mentioned will be blank. But if MAXVRPRT does detect possible volume boosts could be applied, here's what the text file will look like:

The first line of the report will mention the date the program performed its analysis and mention a 'threshold': I'll talk about that in a bit more detail shortly. It then lists all the files it's found which could benefit from a volume boost -and will mention the specific decibel boost it thinks could be achieved without distorting the music. Remember: these are possible volume boosts you yourself will have to apply with manual runs of MAXV later on. MAXVRPRT hasn't modified anything itself at this point: it's just reporting on things it finds suspiciously quiet and which you can go fix later on if you'd like to.

The report is ordered by possible volume boost, so the really significant boosts will be listed toward the bottom of the report; the lesser boosts will be at the top.

What you now do with this information is now entirely up to you: you can simply ignore it and forget about it! Or you can visit each mentioned folder in turn and there run the 'MAXV' utility (assuming you've installed it). MAXV will re-perform the volume analysis (but this time, on a specific folder of FLACs only, so it will be quite quick) and give you the option to boost the volume or not, as you so desire.

The actual business of boosting audio volumes is thus as tedious and manual (and careful and deliberate!) as it ever was... but at least you now know where to focus your efforts!

One word of warning: the program always obliterates the report it last ran when it is launched. You must not therefore run two instances of the program at the same time: the second instance will forever be over-writing the report that the first is attempting to generate, and vice versa.

3.0 The Volume Sensitivity Threshold

I mentioned in the previous section that the MAXVRPRT program's final report will mention in its top line something about 'with threshold x'. The fact is that few CDs will be mastered to have absolutely 0dB as their peak volume, so nearly all of them will be off by a decibel or two -and, frankly, at those sorts of loudness levels, you'd barely notice that the volume is not quite what it could be: potential volume boosts of 0.6dB are therefore hardly worth bothering with. Accordingly, you can tell MAXVRPRT to ignore any folders that could be volume-boosted by an amount less than 'some value': that's the threshold value the report mentions.

By default, MAXVRPRT will assume a threshold value of 5dB. Any potential volume boost smaller than that is simply left out of the final report. If you would prefer a smaller or bigger threshold value, though, you can specify it at run-time. Instead of running the program with the bare command maxvrprt, you can add a double-dashed parameter to the command, like so:

maxvrprt --threshold=11

If I'd run MAXRPRT with that threshold before, the final report would have looked like this:

You can see that this version of the report contains fewer lines than the previous one: three folders with possible volume boosts of less than 11dB have simply been omitted, though they were nevertheless checked.

Be aware that if you supply your own threshold, it must be an integer (so 4.5 would not be accepted) and it must be between 1 and 40. Any threshold not meeting these requirements is silently converted to the default threshold of 5. The first line of the eventual report will always tell you what threshold applied for any given run.