Platform-specific notes

Linux Windows Others

Source code

Generic / Linux Windows Git repository

Binaries and packages

Windows Linux generic

Uninstallation

Documentation

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 5, which is widey available. (An update to Qt 6 should come at some future point in time.)

Since this really is a Linux program, there might be some Windows-specific crashes or other issues, so I recommend using Linux instead. At any rate, many users had no issue with the program on Windows. Still, there are some reports of crashes from Windows users. I try to fix those crashes, but time tends to be an issue.

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 these didn't do any good.

Another known issue is with having the files on external or network drives, including USB sticks. This has been reported a number of times, but puzzled me over the years. Finally, in December 2023 I was able to identify the likely cause, and future releases should have the corresponding fix.

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

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

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 merely available for packagers to copy it wherever is appropriate for their distribution. There are also git repositories.

The development system is openSUSE. I sometimes compile MP3 Diags on other distributions, but not too often.

In order to compile and run the project, these packages should be installed:

Qt is used extensively. Qt 5 is the currently used version. Qt changes sometimes lead to UI glitches, which I don't always notice but about which I'd like to know.

If you find some other required package, please let me know.

For the actual build, there are several options:

• CMake.
  • cmake -S . -B build/release -DCMAKE_BUILD_TYPE=Release
  • cmake --build build/release -j $(getconf _NPROCESSORS_ONLN)
• Qt Creator and other IDEs that support CMake - open CMakeLists.txt
• Qt Creator - open mp3diags.pro
• Build.sh, which relies on QMake and is how MP3 Diags was traditionally built for Linux. A wrapper for it is Install.sh, which copies the files to /usr/local (and thus needs admin permissions).

To uninstall the program, see the corresponding section at the bottom of the page.

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.

The build used to use qmake everywhere, but now it uses CMake and Visual Studio. (MinGW used to work, but I didn't test it after the switch to CMake. I expect it not to need big tweaks. Anyway, the following steps are for Visual Studio.)

Prerequisites

Visual Studio	Get Visual Studio 2022 if you don't have it already ("Community" is fine, 2019 should work as well.) Make sure you include Desktop development with C++ when choosing which parts to install.
ZLib	Get the sources from zlib.net and unpack them under some folder. In the Windows Start Menu, under Visual Studio, choose "x64 Native Tools Command Prompt for Visual Studio" Go to the ZLib folder, run nmake /f win32/Makefile.msc and wait for the build to finish Create C:\local\zlib_13\include\ and copy there zconf.h and zlib.h Create C:\local\zlib_13\lib\ and copy there zdll.lib, zlib.lib and zlib1.dll
Boost	Get the binaries from sourceforge.net. The one with the largest number of downloads is usually the best bet. As of this writing, that is boost_1_83_0-msvc-14.3-64.exe. If you get a warning that the file isn't commonly downloaded (with Edge), click on the 3 dots, choose "Keep", then "More info", then "Keep anyway". Run it and keep the suggested location, probably under C:\local\. After install, C:\local\boost_1_xx_y\libs\ should exist, with "xx_y" replaced by an actual version. Again, tell Windows that you trust the file and want to run it.
Qt binaries	Go to qt.io and make sure you are logged in. (You may need to create an account.) Go to qt.io/download-open-source, scroll down, and click on Download the Qt online installer. Run the downloaded file and log in Choose Qt 5, e.g. 5.15.2. Deselect MingW and other options, but keep MSVC 2019 (note that 2022 wasn't available at the time of this writing, but it's supposed to be compatible), CMake, and Ninja Proceed with the install
OpenSSL binaries	Go to slproweb.com and get the current Light installable for version 1.1 (which is 1.1.1w as of this writing), either MSI or EXE. (Qt comes with its own copy of OpenSSL, but that isn't suitable for MP3 Diags, because it is not compatible with Qt 5, but only with Qt 6.) Install the downloaded file. (You probably don't want to copy anything to the Windows System folder.)

Building the project

Get the code ready:

1. Get the code and unpack it if needed
2. Open the file CMakePresets.json in a text editor and make whatever adjustments are needed to the values under the environment key, such that:
   • Boost_ROOT contains the files boostcpp.jam or boost-build.jam
   • ZLIB_ROOT contains the folders include and lib
   • Qt5_ROOT contains the folders include, lib, mkspecs, translations, ...
   • OpenSSL_BIN contains the files libssl-1_1-x64.dll and libcrypto-1_1-x64.dll

Then you can build from the command line or from within Visual Studio.

To build from the command line, open a "x64 Native Tools Command Prompt for Visual Studio", go to the project's root and run:

• cmake -S . -B out\build\x64-release --preset x64-release
• cmake --build out\build\x64-release --config x64-release -j %NUMBER_OF_PROCESSORS%

To build from Visual Studio, start Visual Studio and open CMakeLists.txt from the menu File / Open / CMake ..., then press F7.

If the build went OK, the executable will be in out\build\x64-release (or out\build\x64-debug), together with translations, DLLs, and other dependencies, so you should be able to just run the executable there.

To uninstall the program, see the corresponding section at the bottom of the page.

Note: There is also an HTML / JScript application called BuildMp3Diags.hta, which uses QMake and supports multiple compilers and build options from a simple UI interface. It became unusable with newer versions of Windows 10 but was fixed in November 2023. Still, it's unclear if it will be kept long-term, given that the build process now uses CMake in Linux and Windows.

The git repositories store 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.

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 (but there are options for running it on Windows). MakeArchives.sh is used to set the correct branch and version number in a number of places, mainly 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. Actually, 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.)

The build scripts can be used as a starting point for creating binary packages for .rpm- or Debian- based distributions. It used to be necessary to run AdjustMt.sh in order to account for how dependencies were packaged, but that is probably no longer the case.

There are 2 main choices: binaries that I build, and those built by others. I'm not aware of anybody else besides me releasing Windows builds, while MP3 Diags is included in some well-known repositories and official distributions for non-Windows systems; as far as I know, you can get it for Gentoo, Ubuntu, Mint, Debian, Mac OS X, openSUSE, and Arch Linux.

I used to build the program for Fedora, openSUSE, and Ubuntu at openSUSE Build Service, but I no longer do this, as I didn't get much feedback on these and it doesn't look like anybody misses them.

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 build from sources.

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 64-bit installer
• Zip archive with Windows 64bit executable and required DLLs. Note that you also need the Visual Studio redistributables, but they may be already installed, as other programs need them to. If not, you can get them from Microsoft.

Note: More likely than not, you will get warnings from Windows about MP3 Diags being an unrecognized and potentially harmful program. This is due to MP3 Diags not being registered with Microsoft (which seems to require it being distributed by a company, among other things) and not having enough downloads to be considered OK automatically. So far I don't have a good solution to this, so all you can do to get the program installed is to ignore the warnings, as shown below. (There are a number of opinions on this subject, like this post on StackOverflow.)

Starting with version 0.99.06.043, "generic" Linux executables were provided. They were supposed to work on any recent distribution on x86 or x86_64 CPUs but very limited testing was done.

At some point in time I stopped providing them and nobody complained, so I never resumed building them. Older versions can be found here. Even though they are quite old, it's not a huge deal, provided that they run, as there were no major features or bad bug fixes after that.

Flatpack or Snap are more modern solutions to this problem, but I'm not sure if it's worth the effort.

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.

If for some reason you don't want to look at the documentation online, you can download it here.