MP3 Diags - Getting MP3 Diags
Description: End-user documentation for MP3 Diags, an MP3 analysis tool that also includes correction and tag editing functionality
Keywords: MP3, diags, diagnosis, tag editor, tagger, normalizer, repair, VBR

Home | Getting MP3 Diags | Short MP3 introduction

You may want to look at the change log here, especially if you installed an older version before.
Version to use
There are 2 versions of MP3 Diags: Stable and Unstable. Development goes on in the unstable version and after a while changes get moved to the stable version.
Bug fixes normally happen in the unstable version, but serious bugs are also fixed in the stable version. The plan is to fix bugs in a timely manner, so potential bugs shouldn't be a big issue even when running the unstable version (at least if you keep backup copies of your MP3s.) Note that fixing bugs is easiest when I can reproduce them or at least have a good idea about what might be causing them. I am aware of several outstanding bugs, which I can't fix due to lack of user feedback: I can't reproduce the bug and I can't make a reasonable guess as to what's causing it, so I need more details from the reporter, but the reporter doesn't provide those details. After a while these bugs will be closed.
From time to time you may want to check the MP3 Diags blog, where product announcements are made, with details about bug fixes, new features, and other changes. Then you can decide based on what changed in a given version if you want to upgrade or not. (If you use an RSS reader, you can add that page to it, so you see the notifications automatically.)
The build / install instructions are terribly outdated, but they are not so important, as most users want the Windows install, which works. Those that compile the source code on Linux would need to play a bit with dependencies, which shouldn't be a big deal (but harder than before, when you could just run an .sh to get everything working). For Windows, compiling works as well, as long as the dependencies are downloaded / built.
The instructions will be updated at some point in time, based also on requests. Until then, the old ones will still be kept, as they might still be useful as starting points.
There are both source files and binaries, for several Linux platforms, as well as for 32bit Windows. On this page there are all the links to the current packages. If you need some older version, you can go to the main download page at SourceForge. The packaged Linux binaries that I provide are built and hosted by the openSUSE Build Service. There are also "generic Linux binaries", which I build on my own computer.

Platform-specific notes
Linux
Windows
Others
Source code
Generic / Linux
Windows
Git repository
Binaries and packages
Windows
Linux generic
openSUSE
Fedora
Ubuntu
Debian
Gentoo
Others
Uninstallation
Documentation

Platform-specific notes
Linux
Linux is the development platform (openSUSE, to be more precise), so the program should work best on Linux. The most important requirement is having Qt 4.3.1 (or above), so I expect most Linux distributions from 2007 or newer to be able to compile and run it (perhaps after some tweaks of the build scripts.)
Windows
Since this really is a Linux program, there might be some Windows-specific crashes or other issues, so I recommend using Linux instead, if at all possible. At any rate, I did process some 1600 songs with the Windows port to fix issues in the audio part, and then I corrected the ID3V2 tags and added images for 85 of my albums and everything went OK, no crash whatsoever. But, as they say, your mileage may vary. For one thing, there are some reports of crashes from Windows users, while others are happily using the program. I try to fix those crashes, but usually I need more details and quite often those who report the crash don't seem interested in providing those details. OTOH others have been really helpful, so the crashes that affected them got fixed.
There is one outstanding bug causing files to be read-only on Windows 7. There were several reports, and I've seen it myself; however, when I wanted to get a closer look, the files became writable again (or perhaps I didn't remember their location correctly.) This seems to be related to user rights / file permissions, but for now it's an open issue and suggestions about why is this happening and how to make the program work are welcome. Some things that I would expect to help in this situation are running the program as an Administrator, copying files to a FAT partition, or turning off User Account Control. However, at least in one case they didn'do any good.
I tested previous versions of the executable on XP SP1, XP SP2, XP SP3, Vista Home, and Windows 7. Currently the build and tests are done on Windows XP SP2.
Others
There is this page in the Fink Project, so it looks like the program should work on OS X; also, several percent of the visits to the web site are by OS X users. However, I have never heard from any Mac user about their experience with MP3 Diags, so I can't really say that it works there. Or perhaps they would have told me if it didn't ...
There is an OS/2 port by Elbert Pol. See this page for links.
I'm not aware of attempts to compile and run the project on other platforms, but I'd like to know if anybody tried it and what the results were. At any rate, there is a file that only works with GCC or MSVC, so other compilers should fail until that file gets ported. If somebody wants to publish builds, it would probably be a good idea to tell me, so I can add a link to the build for that platform.
Source code
Generic / Linux
You can download MP3Diags.tar.gz from SourceForge or from my ISP. At my ISP you can also find a source + documentation bundle. The intended target for the bundle are the packagers. In particular, the documentation doesn't get installed anywhere, but is mereley available for packagers to copy it wherever is appropriate for their distribution.
The development system is openSUSE. I sometimes compile MP3 Diags on other distibutions, and that worked fine thus far.
In order to compile and run the project, these packages should be installed:

Generic names | C++ compiler, Qt4 development, zlib development, Boost development, Qt4 SVG, GIF and JPEG plugins (if they are separate packages)
openSUSE 10.3, openSUSE 11.2 | gcc-c++, libqt4-devel, zlib-devel, boost-devel, make
Ubuntu 9.04 | g++, libqt4-dev, zlib1g-dev, libboost1.35-dev, libqt4-svg
Fedora 10 | gcc-c++, qt-devel, zlib-devel, boost-devel
Others | to be determined

Qt 4.3.1 is the one that was used initially for development but I moved to newer versions as they were released (so anything in 4.x above 4.3.1 should be OK too.) Currently the project cannot be compiled with Qt to 5.x, but it shouldn't be too hard to port it. Qt changes sometimes lead to UI glitches, which I don't always notice but about which I'd like to know.
If you use GCC 4.4 or above, you need Boost 1.37 or later (see http://bugs.xmms2.xmms.se/view.php?id=2215.)
If you find some other required package, please let me know.
To install the program, unpack the surce to some directory and just run Install.sh in that directory. Note that double-clicking the script in some file browser may or may not work, depending on the "current directory" being set properly and on whether a terminal window gets opened so you can type the root password to get the executable copied to /usr/local/bin. Other options are to manually run the relevant commands in Install.sh, or to compile the project in an IDE. If you don't use Install.sh, pay attention to having the right serialization library. I think the default is OK for most platforms, but in some cases the file src/src.pro should have LIBS += -lboost_serialization rather than LIBS += -lboost_serialization-mt. Running Install.sh or just AdjustMt.sh sets the correct value.
To uninstall the program, see the corresponding section at the bottom of the page.
Windows
Since there are binaries available (both setup.exe and zip archive), it's more convenient to just use them. However, if you really want to build the project yourself, it's not that hard. You should run BuildMp3Diags.hta, an HTML / JScript application that allows you to do these:

- Build the project using MinGW
- Build the project using Visual C++
- Create a .pro file that can be open from Qt Creator
- Create a .sln file that can be open from Visual C++

(MinGW used to work out-of-the-box, but currently it's Visual Studio that's the primary target. MinGW "should work" but after some tweaks.)
So, several notes for Visual Studio

- Used Visual C++ Community 2017
- Due to MusicBrainz / Discogs integration being disabled, zlib is not really needed right now, but it's part of the process, so it should be there. To make it more annoying, it no longer seems to be available as a binary, but only as source, which needed CMake to build.
- Qt 5.12.1.0 was used to build version 1.5.01, and it had all binaries included, so Qt itself didn't have to be built
- Boost (1.69) was built using instructions on the Boost site (serialization and program_options)
- BuildMp3Diags.hta used to work fine on previous Windows versions, but it's quite a pain on Windows 10 (forgets settings, has to be told several times what to do, ...)

First you need to download and perhaps compile the required libraries: zlib, Qt, Boost Program Options, and Boost Serialization. In case it's not obvious, you cannot mix C++ libraries created by / for different compilers. While downloadable binary Qt libraries existed for MinGW for some time, for Visual C++ 2008 they have been introduced in Qt 4.6.
Well, you need binary zlib, Qt, and Boost for either MinGW or Visual C++. If you can find binaries - fine. Otherwise you'll have to build from sources what's missing. These are the options for building MP3 Diags on Windows, based on what you have available:

zlib for MinGW and Visual C++ | Go to http://www.zlib.net/ and get the "zlib compiled DLL". Unpack it somewhere and you're done. (This is a C DLL, not a C++ one, so it works with all the compilers)
Qt binaries for MinGW | Go to http://qt-project.org/downloads and see what you can find. As mentioned above, the program currently doesn't compile with Qt 5, so 4.x is needed. Note that the "Qt root folder" that BuildMp3Diags.hta wants is something like C:\QtSDK\Desktop\Qt\4.x.y\mingw
Boost sources 1.47 and above for MinGW | Go to http://www.boost.org/users/download/ and click on "Download". Unpack the archive in the folder where you want Boost to be located Open a Qt Command Prompt and go to the Boost root folder run bootstrap run b2 toolset=gcc serialization program_options threading=multi release . This will only build the Serialization and Program Options libraries, and put them inside a "bin.v2" folder
Boost sources up to 1.46 for MinGW | Go to http://www.boost.org/users/download/ and click on "Download". Unpack the archive in the folder where you want Boost to be located Go to https://sourceforge.net/projects/boost/files/boost-jam/ and download the latest ntx86.zip. Unpack the archive and copy bjam.exe to the Boost root folder Open a Qt Command Prompt and go to the Boost root folder run bjam toolset=gcc serialization program_options threading=multi release . This will only build the Serialization and Program Options libraries, and put them inside a "bin.v2" folder
Qt Binaries for Visual C++ | Go to http://qt-project.org/downloads, and see what you can find there
Qt Sources for Visual C++ | In case you can't find binaries for your Visual C++ you can try to build from sources. These used to work but weren't tested in a while: Go to http://qt-project.org/downloads, and get the archive Unpack the zip file in the folder where you want Qt to be located Install Active Pearl Open a Visual C++ Command Prompt and go to the root folder of the unpacked Qt run configure.exe (which may take a while) run nmake (which will take much longer than configure.exe) (These are mainly taken from Rajorshi's blog, where you can find more details. As of January 2014 the post seems deleted, but you might get it via the Wayback Machine)
Boost binaries for Visual C++ | Go to https://sourceforge.net/projects/boost/files/boost-binaries/ and download the package corresponding to your compiler. Unpack the archive in the folder where you want Boost to be located
Boost sources 1.47 and above for Visual C++ | Go to http://www.boost.org/users/download/ and click on "Download". Unpack the archive in the folder where you want Boost to be located Open a Visual C++ Command Prompt and go to the Boost root folder run bootstrap run b2 toolset=msvc serialization program_options threading=multi release debug . This will only build the Serialization and Program Options libraries, and put them inside a "bin.v2" folder
Boost sources up to 1.46 for Visual C++ | Go to http://www.boost.org/users/download/ and click on "Download". Unpack the archive in the folder where you want Boost to be located Go to https://sourceforge.net/projects/boost/files/boost-jam/ and download the latest ntx86.zip. Unpack the archive and copy bjam.exe to the Boost root folder Open a Visual C++ Command Prompt and go to the Boost root folder run bjam toolset=msvc serialization program_options threading=multi release debug . This will only build the Serialization and Program Options libraries, and put them inside a "bin.v2" folder

In many cases it's possible to choose various options or do things differently, but I won't get into any of that, instead trying to make this as concise as possible. If you care about those options you probably shouldn't be reading this anyway, as you already know what to do.
After the libraries are downloaded / built, download and unpack MP3Diags.tar.gz from SourceForge or from my ISP, run BuildMp3Diags.hta, fill in the fields, and create the project files or build the program. BuildMp3Diags.hta has more details about this process.
If you don't like the idea of some JScript doing things on your hard drive, you can always change the src\src.pro file until it works. And there's another option as well: Sebastian Schuberth made it possible to compile the project with Visual C++ using CMake. You'll need to set BOOST_ROOT and QTDIR, then run CMake-VS2008-Win32.cmd to generate MP3Diags.sln and MP3Diags.vcproj. Since I don't actually use this, the code may fail to compile occasionally, due to missing headers or some other non-GCC issue. Most likely I won't notice these issues until told.
To uninstall the program, see the corresponding section at the bottom of the page.
Git repository
The source code used to be in Subversion, but now it's in git. There are now 2 public repositories, one at SourceForge and one at GitHub.

- Sourceforge page or run git clone git://git.code.sf.net/p/mp3diags/code-git mp3diags-code-git
- GitHub page or run git clone https://github.com/mciobanu/mp3diags.git

(Note that the Subversion repository wasn't imported to git. Rather, a private Perforce repository was used as the source for what's in git.)
The source code may also be downloaded from the Subversion server provided by SourceForge, by going to the SVN Browser and clicking on Download snapshot in the top-right corner of the page. Or you can check out the trunk using this command:
svn checkout svn://svn.code.sf.net/p/mp3diags/code/trunk/mp3diags mp3diags
Builds created from code from this server are supposed to be of the same quality as official releases. Changes are tested before checking in. (However, occasionally mistakes may be made.)
The Subversion repository stores all the tools that are needed to build the project, not just the source code. So you can find there the documentation, installer and build scripts, and desktop integration files. The build scripts can be used as a starting point for creating binary packages for other .rpm- or Debian- based distributions. Before trying to compile on openSUSE 10.3 (and perhaps other distributions), you should run AdjustMt.sh or Install.sh.
There are some differences between the sources that you download via Subversion and the ones that you get from SourceForge as source packages, as the latter ones are "generated", using MakeArchives.sh. This script is Linux-specific; there is no Windows equivalent or plan for it (it might work with Cygwin, though, perhaps after some adjustments). MakeArchives.sh is used to set the correct branch and version number in a number of places, mainly the build tools and the documentation, but also several C++ files. It also renames some of the files, so they have the branch as part of their name and moves the documentation files up one folder. Or, well, it doesn't do any of these, but it creates a directory called package/out where it makes a copy of the project that includes these changes.
Note that you may need to set the executable bit for AdjustMt.sh, Install.sh, Uninstall.sh, and MakeArchives.sh, at least when downloading the tarball.
See the notes above about requirements and how to build the code.
To uninstall the program, see the corresponding section at the bottom of the page.
Binaries and packages
There are 2 main choices: binaries that I build and those built by others. Since this is my first attempt at creating distributable binaries, I'm not very confident that they are of good quality, so using binaries built by others might be a better idea. One known issue is that they are not signed.
MP3 Diags is included in some well-known repositories and official distributions; as far as I know, you can get it for Gentoo, Ubuntu, Debian, Mac OS X, openSUSE, and Arch Linux. Besides those, I build the program for Fedora, openSUSE, and Ubuntu at openSUSE Build Service.
For Linux binaries you'll probably want to install from a repository (or use 1-Click-Install on openSUSE), rather than install the .rpm or .deb file directly. This way you get new versions automatically.
There used to be specific packages for several versions of a distribution. Building them was a long, tedious process. Now there are more generic packages, which are easier to build and should work on all recent versions of a distribution. Note that you might need to uninstall the previous version if installing from a new repository doesn't work.
If you can't find a pre-packaged binary for your Linux distribution, or if what you can find is out-of-date, you may want to try the generic Linux binaries. Also, if your distribution is "based" on some other distribution that has packages that I build, you may want to try those packages or the repositories; they should work in many cases, because they are built in a way that minimizes dependency issues.
Windows
There is a pretty standard Windows installer, as well as a zip archive with the executable and the DLLs it needs. Either one of these should be OK:

- Windows 32bit installer (if the link doesn't work, there's a copy at my ISP, here)
- Zip archive with Windows 32bit executable and required DLLs

Linux generic
Starting with version 0.99.06.043, "generic" Linux executables are provided. They are supposed to work on any recent distribution on x86 or x86_64 CPUs but very limited testing was done, so some tweaks might be needed (or it may prove impossible to make them work as intended.) The point of having them is to make it easier for more people to run MP3 Diags. Please share your experience if you try them. Note that running these alternatively with pre-packaged MP3 Diags might lead to the MP3 files being rescanned, due to a different serialization library.
This is what's available:

- Linux i686 binary
- Linux x86-64 binary

If you use these, you'll have to make sure that you have the correct dependencies. All you'll need to add is probably Qt 4. If on your distribution the SVG support in Qt 4 is packaged separately, as it is on Debian-based distributions, you'll need to add that as well. Note that the program will run without SVG, but the buttons will have no icons in such a case. If you have KDE 4.x you probably don't need to add anything.
openSUSE (see also the generic notes about binaries)
You should probably get MP3 Diags from the PackMan repository. See this link.
There are also binaries that I build at openSUSE Build Service:

openSUSE 13.2 | Repository | 1-Click Install | i586 .rpm | x86_64 .rpm
openSUSE 13.1 | Repository | 1-Click Install | i586 .rpm | x86_64 .rpm
openSUSE Tumbleweed | Repository | 1-Click Install | i586 .rpm | x86_64 .rpm

Fedora (see also the generic notes about binaries)
Binaries that I build at openSUSE Build Service:

Home directory | i386 .rpm | x86_64 .rpm

For Fedora there are no repositories, so newer versions can only be installed manually. Perhaps somebody will offer to get me started on creating repositories, or just build the program elsewhere.
Ubuntu (see also the generic notes about binaries)
Starting with 9.10 (Karmic Koala), MP3 Diags is included in Ubuntu, so you can simply install it from Synaptic. The package's page is here.
For the latest version, there are binaries that I build at openSUSE Build Service:

Repository (mirror) | i386 .deb | amd64 .deb

Normally you should use the repositories rather than the .deb file, so you are notified automatically about updates. Another issue with the .deb files is that the direct links are broken for a while after running a new build (the link is for the old version, which got replaced by the new version.) You can still get a .deb file from the repository, though.
In my tests, the Ubuntu 9.04 i386 .deb installation was OK except for a warning about the package not being authenticated, because it's not digitally signed. I looked at this and I think I can't sign Ubuntu / Debian packages that are hosted on the openSUSE servers. I might be wrong, though, since I know next to nothing about building .deb files or signing them. However, I'm not going to look any further into this by my own, but merely hope that somebody more experienced would offer to help (or even better, take ownership of the build process, so I don't have to deal with it.) At any rate, the program installs and runs OK if you ignore that warning. You can read about adding repositories on Ubuntu here. The command I used when prompted for the "APT line" was:
deb http://download.opensuse.org/repositories/home:/ciobi/Ubuntu/ ./
The repository on the main server uses redirection, which apparently isn't supported by Synaptic (or at least it wasn't until some time ago, because Ubuntu 9.04 works fine with the main server; maybe the others work too, but I don't have them installed.) Perhaps somebody would like to test if installation and / or automatic updates work for the main repositories and then share the results.
One thing I noticed on 10.10 (and I guess it's the same on others) was that I couldn't update the package using the Update Manager, because the package is unsigned. The update went OK through Synaptic, though.
Debian (see also the generic notes about binaries)
MP3 Diags is now available from sid / unstable, as well as stable and testing.
For binaries that I build at openSUSE Build Service you could probably use the ones for Ubuntu. A while ago I tested the i386 .deb on a Live 5.0 and it worked fine:

Repository (mirror) | i386 .deb | amd64 .deb

I'm not sure if the main repository can be used, because of redirection issues (see also the notes for Ubuntu, above); if it can't, the mirrors should work.
Gentoo
I don't package MP3 Diags for Gentoo. There's no need for it, as the project is now included in the distribution, thanks to Dominik Kapusta. The install instructions are rather simple:
emerge mp3diags
Others
If you can't find a pre-packaged binary for your Linux distribution / version, and you don't want to build from sources, have a look at the notes about binaries above for suggestions about getting binaries and packages.
If you want to build binaries for other platforms, please let me know, so I can add the links here.
Uninstallation
How the uninstallation should proceed depends on how the program was installed. If you installed from sources with Install.sh, there is an Uninstall.sh. If you installed on Windows using the installer, you can use both the Control panel and the "Uninstall" entry created when MP3 Diags was installed. If you used a package manager on Linux, use the same thing. If you just copied binaries, remove the binaries.
Keep in mind that besides the executable, there are data files and settings. You probably created some data files, and if you are sure you no longer need them you should remove them manually. Note that the data files come in pairs. Although you only specify an ".ini" file when you start the program for the first time (or when you create a new session), two files get created. The ".ini" only stores settings, while the actual data is stored in a file in the same directory and with the same name but with the extension ".dat".
Besides the ".ini" and ".dat" files, there is a small configuration file which is named ~/.config/Ciobi/Mp3DiagsQQQBRANCH_DQQQ.conf on Linux and similar systems. That file should be removed as well if you want no trace of MP3 Diags left on your computer. (Of course, you lose your settings, should you want to reinstall MP3 Diags.) The corresponding place on Windows is the registry entry HKEY_CURRENT_USER\Software\Ciobi\Mp3DiagsQQQBRANCH_DQQQ.
If you used shell integration, you should disable it before simply removing the program, so it won't leave garbage in your system. This is done automatically by the Windows uninstaller. You can do this manually by running the program with the "-u" parameter or by going to the Shell integration configuration page and unchecking all the options there.
Documentation
If for some reason you don't want to look at the documentation online, you can download it here.

Home | Getting MP3 Diags | Short MP3 introduction