MP3 Factory: 'De-borking' MP3s on Linux

Tux with headphones

Note that MP3 Factory is under development and documentation is not complete. Use at your own risk. Lastly, the options set in the configuration file may not be set to their default values.


Yes, "de-borking" is a word you grammar Nazi! It's right here in the dictionary :)

Apparently i'm an oddball because my MP3s usually contain only the artist, title and genre tags (and i only use 3 or 4 of the latter), along with the other required stuff and nothing else, except for the actual audio of course. I'm not interested in embedding cover art, lyrics, soupie recipes or whatever else people are sticking in their music these days. I like to aim for minimal, compact, error-free files that meet my (medium-high) quality standard and that's what this is all about. If you're a super serious audiophile that spends days deciding which DAC will provide the truest sound (check out this one), this might not be for you, but if you just like to listen to good sounding music while you do whatever it is you do, read on.

In an ideal world of unlimited availability and smartphones with unlimited storage one may never mess with MP3s, preferring instead one of the lossless formats such as FLAC, however some songs are difficult or impossible to find in such a format and storage space is still pretty limited on our fondleslabs, so making efficient use of that space still seems like a good idea. Also the MP3 format generally provides a transparent listening experience as long as the encoding was performed with quality in mind, transparent meaning that it is unlikely that anyone with good hearing, in a quiet environment, with good equipment, would be able to differentiate between a high quality MP3 and the original lossless recording.

Typically i acquire specific songs from various artists rather than entire albums because i've never run across an album for which i liked every song. The problem with this disjointed approach is that downloading songs willy-nilly usually results in problems regarding tags, header errors, too much silence, nonuniform volume, etc.. Most maddening is when some aspiring government employee thinks that upsampling a 64 kbit/s MP3 to 320 kbit/s is somehow a good idea. With the exception of the latter, such problems are generally easy to fix using a few software tools.

Enter MP3 Factory, a Bash shell script which is essentially a wrapper that handles various tools and does so without relying on crap i don't like relying on, such as Java, Wine and Mono.

MP3 Factory, or MP3F if you rather, is intended primarily for transcoding (converting) downloaded music files to MP3s and/or performing various operations on them before adding them to your collection. Several of the functions that MP3F is capable of are applicable to formats other than MP3 however. With the exception of transcoding non-MP3's to MP3, all of the tasks which it performs are lossless, meaning that there is no loss of sound quality.

MP3 Factory is not a complete solution for processing music files. For example only rudimentary tagging functions are available (for greater tagging flexibility you might consider a good graphical program like puddletag), nor is it a complete replacement for comprehensive MP3 analysis and repair software like the venerable MP3 Diags which can address certain issues with MP3 files that MP3 Factory cannot.

MP3 Factory was developed and tested on Manjaro Linux or, as i like to call it, 'Arch for dummies'. The script should run on any flavor of Linux that includes a Bash compatible shell and for which the dependent packages are available.


  • Batch processing
  • Convert to MP3
  • Convert tags to file names and file names to tags
  • Repair and optimize files
  • Integrity checking, including LAME CRC testing
  • Generate frequency spectrographs for graphic analysis
  • Trim excess silence interactively
  • Normalize gain (volume) with ReplayGain 2.0 data
  • Process files other than MP3
  • Play a video of a music file
  • Output clean, error-free, compact MP3 files
  • Create multiple configuration files
  • The code is ShellCheck and Shellharden compliant, however that certainly doesn't mean it's bullet-proof so if you find a bug, let me know.


The MP3 Factory script runs in a terminal, but don't let that scare you half to death if you're not a terminal freak... get it? There are plenty of prompts to guide you along and it presents a unified interface for running several software tools which are available for Linux-based operating systems (because they suck slightly less than Windoze).

Music files can be batch processed and automatically retained or discarded according to parameters you define, or the operation can be interrupted after each file is processed so you can decide whether a file is worth keeping.

Following are the primary functions offered by MP3F:

1) Tag To File Name     8) Write A Tag        15) Repairs (!)
2) Integrity Check 1    9) Auto-Tag           16) Add Log Entry
3) Spectral Analysis   10) Optimize           17) View Log
4) Clean File Name     11) Integrity Check 2  18) Edit Config
5) Convert To MP3      12) Play Audio File    19) Load Config
6) Clean Metadata      13) Collection Stats   20) Documentation
7) File Name To Tag    14) Trim Silence (!)   21) Quit
  1. Tag To File Name : Rename a file using ID3 metadata (tags).
  2. Integrity Check 1: Run various Integrity Checks on the files and discard those which do not pass.
  3. Spectral Analysis : Create a spectrograph image of the file to check for various issues.
  4. Clean File Name : Removes unwanted characters from file names.
  5. Convert To MP3 : Convert a non-MP3 to an MP3.
  6. Clean Metadata : By default this task removes all obsolete and ID3 metadata and then writes back only the requested ID3 metadata in the desired format.
  7. File Name To Tag : Write ID3 tags derived from the file name, such as artist and song title.
  8. Write A Tag : Write user defined ID3 tags to the file.
  9. Auto-Tag : Writes multiple, predefined ID3 tags to the file.
  10. Optimize : By default this task reverses changes made by mp3gain when possible, writes ReplayGain tags and removes all ID3 padding in order to minimize the file size. ReplayGain information is written using loudgain, a byproduct of which is the removal of all ID3v1, ID3v1.1, ID3v2.2 and APEv2 tags.
  11. Integrity Check 2 : This second Integrity Check performs all of the tests the first one does, plus additional metadata checks.
  12. Play Audio File : Play a music file using a choice of players.
  13. Collection Statistics : Provides various quality and conformity statistics for all files in a folder.
  14. Trim Silence (!) : Remove excess silence from the beginning and end of the file. See the 'trim silence' section below for important notes regarding this task.
  15. Repair (!) : Repair a damaged file (damaged audio frames cannot be repaired). See the 'repair' section below for important notes regarding this task.
  16. Add Log Entry : Add a user defined comment to the session.log file.
  17. View Log : View the current log file.
  18. Edit Config 1 : Edit the script options in the default.conf file.
  19. Load Config : Load a different configuration file.
  20. Documentation : View various included and on-line manuals and documentation.
  21. Quit : Perform housekeeping and exit.


(1) Be extra careful to not mess up the syntax when editing the configuration file(s). Not even kidding. These files are sourced from the main Bash script and thus are essentially a part thereof.


Prior to using MP3 Factory you should check that its dependencies are available for your distribution. The script will notify you of any which are missing.

Primary dependencies...

  • python-eyed3 : A "tool for working with audio files, specifically MP3 files containing ID3 metadata (i.e. song info)."
  • apetag : A utility for reading and writing APEv2 tags, used only to remove APE tags.
  • exiftool : "... a platform-independent Perl library plus a command-line application for reading, writing and editing meta information in a wide variety of files." exiftool is used by MP3F only to read metadata since it cannot write to the MP3 format.
  • eyeD3 : "... a Python tool for working with audio files, specifically mp3 files containing ID3 metadata"
  • ffmpeg : "A complete, cross-platform solution to record, convert and stream audio and video."
  • flac : For processing FLAC files.
  • loudgain : "A versatile ReplayGain 2.0 loudness normalizer".
  • mp3gain : "Analyzes and losslessly adjusts mp3 files to a specified target volume". mp3gain is used primarily to un-do the damage it caused to a file, though this is not always possible.
  • mp3guessenc : "A small utility for analysis of audio mpeg files and detection of the encoder used".
  • mp3info : Used to obtain various information about an MP3.
  • mp3splt : A "utility to split mp3, ogg vorbis and native FLAC files selecting a begin and an end time position, without decoding". mp3splt (yes, that's how it's spelled) is used to trim excess silence from an MP3 or FLAC file.
  • mp3val : A "tool for checking MPEG audio files' integrity".
  • rmlyrics3 : "A Lyrics3 tag remover for MP3 files".

Optional dependencies...

  • notify-send : Provided by the libnotify package, it is used to send desktop notifications to notify you when a batch process has completed.
  • shellcheck : "Finds bugs in your shell scripts". It is strongly suggested to install this package so that the configuration files for MP3 Factory can be checked.

After downloading the MP3 Factory archive, extract it somewhere where you have read, write and execute permissions, such as in your home directory. The script will be contained in a folder named 'mp3actory'. I know you never anticipated such stunning creativity, but there it is! Don't forget to make sure it's executable ( $ chmod +x ).

MP3 Factory will create the following directories and files within the 'MP3 Factory' folder:

/.temp    (holds a copy of each file being processed)
/backup   (copies of source files converted to MP3)
/config   (configuration files)
/holding  (for holding files you want to process)
/junk     (discarded files)
/logs     (take a guess)
/spectro  (spectrograph images of music files)
/working  (files which are to be processed)
junk.txt  (file names of discarded files)

Other files included in the archive are:

help.txt       (internal help file)
license.txt    (GPL license)  (MP3 Factory shell script)

The first thing you'll want to do is edit the configuration options in the /config/default.conf file using a capable code editor. Better yet, make a copy of it and edit the copy (give the copy a descriptive name and a .conf extension). If you're running the KDE desktop then Kate is a nice choice for a code editor, just don't use something like LibreOffice Writer or whatever. If your editor supports syntax highlighting, set it to 'bash' or 'ini' to help avoid errors. Carefully review each option and their descriptions and make the necessary changes. Be careful to not make any syntax errors.

If you need help with the options for a dependency program, such as for ffmpeg, try one of the following in your terminal. Note that the name of the program is typically case sensitive and usually all lower case, eyeD3 being the red-headed stepchild of the lot.

man <program name>
<program name> --help
<program name -h


You can create multiple configuration files in the /config folder in which case MP3F will ask which one you want to load when you run the script. The suggested way to do this is to copy the default.conf file to a new file and edit the new file. Be sure to give it a descriptive name and a '.conf' extension.

There are 3 types of option/value pairs in the configuration file and in all cases there can be no space between the option name, the equals character, and the value, and all 3 must be present. Do not alter any of the option names. Following are some examples of properly and poorly formatted options:

Good : optionName='value'
Bad  : optionName="value"
Bad  : optionName = 'value'
Bad  : optionName'value'
Bad  : optionName=

The types of options in the file are strings, integers and arrays. For a string the entire value must be surrounded by single quotes:

Good : stringName='some string'
Bad  : stringName=some string

For an integer the value must be a whole number and must not be quoted:

Good : integerName=1
Bad  : integerName=1.2
Bad  : integerName='1'

Arrays must be enclosed in parenthesis and each element must be enclosed in
single quotes and separated with a space (there may exceptions where some
values may be double quoted):

Good : arrayName=( 'value1' 'value2' '...' )
Bad  : arrayName=('value1''value2''...')
Bad  : arrayName='value1' 'value2' '...'

All lines beginning with a ' # ' character are comments and are ignored by the
shell. You may add, edit or remove comments, however do not remove or alter the " # default value: ... " lines as they are used to reset all the values if you run with the -r option.

You should install ShellCheck to let MP3 Factory check the configuration file each time the script is run, as well as after editing it or loading a different one, provided you do so from the Main Menu. If you don't want to install ShellCheck for some reason then you can test the configuration file on-line at (you can ignore all the "... appears unused ..." warnings).


Run the script by opening a terminal, navigating to the 'mp3factory' folder, and running ./ . The script will run some checks to make sure its dependencies are met, etc., and then create some folders after which it's ready to use. No operations will be performed on your files without your explicit input and all important operations are logged for later reference.

During the course of running tasks you will be asked questions and given choices such as, for example, 'Do you want to do this? [Y/n]'. The default choice is indicated by the upper case letter and can be selected either by pressing the letter, 'y' for 'yes' in this instance, or 'Enter'/'Return', or any other key except 'n'.

If something goes haywire and the script crashes, or you forcefully terminate it by pressing Ctrl+C, and you were working on a file when the problem occurred, the file will be named 'working.*' should you want to recover it.

When processing your files you can process one at a time, pausing before moving on to the next, or you can batch process all of them. Batch processing is activated when you disable pausing when starting a task. If you are new to MP3 Factory it is recommended to avoid batch processing until you become familiar with how the script operates given your configuration. When files are batch processed they will be automatically retained or discarded based on these options, whereas when batch processing is not active you may override the automatic handling of the files. Discarded files are moved to the /junk folder by default and their names are written to the junk.txt file should you want to locate better copies.

You can work on multiple file types all at once, however only the file types which are compatible with the chosen task will be processed. If you're new to MP3F, and perhaps even if you aren't, you may find it easier to work on only one file type at a time.

While the order of the tasks in the MP3 Factory main menu may seem odd, there are logical reasons for it. When performing multiple tasks they should generally be performed in order, though there are exceptions. For example, one probably wouldn't want to rebuild a music file without a proper file name before writing a correct file name based on the metadata that will be forever lost when performing a Rebuild task (assuming the default settings). Similarly, it's probably pointless to invoke most tasks following the first Integrity Check task before an Integrity Check is performed.

Using the Tag To File Name task as a final example, it is first in line for good reason. Let us assume the file name '01 - Only Time.mp3'; if you first create a spectrograph image of the audio, '01 - Only Time.mp3.png', and later write a proper file name from the metadata, 'Enya - Only Time.mp3', the base file name in the /spectro directory wouldn't match that of the music file in the /output directory, thus making it more difficult than necessary to later associate the two files. Conversely, tasks from number 12 on can be performed at any time, in any order, and either of the Integrity Check tasks can be performed at any time as well, though you surely wouldn't want to run the second Integrity Check task in batch mode until the necessary prior steps were performed.

It is primarily at the two Integrity Check stages where files are retained or discarded based upon many tests and since this testing relies heavily upon several tools that work primarily with MP3 files, you will probably want to transcode all non-MP3s to MP3 before running a final Integrity Check.

The View Spectrograph task, while somewhat time consuming, can be important in determining whether to keep or discard a file. For some hints in this regard, see the 'view spectrograph' section below.

Begin by copying whatever files you want to process to the 'input' folder and then, from the main menu of MP3 Factory, select a task to perform. The alert person you are, you noticed immediately that i used the word "copy" and not "move and potentially f'up all 40,000 of your irreplaceable music files", right? The point being that you should work on copies of your source files rather than the originals (and you should retain the originals when possible because... reasons).

When adding a comment tag to an MP3, the comment that is written depends upon whether batch mode is enabled. If batch mode is not enabled then you will be prompted for the comment text, whereas if batch mode is enabled, a default comment is written without prompting. The latter is potentially useful for writing the MP3 Factory version and current date as a comment should a new version of MP3F be released with additional or changed features and you decide to re-process your collection. You could also match the date in the comment tags to the date of the archived log files in order to see exactly what settings were used to process the files in question.

After processing a file there may be one or more error messages starting with 'ERROR', 'WARNING' or 'NOTICE'. As already mentioned, you always have the option to override any errors and keep the file when not operating in batch mode, however when batch mode is enabled all files with an error level of 'ERROR' or 'WARNING' are automatically discarded. While files with only a 'NOTICE' level error are retained since they are quite fixable.

Any file with any error that is retained when not operating in batch mode will have it's file name prefixed with '[X]' so that you know further action is necessary. The prefix will be removed if the error is fixed and it passes the second Integrity Check.

If your music collection consists of singles you downloaded from all over the damn place (like i do) without paying much attention to quality, then don't have a stroke when a huge chunk of it is flagged as junk when subjecting it to an Integrity Check with the default settings. A great deal of music on the interwebs was encoded by dummies like my somewhat former self, not that i gained many IQ points since then. For example, allot of music is encoded using a constant bit rate (CBR) of 320 kib/s which makes little to no sense since the primary purpose of the MP3 format is to reduce file size. Yes, that's a not-so-gentle poke in the ribs for you "but mah 320 CBR" peeps out there who should instead be using LAME's --preset insane , --preset extreme or --preset standard settings which have been thoroughly tested and which produce transparent results for most people; 'transparent' meaning that they cannot tell the difference between a high quality VBR encoded file and the original. Also, a 320 CBR can actually be of lessor quality than a high quality VBR.

batch processing

If you choose to disable pausing after each song is processed then MP3 Factory will batch process all files in the /input directory that are compatible with the chosen task. In this mode of operation the files will be automatically discarded (moved to the /junk folder by default) or moved to the /output folder depending upon the options you have chosen, as well as other internal parameters. If you're just getting to know MP3F then i suggest/warn/demand you avoid batch processing until you become familiar with it.

view spectrograph

MP3 Factory uses ffmpeg to create PNG images of the frequency spectrum of your music files. If batch mode is not enabled you will be shown the image as each image is generated in order to make an immediate determination as to whether to keep the song. If batch mode is enabled then no preview is shown but the images are still written to the /spectro folder with the same base file name as the song (i.e. 'this - song.mp3' has the corresponding image file name of 'this - song.png').

One of the things to look for in these images is the frequency cutoff point, meaning the highest frequency the audio attains. The highest frequency that can be encoded in an MP3 is limited by the bit rate, however there is more to consider. Another thing to look for is clipping. Pictures are worth stuff they say, so let's give that a shot...

Here's what the frequency spectrum looks like for a random FLAC music file that indicated a bitrate of 872 kbit/s. The keen observer you are, you'll notice that the frequency cutoff is close to 21000 Hz, or 21 kHz, which is slightly higher than the highest frequency the average young human is capable of hearing (20 kHz). The files size here is a whopping 26,924,696 bytes.

Frequency spectrum for FLAC sample 872kbps

Next i transcoded the 872 kbit/s FLAC file to a 320 kbit/s CBR MP3. The file size dropped to 9,882,876 bytes, less than half of what it was, yet we lost very little quality. You'll notice the frequency cutoff point has dropped to around 20000 Hz, or 20 kHz, so we lost a little something, but nothing anybody without very terribly keen hearing in a quiet environment with a decent sound system is likely to notice. We also saved a hell of a lot of disk space which is crucial if you want to cram as many songs as possible onto that microscopic SD card that you struggle to plug in to your fondleslab.

Frequency spectrum for MP3 sample 320kbps

Next i converted the 872 kbit/s FLAC to a 128 kbit/s MP3. This time the quality loss is significant to the point where most people with decent hearing in a quiet listening environment and a decent sound system would probably notice. If you're listening to music while operating a jackhammer however, then a 128 kbit/s might be just dandy. Here the frequency cutoff is around 16000 Hz, or 16 kHz, and the file size is 3,953,289 bytes, again half of what it was.

Frequency spectrum for MP3 sample 128kbps

Now i 'did as stoopid does'; i took the 128 kbit/s MP3 and upsampled it to a 320 kbit/s because "more quality", however the only thing i actually accomplished was to fatten the file size, which has now more than doubled to 9,882,876 bytes, the same size of the 320 kbit/s MP3 that was converted from FLAC earlier. The quality is, at best, no better than the 128 kbit/s file and the frequency cutoff point hasn't changed. The lesson here is that you cannot add quality to an MP3 file; it either exists in the first place or it never will.

Frequency spectrum for MP3 sample 320kbps

So now we know that files with a high bit rate and a low frequency cutoff point are upsampled junk, right? Well, no, not necessarily.

When encoding an MP3, audio data is sacrificed in order to reduce the file size, however the way that a good encoder (LAME) does this is to discard sound that the ear would never hear anyway, thus everything above and below a given frequency is discarded right off the bat and it doesn't end there. The bit rate is a primary factor regarding sound quality and frequency cut-off with the LAME encoder. As the bit rate is decreased, so too is the maximum frequency that the audio is able to attain. We know that the average young human with really good hearing can hear frequencies up to about 20 kHz, but as we age that threshold drops. Below is the approximate maximum frequency that can be attained at a given bit rate for a LAME encoded MP3. Keep this in mind when viewing spectrograph images of your audio files:

64  kbit/s = ~11 kHz frequency cut-off
128 kbit/s = ~16 kHz frequency cut-off
192 kbit/s = ~19 kHz frequency cut-off
320 kbit/s = ~20 kHz frequency cut-off

But again, the frequency cut-off point is not in itself a determining factor of file quality. While the cut-off points above are useful for Rock and Pop type genres with a variety of instruments and vocals, they may be meaningless for songs which are not composed with so much diversity. For example, a 'perfect' quality audio recording of a flute, a vocal, or a piano, may have a frequency cut-off point that is well below those stated for a given bitrate.

The other thing to look for in the spectrographs is signs of clipping. Clipping is the result of the gain (volume) having been raised too high and this can lead to really nasty distortion when listening to the song. This is not uncommon given the loudness war we've been subjected to, as well as poor encoding practices. Here is a frequency spectrum of Acoustic Alchemy - Clear Air For Miles.mp3 (320 kbit/s CBR 44.1 KHz). There are no significant signs of clipping here:

Frequency spectrum: Acoustic Alchemy - Clear Air For Miles MP3

Using MP3gain i then increased the gain by 10 dB and this was the result:

Frequency spectrum: Acoustic Alchemy – Clear Air For Miles MP3 (clipping)

What you'll notice is that a lot of the green and blue stuff now reaches the upper frequency cutoff point and this is indicative of clipping.

So how do you use all this information? Well, this is where it gets tricky because an MP3 that was encoded using a high bit rate, yet doesn't approach 20 kHz, is not necessarily of poor quality. Given the wide variety of sounds in most Rock, Pop and some other genres of music we listen to today however, these songs will often approach or slightly exceed 20 kHz even after being converted to MP3 as long as a high quality VBR or CBR encoding method was used.

Over time you'll develop a sense of what the frequency spectrum should look like given the bit rate and the different kinds of sounds present in the recording. Ultimately what matters however is whether you're happy with what you hear, not the fancy colors on a graph.

See also: Spectral Analysis (archive) and Audio Checker – Check the True Quality of Your Audio Files

integrity check

The Integrity Check operations are fairly comprehensive, therefor i think they deserves special attention so you can understand what's going on under the hood and why all your music gets flagged as junk. Actually i'm just in the mood to elaborate about technical crap in such a way as to appear as though i know what the hell i'm talking about, but we'll ignore that.

When running an Integrity Check many tests are performed depending on the options you've defined. When batch mode is not enabled you always have the option to keep or discard the file, whereas when batch mode is enabled, the fate of the file depends entirely upon those options. Here's an overview of what happens when you process an MP3...

  1. ffprobe spits out a pile of information about the file, though it is not used for any purpose other than informational. This output is disabled by default.
  2. A check is performed to see that the tags (artist, title, etc.) you require are present.
  3. eyeD3 spits out a bunch of information regarding the ID3 metadata and a test is performed to see whether the amount of ID3 padding exceeds a given value.
  4. mpck is run and several tests are performed:
    1. Check that the ID3 tags are of an acceptable version.
    2. Check for the presence of obsolete APEv1/2 tags.
    3. Report the integrity of the file.
  5. mp3vl is run to check for various issues.
  6. mp3info is run and a bunch of tests are conducted to determine the integrity of the file, including:
    1. Whether the sample rate is acceptable.
    2. Whether the average bit rate is acceptable.
    3. Whether there are any damaged audio frames.
    4. Whether the MPEG version is version 1.x.
    5. Whether the MPEG layer is layer 3.
    6. Whether the audio channel layout is acceptable (stereo, joint stereo, mono, etc.).
    7. Whether the file was encoded from the original media.
    8. Whether the encoding method is acceptable (VBR, CBR).
    9. Whether the duration is acceptable (helps to weed out truncated or concatenated files).
    10. Whether the audio frames include a CRC checksum, which is probably a bad idea (see the 'CRC verification' section below).
    11. mp3guessenc is run and more tests are conducted to determine whether the file is good or bad (have you realized yet just how hard i'm trying to flag all your music as garbage?). These tests include:
      1. Whether a LAME tag is present and, if so...
        1. Whether the CRC checksum in the LAME tag matches a hash of all the audio frames. This can ('can' being emphasized) tell you whether someone or something mucked with the actual audio, such as mp3gain, mp3splt, etc.).
        2. Whether 'unwise' encoder settings were used.
        3. Whether the 'nspsytune' option was used with LAME.
        4. Whether the 'nssafejoint' option was used with LAME.
        5. Whether the 'lowpass' filter setting is acceptable.
      2. Whether the file size overhead is of an acceptable value or, in other words, whether there is too much metadata or other garbage.
    12. ffmpeg is run to check for decoding errors.

If the file is not an MP3 then only a subset of the tests can be performed. For instance for a FLAC file the following tests are performed:

  1. ffprobe spits out a pile of information, though this information is not used for any purpose other than informational.
  2. A check is performed to see that the tags (artist, title, etc.) you require are present.
  3. metaflac is run and the information it provides is used to determine whether the file is good or bad. The tests performed are:
    1. Whether the sample rate is acceptable.
    2. Whether the number of bits per sample is acceptable.
    3. Whether the duration is acceptable (helps to weed out truncated or concatenated files).
    4. Whether the number of audio channels is acceptable.
  4. ffmpeg is run to check for decoding errors.

CRC verification

The LAME encoder v3.90 or newer writes CRC checksums to the LAME/Xing header of the MP3 when it's encoded. While not bulletproof, this checksum can be used to verify the integrity of the audio stream as a whole (metadata such as artist, title, etc., do not affect the audio verification). While LAME can also write a CRC checksum to each audio frame which may provide a more accurate diagnosis as to whether the audio has been altered, this is discouraged since the space used for this information is the same as that used for the actual audio, thus leading to a possible reduction in audio quality. MP3 Factory can use mp3guessenc to verify that the checksum in the LAME tag matches a hash of the audio and while enabling this check is a great way to weed out a lot of damaged, truncated, or otherwise compromised files, be aware that MP3s processed by any tool which modifies the audio frames, such as mp3splt and mp3gain, may fail the CRC check. Also MP3s that were encoded using ffmpeg will not include this information and therefore the CRC check will fail.

trim silence

Trimming silence should be avoided whenever possible, however if it is necessary it is best to perform the operation on a FLAC file before it is converted to an MP3, else it will not pass an Integrity Check given the default options, though this can be safely ignored. If it is an MP3 that must be trimmed, it is possible it wasn't properly encoded, or the music player (the decoder) isn't discarding the silence added by the encoder (typically LAME). Furthermore if there is a CRC checksum in the LAME tag it will no longer match that of the audio and thus, again, it will no longer pass an Integrity Check, though this can be safely ignored.

In summary, if it is necessary to trim silence from the file, it is best to locate a better copy whenever possible.

Mp3splt can trim more than silence if the silence detection threshold (the value of -p th in the Mp3splt options) is not properly set, therefore you should never batch trim all your music files! It is always best to preview them first to determine if they actually need trimming. When pausing is enabled you will have the opportunity to preview a few seconds of the beginning and end of each file both before and after trimming and, if you're not satisfied with the result, you can adjust the silence threshold and start over. If you find that not enough silence was removed, lower the db threshold by 1 or 2 (e.g. from -48 to -50) and repeat the process. Conversely, if too much was removed, raise the threshold and try again. Don't be surprised if, on occasion, you run across a file where you simply cannot trim it the way you want regardless of the silence threshold value. Again, it's probably better to locate a better copy than fool with silence trimming.


The repair tasks should not be invoked carelessly. The 'Rebuild file with ffmpeg' task is intended as a last resort to recover undamaged audio from an otherwise irreparable MP3 (damaged audio can not be repaired). This task will discard all metadata by default. If you really want the smallest possible file size and do not care about the metadata, you could invoke this task to achieve such a result, but be aware that the decoder may not display any song information.

miscellaneous notes

MP3 Factory does not use ffmpeg to encode MP3s, rather it uses LAME directly so that a proper LAME tag with accurate information is present.

ffplay, a part of the ffmpeg package, is used in various operations to preview the music files. ffplay does not offer any graphical controls in its interface but you can control it with hotkeys. See the 3.6 While playing section of the ffplay documentation. The basic controls you may find handy are:

  • space bar : play/pause
  • left/right (arrows) : seek backwards/forwards 10 sec.
  • down/up (arrows) : seek backwards/forwards 1 min.
  • escape key : quit


DISCLAIMER: MP3 Factory is in the early stage of development and is considered 'alpha' software, meaning there be bugs here. It may not be feature complete and some stuff may simply fail to work. If you choose to use it you should be competent enough to review the code and smart enough to backup your music files before processing them. If anything explodes, a mirror will reveal who's to blame :)

Having said that, i am developing and using it on my daily driver box without any guardrails. Then again, i've been known to do stupid things that result in catastrophe, like that time i formatted the wrong partition without first making a fresh backup (i never even thought to ask the NSA to send me their copy).

Code repository:
ZIP archive:
TAR.GZ archive:
Change log:

suggested software

MP3 Factory does not depend on the following programs, however i readily recommend them.

Kwave Sound Editor (pkg. name: kwave): Kwave for the KDE desktop is a nice and simple sound editor that i used while developing MP3 Factory. If you need more power, try Audacity or ardour.

MP3 Diags (pkg. name: mp3diags): A very comprehensive MP3 diagnostic and repair utility with an odd, not so intuitive interface, and a bit of a steep learning curve. You probably want the "unstable" version if you can get it to run. You could certainly use MP3 Diags in place of MP3 Factory, but you'll need to do some serious reading, configuring and experimentation. I used MP3 Diags while developing MP3F for testing purposes and to verify it was producing clean MP3s (it is, depending the configuration).

puddletag (pkg. name: puddletag): Used to edit MP3 metadata and more, puddletag is a powerful and excellent replacement for the well received Windows program, Mp3tag.

Sonic Visualiser (pkg. name: sonic-visualizer): An excellent tool to analyze audio in different ways.


Email me when this content is updated.

MP3 Factory: 'De-borking' MP3s on Linux

Leave a Reply

Your email address will not be published. Required fields are marked *