REDOFLACS(1)

okay bestie, welcome to REDOFLACS(1) — that’s the one from the General Commands Manual — and this is where FLAC library management gets the group-chat treatment it deserves. 💅✨

💖 NAME 💖

redoflacs — a Parallel BASH commandline FLAC compressor, verifier, organizer, analyzer, and retagger. That’s the whole flex.

🦋 SYNOPSIS 🦋

redoflacs [operations] [options] [target] ...

That’s the shape of it: operations, options, targets, go.

🌸 DESCRIPTION 🌸

redoflacs is a BASH commandline program that gives you a whole series of operations to help manage and verify your FLAC music library. One of its key features is that it can process a great number of FLAC files in parallel, using as many jobs as possible to complete an operation — very similar to GNU make. Iconic behavior, honestly.

When run as a user, redoflacs searches for a config file in:

~/.config/redoflacs/config

When run as root, it searches in:

/etc/redoflacs.conf

If no config file is found in either place, one gets created. No cap.

More info lives at <https://github.com/sirjaren/redoflacs>.

🔥 OPERATIONS 🔥

• -c, --compress — Compress the FLAC files with the user-specified level of compression defined in the config file as compression_level, then verify the resultant files.

The default is 8, and the range goes from 1 to 8, with the smallest compression at 1 and the highest at 8. This option adds a tag (VORBIS_COMMENT) to all successfully verified FLAC files. Here’s the default COMPRESSION tag added to each successfully compressed (and verified) FLAC file:

COMPRESSION=8

If any FLAC files already have the defined compression_level tag — a good indicator that the files are already compressed at that level — the script will instead test those FLAC files for any errors. This is useful for checking your entire music library to make sure all the FLAC files are compressed at the specified level and that they’re intact, i.e. not corrupt.

If any files are found to be corrupt, this script will quit upon finishing the compression of any other files and produce an error log. 😭

NOTE: If this operation is called with -x, --no-extra-tags, the above logic changes. Instead of checking the COMPRESSION tag before continuing, each FLAC file is ALWAYS compressed with the configured compression level. After successful compression, the COMPRESSION tag is NOT applied to the FLAC file.

• -C, --compress-notest — Same as the -c, --compress option, but if any FLAC files already have the defined compression_level tag, the script will skip the file and continue to the next one without testing the FLAC file’s integrity. Useful for checking if all your FLAC files are compressed at the level specified.

NOTE: This operation is NOT compatible with the -x, --no-extra-tags option. This option invalidates the usefulness of this operation, since each FLAC file that is missing the COMPRESSION tag would be compressed, after which the COMPRESSION tag would NOT be applied, leaving future executions of this operation to repeat this process. 🫠

• -t, --test — Same as -c, --compress, but instead of compressing the FLAC files, this script just verifies their integrity. This option will NOT add the COMPRESSION tag to the files.

As with the -c, --compress option, this will produce an error log if any FLAC files are found to be corrupt.

• -a, --aucdtect — Use the auCDtect program by Oleg Berngardt and Alexander Djourik to analyze FLAC files and check, with fairly accurate precision, whether the FLAC files are lossy sourced or not. For example, an MP3 file converted to FLAC is no longer lossless, therefore it’s lossy sourced. The audacity of some files, fr.

While this program isn’t foolproof, it gives you a good idea which FLAC files will need further investigation — i.e. a spectrogram. This program does not work on FLAC files which have a bit depth of more than a typical audio CD (16bit), and will skip the files that have a higher bit depth.

If any files are found to not be perfect — i.e. 100% CDDA via auCDtect — a log will be created with the questionable FLAC files recorded in it.

• -A, --aucdtect-spectrogram — Same as -a, --aucdtect, with the addition of creating a spectrogram for each FLAC file that fails auCDtect. That is, any FLAC file that does not return 100% CDDA from auCDtect will be scanned and a spectrogram will be created.

Any FLAC file skipped (due to having a higher bit depth than 16) will NOT have a spectrogram created.

By default, each spectrogram will be created in the same folder as the tested FLAC file name, as follows:

<filename>__<processed number>__.png

An example of this:

03 - Some FLAC File.flac      # 7th file processed
03 - Some FLAC File__7__.png  # Spectrogram

The user can change the location of where to store the created spectrogram images by changing the value of spectrogram_location defined in the configuration file. The location defined by the user will be tested to see if it exists before starting the script. If the location does NOT exist, the script will warn the user and exit.

The created PNG file is large in resolution to best capture the FLAC file’s waveform (~1800x513).

The spectrogram is created using the program SoX. If the user tries to use this option without having SoX installed, the script will warn the user that SoX is missing and exit. Missing SoX is a vibe check fail, honestly.

• -m, --md5check — Check FLAC files for unset MD5 Signatures, logging any files that have this value unset. An unset MD5 signature doesn’t necessarily mean a FLAC file is corrupt, and MAY be repaired with a re-encoding of said FLAC file.
• -e, --extract-artwork — Run through each FLAC file and extract any and all artwork that’s embedded within the PICTURE block. This is useful in the event a user wants to save any artwork before using the -p, --prune option to remove the artwork.

By default, each extracted image will be placed in a subdirectory where the FLAC file is located. The subdirectory housing the extracted artwork will have a similar name as the currently processed FLAC. If a directory already exists, an integer is appended to the directory (to prevent overwriting and mixing files). For example:

/path/to/01_file.flac          # FLAC file with embedded artwork
/path/to/01_file.flac_art/     # Directory housing artwork
/path/to/01_file.flac_art~1~/  # Directory '1' if above directory
exists
/path/to/01_file.flac_art~2~/  # Directory '2' if above directory
exists
/path/to/01_file.flac_art~N~/  # Directory 'N' if above directory
exists

The user can change the location of where to store the extracted images by changing the value of artwork_location defined in the configuration file. The location defined by the user will be tested to see if it exists before starting the script. If the location does not exist, the script will warn the user and exit.

This operation supports all the various types of embedded artwork that metaflac supports.

If there is more than one image of the same type, this operation will append an integer after the image filename to prevent clobbering:

/path/to/01_file.flac_art~2~/                    # Directory housing
art
/path/to/01_file.flac_art~2~/11_Composer.jpg     # Extracted image
/path/to/01_file.flac_art~2~/11_Composer.jpg~1~  # Another image '1'
/path/to/01_file.flac_art~2~/11_Composer.jpg~2~  # Another image '2'
/path/to/01_file.flac_art~2~/11_Composer.jpg~N~  # Another image 'N'

• -p, --prune — Delete every METADATA block in each FLAC file except the STREAMINFO and VORBIS_COMMENT block. If remove_artwork is set to any values but true (via the configuration file), then the PICTURE block will NOT be removed.
• -g, --replaygain — Add ReplayGain values to FLAC files. ReplayGain is calculated for ALBUM and TRACK values and applied via VORBIS_COMMENTS, and as such, will require the -r, --retag option to have these tags kept (see values. The tags added are:

REPLAYGAIN_REFERENCE_LOUDNESS
REPLAYGAIN_TRACK_GAIN
REPLAYGAIN_TRACK_PEAK
REPLAYGAIN_ALBUM_GAIN
REPLAYGAIN_ALBUM_PEAK

NOTE: This option ignores any ReplayGain tags that may already be set, removing existing values before applying new ones.

In order for ReplayGain values to be applied correctly, the script has to determine which FLAC files to add values to by looking at the directory housing said files. That is, the script must add ReplayGain values by working off the FLAC files’ parent directory. If there are some FLAC files found, the script will move up one directory and begin applying ReplayGain values. This is necessary in order to get the REPLAYGAIN_ALBUM_GAIN and REPLAYGAIN_ALBUM_PEAK values set correctly. Without doing this, the ALBUM and TRACK values would be identical.

If a user has many FLAC files under one directory (of different albums/artists), the ReplayGain ALBUM values are going to be incorrect, as the script will perceive all those FLAC files to essentially be from the same album. This is mitigated by having each album in a separate directory. Keep in mind, multi-disc albums must be in separate directories in order to be processed with different ALBUM GAIN and ALBUM PEAK values.

If there are any errors found while generating and/or applying ReplayGain values, an error log will be produced.

• -G, --replaygain-noforce — Same as -g, --replaygain, but will check for existing ReplayGain tags BEFORE re-applying new ones. If any one of the five ReplayGain tags (mentioned above) are missing from any FLAC file, the script will apply new values to each FLAC file in that directory (first removing the old ReplayGain tags, if any).

If all five ReplayGain tags are intact in every FLAC file (in a given directory), that directory will be skipped and no new ReplayGain tags will be added.

• -r, --retag — bestie this one is the glow-up 💅 it extracts the configured tags from each FLAC file and clears the rest before retagging. So like, everything you didn't ask for? Gone. Iconic. The default tags kept are:

TITLE
ARTIST
ALBUM
DISCNUMBER
DATE
TRACKNUMBER
TRACKTOTAL
GENRE
COMPRESSION
RELEASETYPE
SOURCE
MASTERING
REPLAYGAIN_REFERENCE_LOUDNESS
REPLAYGAIN_TRACK_GAIN
REPLAYGAIN_TRACK_PEAK
REPLAYGAIN_ALBUM_GAIN
REPLAYGAIN_ALBUM_PEAK

The characters allowed in a tag field are ASCII only (including the Space character). The EQUAL sign (=), is not allowed as this is the delimiter separating tag field and tag value. No cap, that's just the rules 🫶

See this link for more details (under 'Content vector format'):

<http://xiph.org/vorbis/doc/v-comment.html>

If any FLAC files have missing tags (from those configured to be kept), the file and the missing tag will be recorded in a log. Very "noted, bestie" of it 📝

The tags that can be kept are essentially infinite, as long as the tags to be kept are set in the TAGGING SECTION of the configuration file. Literally infinite. Slay.

If this option is specified, a warning will appear upon script execution. This warning will show which of the configured TAG fields to keep when re-tagging the FLAC files. A countdown will appear giving the user 10 seconds to abort the script. Ten whole seconds to change your mind — use them wisely ⏳😭

• -l, --all — this option is short for, like, the whole squad:

-c, --compress
-m, --md5check
-p, --prune
-g, --replaygain
-r, --retag

• -L, --reallyall — okay so --all said "that's everyone" and this one said "hold my boba" 🧋 it's short for:

-c, --compress
-m, --md5check
-p, --prune
-g, --replaygain
-r, --retag
-e, --extract-artwork
-A, --aucdtect-spectrogram

---

✨ OPTIONS ✨

• -j[N], --jobs[=N] — set the number of parallel jobs to run on script invocation. If this is not set, this script will attempt to find the number of CPU cores available, using the number found as the number of parallel jobs to run. It's giving "multitasking queen" 👑

If the script is unable to find the number of CPU cores available, the number of jobs will be set to two (2), by default. Two. A humble little duo 🎀

• -n, --no-color — turn off color output. Sad beige terminal vibes, but okay 🥲
• -x, --no-extra-tags — disable the application of extra tags. Presently, the only tag that's applied by default is the COMPRESSION tag during compression via the

(yes the sentence just ends there in the original, I don't make the rules 😭💀)

This option has the effect of invalidating the -C, --compress-notest operation, making the invocation of these two arguments together incompatible. See the -c, --compress and -C, --compress-notest operations for more information on how this option affects these operations. So don't run them together, bestie — they do NOT get along 🙅‍♀️

This option has no bearing on the -r, --retag operation. All FLAC tags defined in the configuration file are for use with the the -x, --no-extra-tags option. (double "the the" is canon, don't @ me)

• -o, --new-config — force the creation of a new configuration file. This option does NOT overwrite any existing configuration file. Read that again. It does not. Touch grass, keep your old config safe 🌸
• -v, --version — display script version and exit. Short and sweet, a little mic drop 🎤
• -h, --help — shows this help message. The classic. The blueprint. The mother of all flags 👑

---

📁 FILES 📁

• ~/.config/redoflacs/config — user configuration file. Your personal little corner of the internet 🏡
• /etc/redoflacs.conf — system configuration file. The communal one, shared with everyone 🫶

---

🐛 BUGS 🐛

If you find a bug, please report it at:

<https://github.com/sirjaren/redoflacs/issues/new>

Not me begging you to file an issue — but like, please do, it's how things get fixed 💖

---

👑 AUTHOR 👑

Jaren Stangret <sirjaren@gmail.com> — the main character, lowkey 🫡

---

🌈 THANKS 🌈

Thanks to all the people whom have provided feedback and support! Genuinely, every single one of you ate 💅✨

---

⭐ REVISION ⭐

6. Six. Lucky number, no notes 🔥

---

and that's the whole page, bestie — REDOFLACS(1), revision 6, brought to you by the one and only redoflacs manual. go compress something gorgeous 💖🎀🦋