Ewen Cheslack-Postava

Table of Contents

1. Getting Started
Obtaining the Software
2. Tagging
Tagging Overview
Load Files
Select Results / Manually Tag
Save Metadata
Submitting TRMs
3. Options
The Options Window
Server Options
Output File Naming
File Name Format
Output Directory
Copy MP3s Across Filesystems
4. Extras


This document is intended to give the reader an overview of the functionality of QMBTagger. It will not go into great detail, nor describe the inner workings of the software. The aim is to provide a reference so a user can get started quickly.

All questions, bugs, feature requests, and comments should be directed toward the QMBTagger SourceForge.Net Project Page.

Chapter 1. Getting Started

Obtaining the Software

QMBTagger has a homepage available at http://qmbtagger.sourceforge.net. Click download on the link on the left. This will bring you to the SourceForge.Net download page. The most recent version will almost always be the best choice since it will be the most feature rich and, in general, the software has always been stable. There is little chance that it would actually ruin data (i.e. your song collection), but I do not guarantee it. At worst it should just not run (or compile).

You may download either the source version or the binary version. The binary version is provided for convenience, and thus is not guaranteed to work. It is compiled for i686 and should requires all the dependencies (i.e. can use mp3, flac, and ogg files). The source version will automatically detect what libraries you have and compile based on that. Downloading the source version is suggested since it is easy to build and install. The binary version doesn't come with an install script.

RPMs are now also available for various distributions. They are included on the same download page as the source and binary versions.


If you downloaded the binary version you may skip this step.

Since QMBTagger switched over to use the KDE Autotools, building the software is relatively simple. You will need at least automake 1.6 (as of this writing) and automake 1.6, 1.7, and 1.8 are all supported. The steps to build are:

  1. $ tar -xjvf qmbtagger-0.xx.tar.bz2

  2. $ cd qmbtagger-0.xx

  3. $ make -f admin/Makefile.common cvs

  4. $ ./configure

  5. $ make

  6. $ su

  7. # make install

Of course you can specify extra options as usual for configure (adding --enable-debug=full as an option to the configure script is encouraged, especially if reporting bugs with debugger output). Also, if you don't want to install the program, just run it, skip the last step and run ./src/qmbtagger.


If you installed QMBTagger from a package provided by your distribution, it should be located within your path. If you compiled from source as shown above, the executable is most likely in /usr/local/bin. In both cases, most likely all you have to do is run:

$ qmbtagger

from the command line. If the file is not in your path you will have to specify the full path to the executable, such as:

$ /home/ewen/qmbtagger-0.07/src/qmbtagger

That's it! You are ready to start tagging.

Chapter 2. Tagging

Tagging Overview

There are generally 5 steps to the tagging process. A summary of each step is given below, with a full explanation of each in the following sections.

  1. Load Files - Tell the tagger which files you want to tag.

  2. Query - Looks up information about each song. This includes extracting metadata, generating audio fingerprints, and asking the server for information.

  3. Select Results/Manually Tag - With the given information either choose the correct result or manually tag the song.

  4. Save Metadata - In this step the program saves all your metadata to the files and renames and/or moves them as specified.

  5. Submit TRMs - Once you have identified the correct tags, help out the project by telling MusicBrainz what metadata actually matched the fingerprint.

Read on to learn about each of these steps in detail.

Load Files

There are two ways to load files. The first should be familiar to anybody and the second is pretty easy to learn.

The first way is to go to File->Open.... A standard dialog will open up in which you can browse to the files you want to tag. You can select one or more files. Press OK when you have selected all the files you want to tag.

But what if you want to open a lot of files? And they are located in multiple directories? For anybody with a large collection of music, the standard method of opening files quickly becomes tedious.

This brings us to the second method of opening files. You can open a whole directory at once. To do this, go to File->Open Directory.... This will also bring up a standard dialog. Let's say all your music is under /home/ewen/music. Then you would browse to /home/ewen and then select the music directory. Then click OK. All the files in /home/ewen/music will be added.

But what if you have all your files in subdirectories, such as /home/ewen/music/artist/album/song.mp3? Well, if there are subdirectories beneath the directory you select, you will be asked whether to load files recursively. If you choose to load files recursively then every subdirectory will also be searched for music files and these will be added.


Once you have all your files loaded up you will need to extract information from them and find possible metadata matches.

Simply click File->Query... or the corresponding toolbar button. This process is fully automated. A progress window will pop up to show you the current progress.

If at any time you wish to stop querying, click the Cancel button. Any information already obtained will still be available for use in tagging.

This process can be quite lengthy if you have many files. Also be aware that a request for information must be sent for each file and a response received. If you tag a lot of files, the bandwidth use can build up quickly.

That's all there is to it! When the process is finished the progress bar will disappear and the results will be displayed in the main window.

Select Results / Manually Tag

Now that results have been returned and are listed, the next step is to choose which ones are correct.

Simply go through the list. Each file is listed on the left. Each of the results received from the server is listed as an item on the bottom right with metadata extracted from file itself listed above. Select the one that contains the correct information. Only one may be selected.

If none of them reflect the file's true content you can manually tag them. Right click on the file (on the left) and select Edit Tags from the context menu. This provides a window where you can type the metadata. If some data was already in the file it will already be filled in, but can still be changed.

Once you have done this for each of your files you are ready to save the results.

Save Metadata

Once you have selected the correct results and/or tagged each file, you are ready to save the files.

Just click File->Save. All the files will be saved automatically with the new metadata. Note that manual tags take precedence over selected results.

There are some options that affect saving. You can choose to put the files into a new directory and choose the file format (including subdirectory names) with metadata substitutions. See the Options section of this document for more detail.

Submitting TRMs

When you choose results returned by the server, an association is made from a TRM to a set of metadata. It is useful to MusicBrainz to know how many users associate the same fingerprint with the same metadata. To help out, you should submit these associations.

These associations are collected automatically by QMBTagger, so all you have to do is submit them. They are collected and then submitted in one batch for efficiency reasons.

Just click File->Submit to submit the currently stored TRM-Metadata associations.

If you have some left that have not been submitted when you exit you will be asked if you wish to submit them. You can choose to submit them immediately, discard them, or store them locally to be sent during a later session.

Chapter 3. Options

The Options Window

There are quite a few options for how QMBTagger operates. To change some of these options, go to Tools->Options.

No matter which tab of options you are viewing, there will always be four buttons at the bottom of the window.

Load Defaults

This loads your saved defaults if you have saved them. Otherwise it loads the default values for all the items.

Save Defaults And Apply

This saves the current options as defaults and applies them to the current session.


This applies the current options to the current session, but does not save them. The old values will be restored when you restart the program.


Undo any changes you have made since you opened the window.

Server Options

This tab allows you to specify which MusicBrainz server you are using, proxy information, and your username and password.

Server URL

The location of the MusicBrainz server we should query. This will almost always be musicbrainz.org.

Server Port

The port on which to connect to the server. Will almost always be 80.

Proxy URL

If you need to use a proxy server to access the MusicBrainz server, fill it in here. If left blank, no proxy is used.

Proxy Port

The port to use to connect to the proxy.


Your MusicBrainz username.


Your MusicBrainz password.

Output File Naming

The options for naming output files are not too complex. There are two major considerations and one minor one.

File Name Format

File names can be of any format normally accepted by the filesystem. Additionally, you may use some some special keywords that will be substituted with the metadata you specify. These are listed below, and are also listed in the configuration window.


Gets replaced by the artist name (e.g. "Our Lady Peace")


Gets replaced by the album name (e.g. "Gravity")


Gets replaced by the artist name (e.g. "Our Lady Peace")


Gets replaced by the unpadded track number (e.g. "4")


Gets replaced by the padded track number (e.g. "04")


Gets replaced by the default extension for the file type (e.g. "ogg")

So a full specification might be {ARTIST} - {ALBUM} - {PTN} - {TRACK}.{EXT}.

You should also note that you may use the parts of the file name specification as directories too. So we could also have {ARTIST}/{ALBUM}/{PTN} - {TRACK}.{EXT}. If the directories do not exist they will be created automatically for you.

Output Directory

This option changes where files are saved. They will be automatically moved to this directory if it is specified. Any necessary subdirectories specified in the File Name Format will be created under this directory.

Copy MP3s Across Filesystems

If this option is specified then if the source MP3 file and destination file are on separate mounts the file will be copied. Otherwise it will error out. This option exists because tagging many files and copying them accross filesystems can be slow.

Chapter 4. Extras

Right now the only additional feature that doesn't fit in with the usual process of tagging is CD Lookup. To look up a CD place it in your CD drive and click Tools->CD Lookup. The results will be displayed in a new window. This feature doesn't do anything more than that at this point.