beets: the music geek’s media organizer¶

Installing¶

You will need Python. (Beets is written for Python 2.7, but it works with 2.6 as well. Python 3.x is not yet supported.)

• Mac OS X v10.7 (Lion) and 10.8 (Mountain Lion) include Python 2.7 out of the box; Snow Leopard ships with Python 2.6.
• On Debian or Ubuntu, depending on the version, beets is available as an official package (Debian details, Ubuntu details), so try typing: apt-get install beets. But the version in the repositories might lag behind, so make sure you read the right version of these docs. If you want the latest version, you can get everything you need to install with pip as described below by running: apt-get install python-dev python-pip
• On Arch Linux, beets is in [community], so just run pacman -S beets. (There’s also a bleeding-edge dev package in the AUR, which will probably set your computer on fire.)
• For Gentoo Linux, beets is in Portage as media-sound/beets. Just run emerge beets to install. There are several USE flags available for optional plugin dependencies.
• On FreeBSD, there’s a beets port at audio/beets.
• For Slackware, there’s a SlackBuild available.

If you have pip, just say pip install beets (you might need sudo in front of that). On Arch, you’ll need to use pip2 instead of pip.

To install without pip, download beets from its PyPI page and run python setup.py install in the directory therein.

The best way to upgrade beets to a new version is by running pip install -U beets. You may want to follow @b33ts on Twitter to hear about progress on new versions.

Configuring¶

You’ll want to set a few basic options before you start using beets. The configuration is stored in a text file. You can show its location by running beet config -p, though it may not exist yet. Run beet config -e to edit the configuration in your favorite text editor. The file will start out empty, but here’s good place to start:

directory: ~/music
library: ~/data/musiclibrary.blb

Change that first path to a directory where you’d like to keep your music. Then, for library, choose a good place to keep a database file that keeps an index of your music.

The default configuration assumes you want to start a new organized music folder (that directory above) and that you’ll copy cleaned-up music into that empty folder using beets’ import command (see below). But you can configure beets to behave many other ways:

• Start with a new empty directory, but move new music in instead of copying it (saving disk space). Put this in your config file:

  import:
      move: yes
  

• Keep your current directory structure; importing should never move or copy files but instead just correct the tags on music. Put the line copy: no under the import: heading in your config file to disable any copying or renaming. Make sure to point directory at the place where your music is currently stored.

• Keep your current directory structure and do not correct files’ tags: leave files completely unmodified on your disk. (Corrected tags will still be stored in beets’ database, and you can use them to do renaming or tag changes later.) Put this in your config file:

  import:
      copy: no
      write: no
  

  to disable renaming and tag-writing.

There are approximately six million other configuration options you can set here, including the directory and file naming scheme. See Configuration for a full reference.

Importing Your Library¶

There are two good ways to bring your existing library into beets. You can either: (a) quickly bring all your files with all their current metadata into beets’ database, or (b) use beets’ highly-refined autotagger to find canonical metadata for every album you import. Option (a) is really fast, but option (b) makes sure all your songs’ tags are exactly right from the get-go. The point about speed bears repeating: using the autotagger on a large library can take a very long time, and it’s an interactive process. So set aside a good chunk of time if you’re going to go that route. For more on the interactive tagging process, see Using the Auto-Tagger.

If you’ve got time and want to tag all your music right once and for all, do this:

$ beet import /path/to/my/music

(Note that by default, this command will copy music into the directory you specified above. If you want to use your current directory structure, set the import.copy config option.) To take the fast, un-autotagged path, just say:

$ beet import -A /my/huge/mp3/library

Note that you just need to add -A for “don’t autotag”.

Adding More Music¶

If you’ve ripped or... otherwise obtained some new music, you can add it with the beet import command, the same way you imported your library. Like so:

$ beet import ~/some_great_album

This will attempt to autotag the new album (interactively) and add it to your library. There are, of course, more options for this command—just type beet help import to see what’s available.

Seeing Your Music¶

If you want to query your music library, the beet list (shortened to beet ls) command is for you. You give it a query string, which is formatted something like a Google search, and it gives you a list of songs. Thus:

$ beet ls the magnetic fields
The Magnetic Fields - Distortion - Three-Way
The Magnetic Fields - Distortion - California Girls
The Magnetic Fields - Distortion - Old Fools
$ beet ls hissing gronlandic
of Montreal - Hissing Fauna, Are You the Destroyer? - Gronlandic Edit
$ beet ls bird
The Knife - The Knife - Bird
The Mae Shi - Terrorbird - Revelation Six
$ beet ls album:bird
The Mae Shi - Terrorbird - Revelation Six

As you can see, search terms by default search all attributes of songs. (They’re also implicitly joined by ANDs: a track must match all criteria in order to match the query.) To narrow a search term to a particular metadata field, just put the field before the term, separated by a : character. So album:bird only looks for bird in the “album” field of your songs. (Need to know more? Queries will answer all your questions.)

The beet list command has another useful option worth mentioning, -a, which searches for albums instead of songs:

$ beet ls -a forever
Bon Iver - For Emma, Forever Ago
Freezepop - Freezepop Forever

So handy!

Beets also has a stats command, just in case you want to see how much music you have:

$ beet stats
Tracks: 13019
Total time: 4.9 weeks
Total size: 71.1 GB
Artists: 548
Albums: 1094

Keep Playing¶

This is only the beginning of your long and prosperous journey with beets. To keep learning, take a look at Advanced Awesomeness for a sampling of what else is possible. You’ll also want to glance over the Command-Line Interface page for a more detailed description of all of beets’ functionality. (Like deleting music! That’s important.)

Also, check out beets’ plugins. The real power of beets is in its extensibility—with plugins, beets can do almost anything for your music collection.

You can always get help using the beet help command. The plain beet help command lists all the available commands; then, for example, beet help import gives more specific help about the import command.

Please let me know what you think of beets via the mailing list or Twitter.

An Apology and a Brief Interlude¶

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.

Overview¶

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.

  There are, however, a couple of exceptions to this rule:

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

  Second, if you have jumbled directories containing more than one album, you can ask beets to split them apart for you based on their metadata. Use either the --group-albums command-line flag or the G interactive option described below.

• 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? Please file a feature request!)

Now that that’s out of the way, let’s tag some music.

Options¶

To import music, just say beet import MUSICDIR. There are, of course, a few command-line options you should know:

• beet import -A: don’t try to autotag anything; just import files (this goes much faster than with autotagging enabled)
• beet import -W: when autotagging, don’t write new tags to the files themselves (just keep the new metadata in beets’ database)
• beet import -C: don’t copy imported files to your music directory; leave them where they are
• beet import -l LOGFILE: write a message to LOGFILE every time you skip an album or choose to take its tags “as-is” (see below) or the album is skipped as a duplicate; this lets you come back later and reexamine albums that weren’t tagged successfully
• beet import -q: quiet mode. Never prompt for input and, instead, conservatively skip any albums that need your opinion. The -ql combination is recommended.
• beet import -t: timid mode, which is sort of the opposite of “quiet.” The importer will ask your permission for everything it does, confirming even very good matches with a prompt.
• beet import -p: automatically resume an interrupted import. The importer keeps track of imports that don’t finish completely (either due to a crash or because you stop them halfway through) and, by default, prompts you to decide whether to resume them. The -p flag automatically says “yes” to this question. Relatedly, -P flag automatically says “no.”
• beet import -s: run in singleton mode, tagging individual tracks instead of whole albums at a time. See the “as Tracks” choice below. This means you can use beet import -AC to quickly add a bunch of files to your library without doing anything to them.
• beet import -g: assume there are multiple albums contained in each directory. The tracks contained a directory are grouped by album artist and album name and you will be asked to import each of these groups separately. See the “Group albums” choice below.

Similarity¶

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.

Choices¶

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, G, E, or B. That is, you can choose one of the following:

• A: Apply the suggested changes shown and move on.
• M: Show more options. (See the Candidates section, below.)
• S: Skip this album entirely and move on to the next one.
• U: Import the album without changing any tags. This is a good option for albums that aren’t in the MusicBrainz database, like your friend’s operatic faux-goth solo record that’s only on two CD-Rs in the universe.
• T: Import the directory as singleton tracks, not as an album. Choose this if the tracks don’t form a real release—you just have one or more loner tracks that aren’t a full album. This will temporarily flip the tagger into singleton mode, which attempts to match each track individually.
• G: Group tracks in this directory by album artist and album and import groups as albums. If the album artist for a track is not set then the artist is used to group that track. For each group importing proceeds as for directories. This is helpful if a directory contains multiple albums.
• E: Enter an artist and album to use as a search in the database. Use this option if beets hasn’t found any good options because the album is mistagged or untagged.
• B: Cancel this import task altogether. No further albums will be tagged; beets shuts down immediately. The next time you attempt to import the same directory, though, beets will ask you if you want to resume tagging where you left off.

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.

Candidates¶

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.

Duplicates¶

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.

Fingerprinting¶

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.

Album Art, Lyrics, Genres and Such¶

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.

Missing Albums?¶

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.

I Hope That Makes Sense¶

If I haven’t made the process clear, please send an email to the mailing list and I’ll try to improve this guide.

Fetch album art, genres, and lyrics¶

Beets can help you fill in more than just the basic taxonomy metadata that comes from MusicBrainz. Plugins can provide album art, lyrics, and genres from databases around the Web.

If you want beets to get any of this data automatically during the import process, just enable any of the three relevant plugins (see Plugins). For example, put this line in your config file to enable all three:

plugins: fetchart lyrics lastgenre

Each plugin also has a command you can run to fetch data manually. For example, if you want to get lyrics for all the Beatles tracks in your collection, just type beet lyrics beatles after enabling the plugin.

Read more about using each of these plugins:

• FetchArt Plugin (and its accompanying EmbedArt Plugin)
• Lyrics Plugin
• LastGenre Plugin

Customize your file and folder names¶

Beets uses an extremely flexible template system to name the folders and files that organize your music in your filesystem. Take a look at Path Format Configuration for the basics: use fields like $year and $title to build up a naming scheme. But if you need more flexibility, there are two features you need to know about:

• Template functions are simple expressions you can use in your path formats to add logic to your names. For example, you can get an artist’s first initial using %upper{%left{$albumartist,1}}.
• If you need more flexibility, the Inline Plugin lets you write snippets of Python code that generate parts of your filenames. The equivalent code for getting an artist initial with the inline plugin looks like initial: albumartist[0].upper().

If you already have music in your library and want to update their names according to a new scheme, just run the move command to rename everything.

Stream your music to another computer¶

Sometimes it can be really convenient to store your music on one machine and play it on another. For example, I like to keep my music on a server at home but play it at work (without copying my whole library locally). The Web Plugin makes streaming your music easy—it’s sort of like having your own personal Spotify.

First, enable the web plugin (see Plugins). Run the server by typing beet web and head to http://localhost:8337 in a browser. You can browse your collection with queries and, if your browser supports it, play music using HTML5 audio.

But for a great listening experience, pair beets with the Tomahawk music player. Tomahawk lets you listen to music from many different sources, including a beets server. Just download Tomahawk and open its settings to connect it to beets. A post on the beets blog has a more detailed guide.

Transcode music files for media players¶

Do you ever find yourself transcoding high-quality rips to a lower-bitrate, lossy format for your phone or music player? Beets can help with that.

You’ll first need to install ffmpeg. Then, enable beets’ Convert Plugin. Set a destination directory in your config file like so:

convert:
    dest: ~/converted_music

Then, use the command beet convert QUERY to transcode everything matching the query and drop the resulting files in that directory, named according to your path formats. For example, beet convert long winters will move over everything by the Long Winters for listening on the go.

The plugin has many more dials you can fiddle with to get your conversions how you like them. Check out its documentation.

Store any data you like¶

The beets database keeps track of a long list of built-in fields, but you’re not limited to just that list. Say, for example, that you like to categorize your music by the setting where it should be played. You can invent a new context attribute store this. Set the field using the modify command:

beet modify context=party artist:'beastie boys'

And then query your music just as you would with any other field:

beet ls context:mope

You can even use these fields in your filenames (see Path Format Configuration).

And, unlike built-in fields, such fields can be removed:

beet modify context! artist:'beastie boys'

Read more than you ever wanted to know about the flexible attributes feature on the beets blog.

Choose a path style manually for some music¶

Sometimes, you need to categorize some songs differently in your file system. For example, you might want to group together all the music you don’t really like but keep around to play for friends and family. This is, of course, impossible to determine automatically using metadata from MusicBrainz.

Instead, use a flexible attribute (see above) to store a flag on the music you want to categorize, like so:

beet modify bad=1 christmas

Then, you can query on this field in your path formats to sort this music differently. Put something like this in your configuration file:

paths:
    bad:1: Bad/$artist/$title

Used together, flexible attributes and path format conditions let you sort your music by any criteria you can imagine.

What’s Migrated¶

Automatic migration is most important for the configuration file, since its syntax is completely different, but two other files are also moved. This is to consolidate everything beets needs in a single directory instead of leaving it messily strewn about in your home directory.

First, the library database file was at ~/.beetsmusic.blb on Unix and %APPDATA%\beetsmusic.blb on Windows. This file will be copied to library.db in the same directory as your new configuration file. Finally, the runtime state file, which keeps track of interrupted and incremental imports, was previously known as ~/.beetsstate; it is copied to a file called state.pickle.

Feel free to remove the old files once they’ve been copied to their new homes.

Manual Migration¶

If you find you need to re-run the migration process, just type beet migrate in your shell. This will migrate the configuration file, the database, and the runtime state file all over again. Unlike automatic migration, no step is suppressed if the file already exists. If you already have a config.yaml, for example, it will be renamed to make room for the newly migrated configuration.

Commands¶

Here are the built-in commands available in beets:

Also be sure to see the global flags.

beet import [-CWAPRqst] [-l LOGPATH] PATH...
beet import [options] -L QUERY

beet list [-apf] QUERY

beet remove [-ad] QUERY

beet modify [-MWay] QUERY [FIELD=VALUE...] [FIELD!...]

beet move [-ca] [-d DIR] QUERY

beet update [-aM] QUERY

beet write [-ap] [QUERY]

beet stats [-e] [QUERY]

beet fields

beet config [-pd]
beet config -e

Global Flags¶

Beets has a few “global” flags that affect all commands. These must appear between the executable name (beet) and the command—for example, beet -v import ....

• -l LIBPATH: specify the library database file to use.
• -d DIRECTORY: specify the library root directory.
• -v: verbose mode; prints out a deluge of debugging information. Please use this flag when reporting bugs.
• -c FILE: read a specified YAML configuration file.

Beets also uses the BEETSDIR environment variable to look for configuration and data.

Shell Completion¶

Beets includes support for shell command completion. The command beet completion prints out a bash 3.2 script; to enable completion put a line like this into your .bashrc or similar file:

eval "$(beet completion)"

Or, to avoid slowing down your shell startup time, you can pipe the beet completion output to a file and source that instead.

You will also need to source the bash-completion script, which is probably available via your package manager. On OS X, you can install it via Homebrew with brew install bash-completion; Homebrew will give you instructions for sourcing the script.

The completion script suggests names of subcommands and (after typing -) options of the given command. If you are using a command that accepts a query, the script will also complete field names.

beet list ar[TAB]
# artist:  artist_credit:  artist_sort:  artpath:
beet list artp[TAB]
beet list artpath\:

(Don’t worry about the slash in front of the colon: this is a escape sequence for the shell and won’t be seen by beets.)

Completion of plugin commands only works for those plugins that were enabled when running beet completion. If you add a plugin later on you will want to re-generate the script.

Global Options¶

These options control beets’ global operation.

pluginpath:
    - /path/one
    - /path/two

replace:
    '[\\/]': _
    '^\.': _
    '[\x00-\x1f]': _
    '[<>:"\?\*\|]': _
    '\.$': _
    '\s+$': ''
    '^\s+': ''

paths:
    default: $albumartist/$album%aunique{}/$disc-$track $title

Importer Options¶

The options that control the import command are indented under the import: key. For example, you might have a section in your configuration file that looks like this:

import:
    write: yes
    copy: yes
    resume: no

These options are available in this section:

MusicBrainz Options¶

If you run your own MusicBrainz server, you can instruct beets to use it instead of the main server. Use the host and ratelimit options under a musicbrainz: header, like so:

musicbrainz:
    host: localhost:5000
    ratelimit: 100

The host key, of course, controls the Web server hostname (and port, optionally) that will be contacted by beets (default: musicbrainz.org). The ratelimit option, an integer, controls the number of Web service requests per second (default: 1). Do not change the rate limit setting if you’re using the main MusicBrainz server—on this public server, you’re limited to one request per second.

Autotagger Matching Options¶

You can configure some aspects of the logic beets uses when automatically matching MusicBrainz results under the match: section. To control how tolerant the autotagger is of differences, use the strong_rec_thresh option, which reflects the distance threshold below which beets will make a “strong recommendation” that the metadata be used. Strong recommendations are accepted automatically (except in “timid” mode), so you can use this to make beets ask your opinion more or less often.

The threshold is a distance value between 0.0 and 1.0, so you can think of it as the opposite of a similarity value. For example, if you want to automatically accept any matches above 90% similarity, use:

match:
    strong_rec_thresh: 0.10

The default strong recommendation threshold is 0.04.

The medium_rec_thresh and rec_gap_thresh options work similarly. When a match is above the medium recommendation threshold or the distance between it and the next-best match is above the gap threshold, the importer will suggest that match but not automatically confirm it. Otherwise, you’ll see a list of options to choose from.

match:
    max_rec:
        missing_tracks: medium
        unmatched_tracks: medium

match:
    preferred:
        countries: ['US', 'GB|UK']
        media: ['CD', 'Digital Media|File']
        original_year: yes

match:
    ignored: missing_tracks unmatched_tracks

Path Format Configuration¶

You can also configure the directory hierarchy beets uses to store music. These settings appear under the paths: key. Each string is a template string that can refer to metadata fields like $artist or $title. The filename extension is added automatically. At the moment, you can specify three special paths: default for most releases, comp for “various artist” releases with no dominant artist, and singleton for non-album tracks. The defaults look like this:

paths:
    default: $albumartist/$album%aunique{}/$track $title
    singleton: Non-Album/$artist/$title
    comp: Compilations/$album%aunique{}/$track $title

Note the use of $albumartist instead of $artist; this ensure that albums will be well-organized. For more about these format strings, see Path Formats. The aunique{} function ensures that identically-named albums are placed in different directories; see Album Disambiguation for details.

In addition to default, comp, and singleton, you can condition path queries based on beets queries (see Queries). This means that a config file like this:

paths:
    albumtype:soundtrack: Soundtracks/$album/$track $title

will place soundtrack albums in a separate directory. The queries are tested in the order they appear in the configuration file, meaning that if an item matches multiple queries, beets will use the path format for the first matching query.

Note that the special singleton and comp path format conditions are, in fact, just shorthand for the explicit queries singleton:true and comp:true. In contrast, default is special and has no query equivalent: the default format is only used if no queries match.

Configuration Location¶

The beets configuration file is usually located in a standard location that depends on your OS, but there are a couple of ways you can tell beets where to look.

Example¶

Here’s an example file:

library: /var/music.blb
directory: /var/mp3
import:
    copy: yes
    write: yes
    resume: ask
    quiet_fallback: skip
    timid: no
    log: beetslog.txt
ignore: .AppleDouble ._* *~ .DS_Store
art_filename: albumart
plugins: bpd
pluginpath: ~/beets/myplugins
threaded: yes
color: yes

paths:
    default: $genre/$albumartist/$album/$track $title
    singleton: Singletons/$artist - $title
    comp: $genre/$album/$track $title
    albumtype:soundtrack: Soundtracks/$album/$track $title

A Note About Artists¶

Note that in path formats, you almost certainly want to use $albumartist and not $artist. The latter refers to the “track artist” when it is present, which means that albums that have tracks from different artists on them (like Stop Making Sense, for example) will be placed into different folders! Continuing with the Stop Making Sense example, you’ll end up with most of the tracks in a “Talking Heads” directory and one in a “Tom Tom Club” directory. You probably don’t want that! So use $albumartist.

As a convenience, however, beets allows $albumartist to fall back to the value for $artist and vice-versa if one tag is present but the other is not.

Template Functions¶

Beets path formats also support function calls, which can be used to transform text and perform logical manipulations. The syntax for function calls is like this: %func{arg,arg}. For example, the upper function makes its argument upper-case, so %upper{beets rocks} will be replaced with BEETS ROCKS. You can, of course, nest function calls and place variable references in function arguments, so %upper{$artist} becomes the upper-case version of the track’s artists.

These functions are built in to beets:

• %lower{text}: Convert text to lowercase.
• %upper{text}: Convert text to UPPERCASE.
• %title{text}: Convert text to Title Case.
• %left{text,n}: Return the first n characters of text.
• %right{text,n}: Return the last n characters of text.
• %if{condition,text} or %if{condition,truetext,falsetext}: If condition is nonempty (or nonzero, if it’s a number), then returns the second argument. Otherwise, returns the third argument if specified (or nothing if falsetext is left off).
• %asciify{text}: Convert non-ASCII characters to their ASCII equivalents. For example, “café” becomes “cafe”. Uses the mapping provided by the unidecode module.
• %aunique{identifiers,disambiguators}: Provides a unique string to disambiguate similar albums in the database. See Album Disambiguation, below.
• %time{date_time,format}: Return the date and time in any format accepted by strftime. For example, to get the year some music was added to your library, use %time{$added,%Y}.

Plugins can extend beets with more template functions (see Template functions and values provided by plugins).

Album Disambiguation¶

Occasionally, bands release two albums with the same name (c.f. Crystal Castles, Weezer, and any situation where a single has the same name as an album or EP). Beets ships with special support, in the form of the %aunique{} template function, to avoid placing two identically-named albums in the same directory on disk.

The aunique function detects situations where two albums have some identical fields and emits text from additional fields to disambiguate the albums. For example, if you have both Crystal Castles albums in your library, %aunique{} will expand to “[2008]” for one album and “[2010]” for the other. The function detects that you have two albums with the same artist and title but that they have different release years.

For full flexibility, the %aunique function takes two arguments, each of which are whitespace-separated lists of album field names: a set of identifiers and a set of disambiguators. Any group of albums with identical values for all the identifiers will be considered “duplicates”. Then, the function tries each disambiguator field, looking for one that distinguishes each of the duplicate albums from each other. The first such field is used as the result for %aunique. If no field suffices, an arbitrary number is used to distinguish the two albums.

The default identifiers are albumartist album and the default disambiguators are albumtype year label catalognum albumdisambig. So you can get reasonable disambiguation behavior if you just use %aunique{} with no parameters in your path forms (as in the default path formats), but you can customize the disambiguation if, for example, you include the year by default in path formats.

One caveat: When you import an album that is named identically to one already in your library, the first album—the one already in your library— will not consider itself a duplicate at import time. This means that %aunique{} will expand to nothing for this album and no disambiguation string will be used at its import time. Only the second album will receive a disambiguation string. If you want to add the disambiguation string to both albums, just run beet move (possibly restricted by a query) to update the paths for the albums.

Syntax Details¶

The characters $, %, {, }, and , are “special” in the path template syntax. This means that, for example, if you want a % character to appear in your paths, you’ll need to be careful that you don’t accidentally write a function call. To escape any of these characters (except {), prefix it with a $. For example, $$ becomes $; $% becomes %, etc. The only exception is ${, which is ambiguous with the variable reference syntax (like ${title}). To insert a { alone, it’s always sufficient to just type {.

If a value or function is undefined, the syntax is simply left unreplaced. For example, if you write $foo in a path template, this will yield $foo in the resulting paths because “foo” is not a valid field name. The same is true of syntax errors like unclosed {} pairs; if you ever see template syntax constructs leaking into your paths, check your template for errors.

If an error occurs in the Python code that implements a function, the function call will be expanded to a string that describes the exception so you can debug your template. For example, the second parameter to %left must be an integer; if you write %left{foo,bar}, this will be expanded to something like <ValueError: invalid literal for int()>.

Available Values¶

Here’s a list of the different values available to path formats. The current list can be found definitively by running the command beet fields. Note that plugins can add new (or replace existing) template values (see Template functions and values provided by plugins).

Ordinary metadata:

• title
• artist
• artist_sort: The “sort name” of the track artist (e.g., “Beatles, The” or “White, Jack”).
• artist_credit: The track-specific artist credit name, which may be a variation of the artist’s “canonical” name.
• album
• albumartist: The artist for the entire album, which may be different from the artists for the individual tracks.
• albumartist_sort
• albumartist_credit
• genre
• composer
• grouping
• year, month, day: The release date of the specific release.
• original_year, original_month, original_day: The release date of the original version of the album.
• track
• tracktotal
• disc
• disctotal
• lyrics
• comments
• bpm
• comp: Compilation flag.
• albumtype: The MusicBrainz album type; the MusicBrainz wiki has a list of type names.
• label
• asin
• catalognum
• script
• language
• country
• albumstatus
• media
• albumdisambig
• disctitle
• encoder

Audio information:

• length (in seconds)
• bitrate (in kilobits per second, with units: e.g., “192kbps”)
• format (e.g., “MP3” or “FLAC”)
• channels
• bitdepth (only available for some formats)
• samplerate (in kilohertz, with units: e.g., “48kHz”)

MusicBrainz and fingerprint information:

• mb_trackid
• mb_albumid
• mb_artistid
• mb_albumartistid
• mb_releasegroupid
• acoustid_fingerprint
• acoustid_id

Library metadata:

• mtime: The modification time of the audio file.
• added: The date and time that the music was added to your library.

Template functions and values provided by plugins¶

Beets plugins can provide additional fields and functions to templates. See the Plugins page for a full list of plugins. Some plugin-provided constructs include:

• $missing by Missing Plugin: The number of missing tracks per album.
• %bucket{text} by Bucket Plugin: Substitute a string by the range it belongs to.
• %the{text} by The Plugin: Moves English articles to ends of strings.

The Inline Plugin lets you define template fields in your beets configuration file using Python snippets. And for more advanced processing, you can go all-in and write a dedicated plugin to register your own fields and functions (see Writing Plugins).

Keyword¶

This command:

$ beet list love

will show all tracks matching the query string love. Any unadorned word like this matches anywhere in a track’s metadata, so you’ll see all the tracks with “love” in their title, in their album name, in the artist, and so on.

For example, this is what I might see when I run the command above:

Against Me! - Reinventing Axl Rose - I Still Love You Julie
Air - Love 2 - Do the Joy
Bag Raiders - Turbo Love - Shooting Stars
Bat for Lashes - Two Suns - Good Love
...

Combining Keywords¶

Multiple keywords are implicitly joined with a Boolean “and.” That is, if a query has two keywords, it only matches tracks that contain both keywords. For example, this command:

$ beet ls magnetic tomorrow

matches songs from the album “The House of Tomorrow” by The Magnetic Fields in my library. It doesn’t match other songs by the Magnetic Fields, nor does it match “Tomorrowland” by Walter Meego—those songs only have one of the two keywords I specified.

Specific Fields¶

Sometimes, a broad keyword match isn’t enough. Beets supports a syntax that lets you query a specific field—only the artist, only the track title, and so on. Just say field:value, where field is the name of the thing you’re trying to match (such as artist, album, or title) and value is the keyword you’re searching for.

For example, while this query:

$ beet list dream

matches a lot of songs in my library, this more-specific query:

$ beet list artist:dream

only matches songs by the artist The-Dream. One query I especially appreciate is one that matches albums by year:

$ beet list -a year:2012

Recall that -a makes the list command show albums instead of individual tracks, so this command shows me all the releases I have from this year.

Phrases¶

You can query for strings with spaces in them by quoting or escaping them using your shell’s argument syntax. For example, this command:

$ beet list the rebel

shows several tracks in my library, but these (equivalent) commands:

$ beet list "the rebel"
$ beet list the\ rebel

only match the track “The Rebel” by Buck 65. Note that the quotes and backslashes are not part of beets’ syntax; I’m just using the escaping functionality of my shell (bash or zsh, for instance) to pass the rebel as a single argument instead of two.

Regular Expressions¶

While ordinary keywords perform simple substring matches, beets also supports regular expression matching for more advanced queries. To run a regex query, use an additional : between the field name and the expression:

$ beet list 'artist::Ann(a|ie)'

That query finds songs by Anna Calvi and Annie but not Annuals. Similarly, this query prints the path to any file in my library that’s missing a track title:

$ beet list -p title::^$

To search all fields using a regular expression, just prefix the expression with a single :, like so:

$ beet list :Ho[pm]eless

Regular expressions are case-sensitive and build on Python’s built-in implementation. See Python’s documentation for specifics on regex syntax.

Numeric Range Queries¶

For numeric fields, such as year, bitrate, and track, you can query using one- or two-sided intervals. That is, you can find music that falls within a range of values. To use ranges, write a query that has two dots (..) at the beginning, middle, or end of a string of numbers. Dots in the beginning let you specify a maximum (e.g., ..7); dots at the end mean a minimum (4..); dots in the middle mean a range (4..7).

For example, this command finds all your albums that were released in the ‘90s:

$ beet list -a year:1990..1999

and this command finds MP3 files with bitrates of 128k or lower:

$ beet list format:MP3 bitrate:..128000

Date and Date Range Queries¶

Date-valued fields, such as added and mtime, have a special query syntax that lets you specify years, months, and days as well as ranges between dates.

Dates are written separated by hyphens, like year-month-day, but the month and day are optional. If you leave out the day, for example, you will get matches for the whole month.

Date intervals, like the numeric intervals described above, are separated by two dots (..). You can specify a start, an end, or both.

Here is an example that finds all the songs added in 2008:

$ beet ls -a 'added:2008'

Find all items added in the years 2008, 2009 and 2010:

$ beet ls 'added:2008..2010'

Find all items added before the year 2010:

$ beet ls 'added:..2009'

Find all items added on 2008-12-01 but before 2009-10-12:

$ beet ls 'added:2008-12..2009-10-11'

Find all items with a file modification time between 2008-12-01 and 2008-12-03:

$ beet ls 'mtime:2008-12-01..2008-12-02'

Path Queries¶

Sometimes it’s useful to find all the items in your library that are (recursively) inside a certain directory. Use the path: field to do this:

$ beet list path:/my/music/directory

In fact, beets automatically recognizes any query term containing a path separator (/ on POSIX systems) as a path query, so this command is equivalent:

$ beet list /my/music/directory

Note that this only matches items that are already in your library, so a path query won’t necessarily find all the audio files in a directory—just the ones you’ve already added to your beets library.

Add Commands to the CLI¶

Plugins can add new subcommands to the beet command-line interface. Define the plugin class’ commands() method to return a list of Subcommand objects. (The Subcommand class is defined in the beets.ui module.) Here’s an example plugin that adds a simple command:

from beets.plugins import BeetsPlugin
from beets.ui import Subcommand

my_super_command = Subcommand('super', help='do something super')
def say_hi(lib, opts, args):
    print "Hello everybody! I'm a plugin!"
my_super_command.func = say_hi

class SuperPlug(BeetsPlugin):
    def commands(self):
        return [my_super_command]

To make a subcommand, invoke the constructor like so: Subcommand(name, parser, help, aliases). The name parameter is the only required one and should just be the name of your command. parser can be an OptionParser instance, but it defaults to an empty parser (you can extend it later). help is a description of your command, and aliases is a list of shorthand versions of your command name.

You’ll need to add a function to your command by saying mycommand.func = myfunction. This function should take the following parameters: lib (a beets Library object) and opts and args (command-line options and arguments as returned by OptionParser.parse_args).

The function should use any of the utility functions defined in beets.ui. Try running pydoc beets.ui to see what’s available.

You can add command-line options to your new command using the parser member of the Subcommand class, which is an OptionParser instance. Just use it like you would a normal OptionParser in an independent script.

Listen for Events¶

Event handlers allow plugins to run code whenever something happens in beets’ operation. For instance, a plugin could write a log message every time an album is successfully autotagged or update MPD’s index whenever the database is changed.

You can “listen” for events using the BeetsPlugin.listen decorator. Here’s an example:

from beets.plugins import BeetsPlugin

class SomePlugin(BeetsPlugin):
    pass

@SomePlugin.listen('pluginload')
def loaded():
    print 'Plugin loaded!'

Pass the name of the event in question to the listen decorator. The events currently available are:

• pluginload: called after all the plugins have been loaded after the beet command starts
• import: called after a beet import command finishes (the lib keyword argument is a Library object; paths is a list of paths (strings) that were imported)
• album_imported: called with an Album object every time the import command finishes adding an album to the library. Parameters: lib, album
• item_copied: called with an Item object whenever its file is copied. Parameters: item, source path, destination path
• item_imported: called with an Item object every time the importer adds a singleton to the library (not called for full-album imports). Parameters: lib, item
• before_item_moved: called with an Item object immediately before its file is moved. Parameters: item, source path, destination path
• item_moved: called with an Item object whenever its file is moved. Parameters: item, source path, destination path
• item_removed: called with an Item object every time an item (singleton or album’s part) is removed from the library (even when its file is not deleted from disk).
• write: called with an Item object just before a file’s metadata is written to disk (i.e., just before the file on disk is opened). Event handlers may raise a library.FileOperationError exception to abort the write operation. Beets will catch that exception, print an error message and continue.
• after_write: called with an Item object after a file’s metadata is written to disk (i.e., just after the file on disk is closed).
• import_task_start: called when before an import task begins processing. Parameters: task (an ImportTask) and session (an ImportSession).
• import_task_apply: called after metadata changes have been applied in an import task. Parameters: task and session.
• import_task_choice: called after a decision has been made about an import task. This event can be used to initiate further interaction with the user. Use task.choice_flag to determine or change the action to be taken. Parameters: task and session.
• import_task_files: called after an import task finishes manipulating the filesystem (copying and moving files, writing metadata tags). Parameters: task and session.
• library_opened: called after beets starts up and initializes the main Library object. Parameter: lib.
• database_change: a modification has been made to the library database. The change might not be committed yet. Parameter: lib.
• cli_exit: called just before the beet command-line program exits. Parameter: lib.

The included mpdupdate plugin provides an example use case for event listeners.

Extend the Autotagger¶

Plugins in can also enhance the functionality of the autotagger. For a comprehensive example, try looking at the chroma plugin, which is included with beets.

A plugin can extend three parts of the autotagger’s process: the track distance function, the album distance function, and the initial MusicBrainz search. The distance functions determine how “good” a match is at the track and album levels; the initial search controls which candidates are presented to the matching algorithm. Plugins implement these extensions by implementing four methods on the plugin class:

• track_distance(self, item, info): adds a component to the distance function (i.e., the similarity metric) for individual tracks. item is the track to be matched (an Item object) and info is the TrackInfo object that is proposed as a match. Should return a (dist, dist_max) pair of floats indicating the distance.
• album_distance(self, items, album_info, mapping): like the above, but compares a list of items (representing an album) to an album-level MusicBrainz entry. items is a list of Item objects; album_info is an AlbumInfo object; and mapping is a dictionary that maps Items to their corresponding TrackInfo objects.
• candidates(self, items, artist, album, va_likely): given a list of items comprised by an album to be matched, return a list of AlbumInfo objects for candidate albums to be compared and matched.
• item_candidates(self, item, artist, album): given a singleton item, return a list of TrackInfo objects for candidate tracks to be compared and matched.
• album_for_id(self, album_id): given an ID from user input or an album’s tags, return a candidate AlbumInfo object (or None).
• track_for_id(self, track_id): given an ID from user input or a file’s tags, return a candidate TrackInfo object (or None).

When implementing these functions, you may want to use the functions from the beets.autotag and beets.autotag.mb modules, both of which have somewhat helpful docstrings.

Read Configuration Options¶

Plugins can configure themselves using the config.yaml file. You can read configuration values in two ways. The first is to use self.config within your plugin class. This gives you a view onto the configuration values in a section with the same name as your plugin’s module. For example, if your plugin is in greatplugin.py, then self.config will refer to options under the greatplugin: section of the config file.

For example, if you have a configuration value called “foo”, then users can put this in their config.yaml:

greatplugin:
    foo: bar

To access this value, say self.config['foo'].get() at any point in your plugin’s code. The self.config object is a view as defined by the Confit library.

If you want to access configuration values outside of your plugin’s section, import the config object from the beets module. That is, just put from beets import config at the top of your plugin and access values from there.

Add Path Format Functions and Fields¶

Beets supports function calls in its path format syntax (see Path Formats). Beets includes a few built-in functions, but plugins can register new functions by adding them to the template_funcs dictionary.

Here’s an example:

class MyPlugin(BeetsPlugin):
    def __init__(self):
        super(MyPlugin, self).__init__()
        self.template_funcs['initial'] = _tmpl_initial

def _tmpl_initial(text):
    if text:
        return text[0].upper()
    else:
        return u''

This plugin provides a function %initial to path templates where %initial{$artist} expands to the artist’s initial (its capitalized first character).

Plugins can also add template fields, which are computed values referenced as $name in templates. To add a new field, add a function that takes an Item object to the template_fields dictionary on the plugin object. Here’s an example that adds a $disc_and_track field:

class MyPlugin(BeetsPlugin):
    def __init__(self):
        super(MyPlugin, self).__init__()
        self.template_fields['disc_and_track'] = _tmpl_disc_and_track

def _tmpl_disc_and_track(item):
    """Expand to the disc number and track number if this is a
    multi-disc release. Otherwise, just exapnds to the track
    number.
    """
    if item.disctotal > 1:
        return u'%02i.%02i' % (item.disc, item.track)
    else:
        return u'%02i' % (item.track)

With this plugin enabled, templates can reference $disc_and_track as they can any standard metadata field.

This field works for item templates. Similarly, you can register album template fields by adding a function accepting an Album argument to the album_template_fields dict.

Extend MediaFile¶

MediaFile is the file tag abstraction layer that beets uses to make cross-format metadata manipulation simple. Plugins can add fields to MediaFile to extend the kinds of metadata that they can easily manage.

The MediaFile class uses MediaField descriptors to provide access to file tags. Have a look at the beets.mediafile source code to learn how to use this descriptor class. If you have created a descriptor you can add it through your plugins add_media_field() method.

BeetsPlugin.add_media_field(name, descriptor)¶

Add a field that is synchronized between media files and items.

When a media field is added item.write() will set the name property of the item’s MediaFile to item[name] and save the changes. Similarly item.read() will set item[name] to the value of the name property of the media file.

descriptor must be an instance of mediafile.MediaField.

Here’s an example plugin that provides a meaningless new field “foo”:

class FooPlugin(BeetsPlugin):
    def __init__(self):
        field = mediafile.MediaField(
            mediafile.MP3DescStorageStyle(u'foo')
            mediafile.StorageStyle(u'foo')
        )
        self.add_media_field('foo', field)

FooPlugin()
item = Item.from_path('/path/to/foo/tag.mp3')
assert item['foo'] == 'spam'

item['foo'] == 'ham'
item.write()
# The "foo" tag of the file is now "ham"

Add Import Pipeline Stages¶

Many plugins need to add high-latency operations to the import workflow. For example, a plugin that fetches lyrics from the Web would, ideally, not block the progress of the rest of the importer. Beets allows plugins to add stages to the parallel import pipeline.

Each stage is run in its own thread. Plugin stages run after metadata changes have been applied to a unit of music (album or track) and before file manipulation has occurred (copying and moving files, writing tags to disk). Multiple stages run in parallel but each stage processes only one task at a time and each task is processed by only one stage at a time.

Plugins provide stages as functions that take two arguments: config and task, which are ImportConfig and ImportTask objects (both defined in beets.importer). Add such a function to the plugin’s import_stages field to register it:

from beets.plugins import BeetsPlugin
class ExamplePlugin(BeetsPlugin):
    def __init__(self):
        super(ExamplePlugin, self).__init__()
        self.import_stages = [self.stage]
    def stage(self, config, task):
        print('Importing something!')

Extend the Query Syntax¶

You can add new kinds of queries to beets’ query syntax indicated by a prefix. As an example, beets already supports regular expression queries, which are indicated by a colon prefix—plugins can do the same.

To do so, define a subclass of the Query type from the beets.dbcore.query module. Then, in the queries method of your plugin class, return a dictionary mapping prefix strings to query classes.

One simple kind of query you can extend is the FieldQuery, which implements string comparisons on fields. To use it, create a subclass inheriting from that class and override the value_match class method. (Remember the @classmethod decorator!) The following example plugin declares a query using the @ prefix to delimit exact string matches. The plugin will be used if we issue a command like beet ls @something or beet ls artist:@something:

from beets.plugins import BeetsPlugin
from beets.dbcore import FieldQuery

class ExactMatchQuery(FieldQuery):
    @classmethod
    def value_match(self, pattern, val):
        return pattern == val

class ExactMatchPlugin(BeetsPlugin):
    def queries(self):
        return {
            '@': ExactMatchQuery
        }

The Library Class¶

class beets.library.Library(path, directory[, path_formats[, replacements]])¶

A database of music containing songs and albums.

items(query=None)¶

Get a sorted list of Item objects matching the given query.

albums(query=None)¶

Get a sorted list of Album objects matching the given query.

get_item(id)¶

Fetch an Item by its ID. Returns None if no match is found.

get_album(item_or_id)¶

Given an album ID or an item associated with an album, return an Album object for the album. If no such album exists, returns None.

add(obj)¶

Add the Item or Album object to the library database. Return the object’s new id.

add_album(items)¶

Create a new album consisting of a list of items.

The items are added to the database if they don’t yet have an ID. Return a new Album object. The list items must not be empty.

transaction()¶

Get a Transaction object for interacting directly with the underlying SQLite database.

lib = Library()
with lib.transaction() as tx:
    items = lib.items(query)
    lib.add_album(list(items))

Model Classes¶

The two model entities in beets libraries, Item and Album, share a base class, Model, that provides common functionality and ORM-like abstraction.

The fields model classes can be accessed using attributes (dots, as in item.artist) or items (brackets, as in item['artist']). The Model base class provides some methods that resemble dict objects.