Beets’ automatic metadata correcter is sophisticated but complicated and cryptic. This is a guide to help you through its myriad inputs and options.
I would like to sincerely apologize that the autotagger in beets is so fussy. It asks you a lot of complicated questions, insecurely asking that you verify nearly every assumption it makes. This means importing and correcting the tags for a large library can be an endless, tedious process. I’m sorry for this.
Maybe it will help to think of it as a tradeoff. By carefully examining every album you own, you get to become more familiar with your library, its extent, its variation, and its quirks. People used to spend hours lovingly sorting and resorting their shelves of LPs. In the iTunes age, many of us toss our music into a heap and forget about it. This is great for some people. But there’s value in intimate, complete familiarity with your collection. So instead of a chore, try thinking of correcting tags as quality time with your music collection. That’s what I do.
One practical piece of advice: because beets’ importer runs in multiple threads, it queues up work in the background while it’s waiting for you to respond. So if you find yourself waiting for beets for a few seconds between every question it asks you, try walking away from the computer for a while, making some tea, and coming back. Beets will have a chance to catch up with you and will ask you questions much more quickly.
Back to the guide.
Beets’ tagger is invoked using the beet import command. Point it at a directory and it imports the files into your library, tagging them as it goes (unless you pass --noautotag, of course). There are several assumptions beets currently makes about the music you import. In time, we’d like to remove all of these limitations.
Your music should be organized by album into directories. That is, the tagger assumes that each album is in a single directory. These directories can be arbitrarily deep (like music/2010/hiphop/seattle/freshespresso/glamour), but any directory with music files in it is interpreted as a separate album. This means that your flat directory of six thousand uncategorized MP3s won’t currently be autotaggable. (This will change eventually.)
There is one exception to this rule: directories that look like separate parts of a multi-disc album are tagged together as a single release. If two adjacent albums have a common prefix, followed by “disc,” “disk,” or “CD” and then a number, they are tagged together.
The music may have bad tags, but it’s not completely untagged. This is because beets by default infers tags based on existing metadata. But this is not a hard and fast rule—there are a few ways to tag metadata-poor music:
- You can use the E option described below to search in MusicBrainz for a specific album or song.
- The Acoustid plugin extends the autotagger to use acoustic fingerprinting to find information for arbitrary audio. Install that plugin if you’re willing to spend a little more CPU power to get tags for unidentified albums. (But be aware that it does slow down the process.)
- The FromFilename plugin adds the ability to guess tags from the filenames. Use this plugin if your tracks have useful names (like “03 Call Me Maybe.mp3”) but their tags don’t reflect that.
Currently, MP3, AAC, FLAC, ALAC, Ogg Vorbis, Monkey’s Audio, WavPack, Musepack, Windows Media, and Opus files are supported. (Do you use some other format? Let me know!)
Now that that’s out of the way, let’s tag some music.
To import music, just say beet import MUSICDIR. There are, of course, a few command-line options you should know:
So you import an album into your beets library. It goes like this:
$ beet imp witchinghour
Tagging:
Ladytron - Witching Hour
(Similarity: 98.4%)
* Last One Standing -> The Last One Standing
* Beauty -> Beauty*2
* White Light Generation -> Whitelightgenerator
* All the Way -> All the Way...
Here, beets gives you a preview of the album match it has found. It shows you which track titles will be changed if the match is applied. In this case, beets has found a match and thinks it’s a good enough match to proceed without asking your permission. It has reported the similarity for the match it’s found. Similarity is a measure of how well-matched beets thinks a tagging option is. 100% similarity means a perfect match 0% indicates a truly horrible match.
In this case, beets has proceeded automatically because it found an option with very high similarity (98.4%). But, as you’ll notice, if the similarity isn’t quite so high, beets will ask you to confirm changes. This is because beets can’t be very confident about more dissimilar matches, and you (as a human) are better at making the call than a computer. So it occasionally asks for help.
When beets needs your input about a match, it says something like this:
Tagging:
Beirut - Lon Gisland
(Similarity: 94.4%)
* Scenic World (Second Version) -> Scenic World
[A]pply, More candidates, Skip, Use as-is, as Tracks, Enter search, or aBort?
When beets asks you this question, it wants you to enter one of the capital letters: A, M, S, U, T, E, or B. That is, you can choose one of the following:
Note that the option with [B]rackets is the default—so if you want to apply the changes, you can just hit return without entering anything.
If you choose the M option, or if beets isn’t very confident about any of the choices it found, it will present you with a list of choices (called candidates), like so:
Finding tags for "Panther - Panther".
Candidates:
1. Panther - Yourself (66.8%)
2. Tav Falco's Panther Burns - Return of the Blue Panther (30.4%)
# selection (default 1), Skip, Use as-is, or Enter search, or aBort?
Here, you have many of the same options as before, but you can also enter a number to choose one of the options that beets has found. Don’t worry about guessing—beets will show you the proposed changes and ask you to confirm them, just like the earlier example. As the prompt suggests, you can just hit return to select the first candidate.
If beets finds an album or item in your library that seems to be the same as the one you’re importing, you may see a prompt like this:
This album is already in the library!
[S]kip new, Keep both, Remove old?
Beets wants to keep you safe from duplicates, which can be a real pain, so you have three choices in this situation. You can skip importing the new music, choosing to keep the stuff you already have in your library; you can keep both the old and the new music; or you can remove the existing music and choose the new stuff. If you choose that last “trump” option, any duplicates will be removed from your library database—and, if the corresponding files are located inside of your beets library directory, the files themselves will be deleted as well.
If you choose to keep two identically-named albums, beets can avoid storing both in the same directory. See Album Disambiguation for details.
You may have noticed by now that beets’ autotagger works pretty well for most files, but can get confused when files don’t have any metadata (or have wildly incorrect metadata). In this case, you need acoustic fingerprinting, a technology that identifies songs from the audio itself. With fingerprinting, beets can autotag files that have very bad or missing tags. The “chroma” plugin, distributed with beets, uses the Chromaprint open-source fingerprinting technology, but it’s disabled by default. That’s because it’s sort of tricky to install. See the Chromaprint/Acoustid Plugin page for a guide to getting it set up.
Before you jump into acoustic fingerprinting with both feet, though, give beets a try without it. You may be surprised at how well metadata-based matching works.
Aside from the basic stuff, beets can optionally fetch more specialized metadata. As a rule, plugins are responsible for getting information that doesn’t come directly from the MusicBrainz database. This includes album cover art, song lyrics, and musical genres. Check out the list of plugins to pick and choose the data you want.
If you’re having trouble tagging a particular album with beets, check to make sure the album is present in the MusicBrainz database. You can search on their site to make sure it’s cataloged there. If not, anyone can edit MusicBrainz—so consider adding the data yourself.
If you think beets is ignoring an album that’s listed in MusicBrainz, please file a bug report.
If I haven’t made the process clear, please drop me an email and I’ll try to improve this guide.