Muzik Faktry is a Bash shell script for processing music files
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
atom a8beabcff2 misc. updates 3 days ago
config misc. updates 3 days ago
license misc. updates 4 weeks ago
muzikfaktry.sh misc. updates 3 days ago
readme.md misc. updates 3 days ago
release_notes.txt misc. updates 3 days ago

readme.md


M U Z I K F A K T R Y by 12bytes.org

CONTENTS

  1. INTRODUCTION
  2. DEPENDENCIES
  3. INSTALLATION
  4. CONFIGURATION
  5. USAGE
    • Miscellaneous
    • Tasks
    • Error Levels
    • Tagging Operations
    • Spectrograms
    • Duplicates & Hashes
    • Repairing Files
  6. COMMAND LINE OPTIONS
  7. HISTORY

INTRODUCTION

Muzik Faktry is a user-friendly, menu driven, Bash shell script for various Linux based operating systems. The script is primarily intended for working with lossless music files and transcoding them to the FLAC format and/or performing various operations and integrity checks on them before adding them to your collection. Producing clean, compact, error free FLAC files is the primary goal of the script. All of the tasks performed by Muzik Faktry are non-destructive (lossless), meaning there is no reduction in the quality of the audio.

The audience for Muzik Faktry might range from the audiophile to the casual listener. In either case the script is designed to be easy to use while still providing the user with a plethora of options.

Muzik Faktry is nearing the final stages of development, however there are very likely bugs that still need to be squashed. If you find any please report them on the Muzik Faktry (https://codeberg.org/12bytes.org/muzikfaktry) code repository or leave a comment on the Muzik Faktry web page (https://12bytes.org/projects/muzik-faktry/).

For additional information see:

DEPENDENCIES

Several dependencies required by Muzik Faktry are already installed with most mainstream Linux-based desktops. The script will notify you of any missing dependencies. Dependencies which may not be installed include:

While optional, shellcheck is highly recommended since it is use to check the syntax of the active configuration file.

If a package is not available in your package manager you may drop precompiled executables in the /bin folder and Muzik Faktry will automatically use them. Make sure the files are executable: $ chmod +x file

INSTALLATION

ZIP archive: https://codeberg.org/12bytes.org/muzikfaktry/archive/main.zip TAR.GZ archive: https://codeberg.org/12bytes.org/muzikfaktry/archive/main.tar.gz

Unpack the archive somewhere where you have read, write and execute permissions, perhaps in your /home directory, and make sure the script is executable: $ chmod +x muzikfaktry.sh

CONFIGURATION

The default configuration file is /config/default.conf. If you wish to make any changes to the configuration then make a copy of the file, giving it a new and descriptive name, and edit the copy. Upon running the script you will be asked to choose a configuration file to load if there is more than one.

It is of particular importance to understand that, although the contents of default.conf closely resembles an INI file (option=value), the configuration file is effectively part of the main script and therefore proper Bash syntax is critical. It is for this reason that the installation of the shellcheck package is strongly suggested. Most anything you want to know about the configuration options should be contained in the file.

USAGE

Miscellaneous

IT IS STRONGLY SUGGESTED TO WORK ON COPIES OF YOUR SOURCE FILES. Muzik Faktry does not backup source files which it modifies. For example, when a compressed file is decompressed, the source file is permanently deleted.

The only file format that Muzik Faktry encodes to is FLAC, however the Decompress task is able to handle many lossless file formats to get you going.

Other than the ability to read metadata for a wide variety of formats there is no support for the MP3 format.

During the course of operations your input will be solicited, often in the form of a question. A typical reply for a yes or no type question might require a "Y" or "N" key press (lower case). Appended to the end of such a question will be "[Y/n]" or "[y/N]" where the default choice is indicated by the upper case letter. To select the default choice you may press the corresponding key (lower case), or the Enter/Return key, or most any other key.

Files which are discarded, either by the user or automatically when a task is run in batch mode, are moved to the /discard folder.

To begin a session, copy (not move!) your source files to the /working directory, then open a terminal and cd to the /muzikfaktry directory and run the script: $ ./muzikfaktry.sh

Personally i like to open my file manager to the /working directory and move it to one side of my screen, then open a terminal and move it to the other side. This allows me to watch what's happening in the /working directory as files are processed.

Tasks

Tasks should generally be run in order for each task that is necessary. A typical scenario might be where you start with FLAC tracks or an album file and a CUE sheet in which case you might want to consider the following tasks:

  1. Split An Album (if necessary)
  2. Tags To File Name (if necessary)
  3. Tags To Text (if you wish to reuse the original metadata)
  4. Format File Names (if necessary)
  5. Decompress (required to take full advantage of the Integrity Check task)
  6. Integrity Check
  7. Spectrogram (suggested unless you know the source files are of good quality)
  8. Trim Silence (if necessary)
  9. Encode (to FLAC)
  10. Text To Tags -or- File Name To Tags (if necessary)
  11. Write Tags (if necessary)
  12. Tags To Text (if you wish to reuse the modified metadata)
  13. Normalize Gain (recommended)
  14. Optimize
  15. Metadata Check
  16. Duplicates & Hashes (recommended)

Each time a task is run you will be asked if you want to batch process all files in the /working directory. If you are new to Muzik Faktry it is suggested to avoid batch processing until you become familiar with how it operates.

It is suggested to work with one file type at a time to avoid confusion.

Decompressing compressed files will result in the loss of all metadata such as artist, title, album art, etc.. Text metadata can be saved by running the Tags To Text task prior to decompression, then writing back the tags using the the Text To Tags task after encoding the file. If some or all of the metadata you require is contained in the file name (artist, title, etc.), perhaps after running the Tag To File Name and Format File Names tasks, it can be written back later using the File Name To Tag task.

When splitting an album, only one album file at a time may be processed.

If the source file is known to be a good FLAC file and you just want to change something such as the compression ratio, the Encode task will non-destructively re-encode the file using the settings defined in the configuration file.

The Normalize Gain task uses metaflac (a component of the FLAC package) to write ReplayGain information to the files. This is non-destructive and can be undone using the Strip Metadata task.

The Integrity Check and Metadata Check tasks are largely responsible for flagging files as "PASSED", which are good files, "MARGINAL", which are repairable, or "FAILED", which probably cannot be repaired. The Metadata Check task is the same as the Integrity Check task with extra metadata tests appended to it. Other than the Duplicates & Hashes task, the Metadata Check task is the final task that should be run before adding the files to your collection.

Error Levels

Tasks can report 4 different error levels when a problem is detected with a file. Depending on the severity of the error the file names may be prefixed with one or more error tags in order to provide a visual indication of the error type and what needs to be done to repair the problem.

  1. "ERROR" level errors generally indicate that the file was not able to be processed by an executable. This likely due to a damaged file, however a missing dependency or specifying incorrect options for an executable in the configuration file could also cause this error. These files are automatically discarded if the task is run in batch mode and the file name will be prefixed with "[ERR]".

  2. "WARNING" level errors generally indicate that the file failed a test based on the criteria specified in the configuration file or that which is hard-coded in the script. These files are automatically discarded if the task is being run in batch mode and the file name will be prefixed with "[WRN]".

  3. "NOTICE" level errors indicate problems which are repairable using another task. Such files may have too much or too little metadata, header issues, a problematic file name, etc.. These files are never automatically discarded. The file name will be prefixed with "[NTC]" if the error is of a general type, or "[TAG]" if the error is metadata related, such as a missing artist or title tag.

  4. "INFO" level errors are informational only and not indicative of a problem.

A file which produced no errors but is discarded by the user will have a "[USR]" prefix added to the file name.

File name error tags are automatically removed if the problem is repaired and the file then passes the Metadata Check task.

Tagging Operations

Tags can be read from many file formats but may only be written to FLAC files. Tags that can be written are limited the the Vorbis I format specification (see: https://xiph.org/vorbis/doc/v-comment.html).

Most tagging tasks should be self-explanatory with the possible exception of the Tags To Text and Text To Tags tasks. The Tags To Text task will attempt to read the values for each tag specified in the configuration file for all files in the /working directory and write this information to text files in the /metadata directory, each file having the same name as the base file name of music file (the extension is ignored). These files are overwritten each time the task is run with the same files. This information can then be used to write metadata to files having the same base file name using the Text To Tags task. One possible use for this is to transfer metadata across different file formats, such as when upgrading from the MP3 to the FLAC format.

Spectrograms

The purpose of the Spectrogram task is to create a visual representation of the audio frequency spectrum which can be used to help determine whether the audio is actually lossless or whether it was up-scaled/up-sampled from a lossy format, such as when an MP3 is transcoded to FLAC. More information is available on the web, including on the Muzik Faktry page at https://12bytes.org/projects/muzik-faktry/.

Spectrogram are stored as PNG image files in the /spectro directory if the Spectrogram task in run batch mode. The file names will be the same as the audio file with an added PNG extension. If batch mode is not active then each image is opened for previewing as it is generated and no image files are written to disk and, additionally, you may view a video spectrogram of the file.

Duplicates & Hashes

The Duplicates & Hashes task performs different operations depending on the selected mode. This task is always run in batch mode. Regardless of the operating modes, any newly found file will have its name and CRC hash added to the checksums.txt file. If the file will be altered then a copy of checksums.txt named checksums.txt.bak is made overwriting the last backup. Beyond that the operating modes perform as follows:

  • Verify CRC: Verifies CRC hashes to find any files which have been unintentionally altered in any way, such as by "bit rot" (see: https://en.wikipedia.org/wiki/Data_degradation), unintentional changes to the metadata, etc.. Files which fail CRC hash verification will have their file names added to the discarded.txt file.

  • Update CRC: Updates any file hashes in the checksums.txt file which have changed. This mode is useful if the files have been intentionally altered, such as a change to the metadata.

  • Find Duplicates: 1) Find potential duplicate using fuzzy file name matching. File names are stripped to a minimum in order to eliminate any potentially unimportant information including numbers, dots, hyphens, spaces and bracket pairs. 2) Compare file sizes to find any exact size matches. 3) Compare CRC hashes to find any bit-identical files.

Repairing Files

If a file requires repairing it may be best to locate another copy. Problems such as low sample or bit rates, poor encoding methods, damaged audio or poor sound quality cannot be repaired by Muzik Faktry, nor any other software i am aware of, regardless of their claims. That said, there are certain issues that can be resolved, such as missing, damaged or incorrect metadata, certain header issues, etc.. Files which report an "ERROR" level error are likely not be repairable.

When repairing a file it will first be decompressed to WAV format if it wasn't already. Choose only the necessary repair task(s) based upon the error messages that resulted from a prior Integrity Check task since subjecting the file to a repair task which is not fitting of the problem may damage the file further.

Repairing WAVE Extensible format files (0xfffe) will result in a broken file that cannot be decoded if a non-canonical header is detected and therefore the canonical header check is automatically disabled for this format. This issue is resolved if the file is transcoded to the FLAC format.

Though not used by Muzik Faktry, you may find the wavfix tool helpful for repairing issues with WAV files if you don't intend to encode them to FLAC or if FLAC encoding fails (see: https://github.com/agfline/wavfix).

COMMAND LINE OPTIONS

Run Muzik Faktry with '-h' to see all available options: $ ./muzikfaktry.sh -h

HISTORY

As i started listening to music on a PC, a mistake i still enjoy making, i became more attuned to the audio quality and the metadata that was included with the files. At the time i was using that other OS (Windoze) and listening to MP3's and so i started building a tool chain for processing my music which checked for errors, added ReplayGain information, etc.. I was happy with the process i created but then i moved to Linux and wanted to recreate my tool chain the best i could, thus MP3 Factory was born which was the original name of this script. Eventually i figured out that the MP3 format is shit for several reasons and so i started focusing more on producing lossless files in the FLAC format which led to the re-branding of the script. Eventually i dropped virtually all support for the MP3 format other than saving some metadata information.

Muzik Faktry has since evolved into a fairly comprehensive tool that greatly exceeded both my original expectations and the vastly inferior tool chain i constructed on Winblows, plus it's been a great project for learning the many intricacies of Bash shell scripting. Whether Bash is an appropriate language to code such a script is certainly debatable, however i coded it for my own usage and it does the job very nicely.