Use MP3 Diags in Linux to repair your MP3 collection

Jack Wallen
Nov 24, 2009
Updated • Feb 15, 2018
Linux, Music

Do you have a massive MP3 collection that contains files with problems? Don't you wish you had a program that could search through that collection, find problems with those files, and fix the problems?

Fortunately for all of your MP3 horders, there are programs for just that task. One of those programs, for the Linux operating system only, is MP3 Diags. This application is an open source app will serve as your one-stop shop to identify and repair over 50 different problems that can occur with MP3 files.

You might think, because of the nature of the task surrounding this tool, that MP3 Diags would be challenging to use. It's not. In fact it's quite simple to scan and repair your music collection. In this tutorial you will learn how to install and use MP3 Diags to diagnose and repair your broken MP3s.

NOTE: Martin covered using MP3 Diags for the Windows operating system in his article "Diagnose your MP3 collection with MP3 Diags". Since there are issues to over come when using this application in the Linux operating system, I decided it was beneficial to cover it once again.

What can it fix?

Some of the problems that MP3 Diags can repair are:

  • Adding/fixing track info.
  • Correcting song duration times.
  • Correcting seek problems.
  • Renaming files based on fields.
  • Low quality audio.
  • Missing VBR header.
  • Missing normalization data.
  • and much more.

Now before I continue on, I will tell you that MP3 Diags can be resource intensive. If your collection is large you can expect this to take some time. During an initial scan MP3 Diags was running at approximately 2,000 files every 15 minutes. You can do the math from there.


MP3 Diags should be found in your distributions repositories. If you are using Ubuntu you can either open up Synaptic or the Ubuntu Software Center, do a search for "mp3 diags" (no quotes) mark the application for installation, and apply the changes.

When the application is installed you will find it in your Sound & Video menu entry.


When you first start up MP3 Diags a window will appear asking you to create a file which the application can save its configuration data. You can place this file anywhere you have write permission. In that same window you can set up a scan by including the directories you want to scan. In most modern Linux distributions you will find a ~/Music directory. If you're like me (and you like to keep everything well organized), you can just select that folder and begin the scan.

During the scan expect your machine to become a big sluggish. You might want to start the scan and walk away (to keep yourself from getting a wee frustrated). When the scan is over, the real fun begins.

Scan results

Figure 1
Figure 1

Take a look at Figure 1.  What you are seeing is the results of a first-run scan containing over 2,000 audio files. Near the top (under the tool bar) is a listing of all the possible issues that each file contains. Let's just look at one file.

To show only one file highlight that file and click the "Show One Song At a Time" button (Sixth button from the left on the toolbar). I will select a file, downloaded and converted from Youtube, of Rush's La Villa Strangiato. Obviously, since this was a download from Youtube, the audio quality is going to be poor. So let's repair that as much as it is possible.

Figure 2
Figure 2

Once you have your one file selected (see Figure 2) click the first work icon on the left (that's the first hammer on the left) which is a drop-down. When you first click this you will get a warning that says "although this works on the developers' machine, it might not work on yours". Take this as a caution and back up your files before you start working on them.

From the drop-down you will see numerous fixes for your file. However, instead of searching from the drop-down, you can hover your mouse over hammer icons labeled 1-4. Each of these contains a pre-configured set of fixes that allow you a single click to fix numerous, related issues on a file. For my poor audio quality file you can see it suffers from four issues:

  • fa - No ID3V2.3.0 tag found
  • ea - ID3V2 tag doesn't have APIC frame.
  • ab - Low quality MPEG audio stream.
  • an - No normalization undo data found.

When you go to fix these problems you will instantly come across an issue when using MP3 Diags in Linux. MP3 Diags uses the application mp3gain to normalize mp3 files, which is not installed by default. And, to make matters worse, MP3 Diags does not install this dependency for you. So you will have to fire up Synaptic, search for "mp3gain" (no quotes), select the results for installation, and apply the changes.

Once mp3gain is installed you can now normalize with MP3 Diags.

Another issue, specific to Linux, is that if you want to configure MP3 Diags to not erase original files, but instead to move them to another directory, you will need to make sure you change the destination directories in the preferences window.

By default all of the temporary directories are set to /tmp which you will have write access to, but if you want to archive that file you do not want it saved in the /tmp directory, because it will be deleted automatically. Different distributions handle this task differently - some clean up /tmp regularly, some upon reboot, some will empty a file in /tmp after it has gone untouched for a pre-determined span of time (usually 30 days). If you want to keep those original files around, you will want to reconfigure MP3 Diags to use a different directory than /tmp.

Final thoughts

After running MP3 Diags on my music collection, I have found that all MP3 files do, in fact, sound better and have far fewer issues. You should definitely give this application a go if you have a collection of MP3s lying around in need of repair.

Use MP3 Diags in Linux to repair your MP3 collection
Article Name
Use MP3 Diags in Linux to repair your MP3 collection
MP3 Diags is an open source app will serve as your one-stop shop to identify and repair over 50 different problems that can occur with MP3 files.
Ghacks Technology News

Tutorials & Tips

Previous Post: «
Next Post: «


  1. Björn Tiedemann said on May 30, 2012 at 8:00 pm

    If you have a low quality MPEG-Stream, how are going to improve it? Witchcraft? Mp3diags can fix problems with metadata and so on, but if the raw music stream is already of low quality there is no way to improve it.

Leave a Reply

Check the box to consent to your data being stored in line with the guidelines set out in our privacy policy

We love comments and welcome thoughtful and civilized discussion. Rudeness and personal attacks will not be tolerated. Please stay on-topic.
Please note that your comment may not appear immediately after you post it.