AFT: What is it?

Most people do not have static music collections; songs are always being renamed and moved. With most other media players, renaming a file or moving it from folder to folder causes the player to lose track of the file, forcing you to re-add the file to your playlist and possibly to lose any statistics about that song that you may have accumulated. This is time-consuming and annoying. Amarok has implemented file tracking features to cope with this common use-case, allowing Amarok to track your songs as you rename and move your files (referred to as AFT for the rest of this page). Parts of Amarok that can take advantage of this file-tracking behavior are "AFT-enabled".

Currently, Amarok's playlist, statistics, and cached lyrics are AFT-enabled. Playlist functionality includes AFT support for in-line tag editing, the Tag Dialog, and playback. Statistics will track files as they are moved around; you can even move a file out of a collection folder, and put it back in somewhere else and have the stats update to the new location!

How does it work?

Amarok's collection scanner, with incremental updates enabled, already detects additions and deletions of files in your collection folders and updates the collection automatically. With AFT, when files are scanned by Amarok's collection scanner, a unique hash (ID number) is either read from the file or calculated from the file. Using this hash, Amarok can check if a file that is being added to the collection is really a file that has simply been renamed or moved. Amarok's playlist and its statistics and lyrics tables are then updated with the new file name information, allowing you to manage your files without having to manage Amarok, or worry about losing years of statistics information!

Types of AFT Tracking

There are two types of AFT tracking: embedded, and non-embedded.

Embedded AFT Tracking

Using embedded tracking, a hash value is written into the metadata of your files, into fields specifically reserved by many tag formats for this information. Not all file types can use this type of tracking; currently only MPEG files that use ID3v2 tags, Ogg Vorbis, FLAC, and Ogg FLAC files are supported. This type of tracking is extremely robust; unless you remove the UID entries from your Amarok database or the file's metadata, Amarok will never lose the file. Duplicated files can be tracked separately by creating different hashes for the files.

Non-Embedded AFT Tracking

Using non-embedded tracking, the hash value is calculated from several read-only properties of the file, including the file length and a portion of its data. No modification of your files are required.

Cases in which non-embedded tracking can fail

Both editing a file (i.e. its tags) and renaming it outside of Amarok. AFT can handle either of these cases singularly, but not both at once. As a result you should always rescan the file after performing one operation or the other to ensure that AFT can track it.
Two identical copies of a file. Only one will be tracked.

Re-Scanning

Note: Because the incremental scanner uses mtimes (modify times) of the selected directories to determine what to rescan, and not of the individual files, if you modify the tags of a file outside of Amarok, the incremental scanner will not re-scan that directory. If you then move one of these files, the tracking will fail.

Therefore, if you want tracking to work after you've modified files outside of Amarok you should either:

manually run a full rescan of your files,
touch the directory that the file resides in (works on most Unix/Linux/Mac filesystems), or
right-click the file folder in Settings -> Configure Amarok -> Collection to individually rescan it, if it was previously selected as part of your Collection.

Using MusicBrainz identifiers

Amarok can now use embedded MusicBrainz track identifiers for embedded tracking functionality. There is one "issue" that you can run into when using MusicBrainz identifiers: since they identify tracks based on characteristics of the audio data, if you have the identical track in different formats they may still have the same exact unique identifier. As a result, Amarok may become confused and only scan one of the tracks when scanning in your files; or it may even flip-flop back and forth between which of the two formats are contained in the collection.

For this reason, identifiers created with the amarok_afttagger program have precedence, as they guarantee file tracking as opposed to song tracking, so if you are running into this issue and the behavior is undesired (after all, depending on your particular needs, you may actually wish to track songs rather than files) then simply tag your files with the amarok_afttagger program and these identifiers will take precedence. Likewise, if you don't care which format of the song is put into Amarok's collection and played, you can simply remove any Amarok-generated embedded identifiers using the amarok_afttagger program, and let the tracking happen via MusicBrainz identifiers.

How do I turn it on?

You don't turn on non-embedded AFT tracking -- it's already enabled for every single file in your collection. Enjoy.

If you want the superior file-tracking features of embedded AFT tracking, you use a helper program installed with Amarok called amarok_afttagger. Pass in a list of files and/or directories to write tags to the supported files. You can also regenerate new IDs, or remove IDs from your files with this program. For more information on available features of the program, run

amarok_afttagger --help

. Once you run the program on your files, perform a full rescan in Amarok to pull the new identifiers into the database, and you're set to go.

Safety

amarok_afttagger uses the tried and tested TagLib library. This library is used in many media applications across multiple platforms, and is well-regarded.

When performing file operations, amarok_afttagger uses an internal library called SafeFileSaver. This uses hash-based checksums and filesystem atomicity guarantees of certain operations to ensure that the file that is being modified by amarok_afttagger is never being modified by another process at the same time. This is the main reason that the program is slow, but the slowness is worth the safety.

In short, the program is believed to be very safe. The author has used it to write identifiers -- and rewrite, multiple times, for testing purposes -- to thousands of files, without any problems.

It's not working for me / It works great and I want to give kudos

No problem. Send email to mitchell @t kde d.t org, and please put AFT somewhere in the subject line. You can also file a bug at bugs.kde.org. Thanks!