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.)

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.

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.)

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.

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 ...

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.

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:

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.

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.

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++

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

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.

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:

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.

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.

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.

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.

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.

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.

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/Mp3Diags-unstable.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\Mp3Diags-unstable.

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.