Here are some answers to frequently-asked questions from IRC and elsewhere. Got a question that isn’t answered here? Try IRC, the mailing list, or filing an issue in the bug tracker.
Just run the move command. Use a query to rename a subset of your music or leave the query off to rename everything.
Enable the import log to automatically record whenever you skip an album or accept one “as-is”.
Alternatively, you can find all the albums in your library that are missing MBIDs using a command like this:
beet ls -a mb_albumid::^$
Assuming your files didn’t have MBIDs already, then this will roughly correspond to those albums that didn’t get autotagged.
Use the Inline Plugin along with the %if{} function to accomplish this:
plugins: inline
paths:
default: $albumartist/$album%aunique{}/%if{$multidisc,Disc $disc/}$track $title
item_fields:
multidisc: 1 if disctotal > 1 else 0
As of 1.0b11, beets tags multi-disc albums as a single unit. To get a good match, it needs to treat all of the album’s parts together as a single release.
To help with this, the importer uses a simple heuristic to guess when a directory represents a multi-disc album that’s been divided into multiple subdirectories. When it finds a situation like this, it collapses all of the items in the subdirectories into a single release for tagging.
The heuristic works by looking at the names of directories. If multiple subdirectories of a common parent directory follow the pattern “(title) disc (number) (...)” and the prefix (everything up to the number) is the same, the directories are collapsed together. One of the key words “disc” or “CD” must be present to make this work.
If you have trouble tagging a multi-disc album, consider the --flat flag (which treats a whole tree as a single album) or just putting all the tracks into a single directory to force them to be tagged together.
An MBID looks like one of these:
Beets can recognize either the hex-with-dashes UUID-style string or the full URL that contains it (as of 1.0b11).
You can get these IDs by searching on the MusicBrainz web site and going to a release page (when tagging full albums) or a recording page (when tagging singletons). Then, copy the URL of the page and paste it into beets.
Note that MusicBrainz has both “releases” and “release groups,” which link together different versions of the same album. Use release IDs here.
Run a command like this:
pip install -U beets
The -U flag tells pip to upgrade beets to the latest version. If you want a specific version, you can specify with using == like so:
pip install beets==1.0rc2
Beets sees regular releases (about every six weeks or so), but sometimes it’s helpful to run on the “bleeding edge”. To run the latest source:
More details about the beets source are available on the [[Hacking]] page.
We use the issue tracker on GitHub. Enter a new issue there to report a bug. Please follow these guidelines when reporting an issue:
If you’ve never reported a bug before, Mozilla has some well-written general guidelines for good bug reports.
There are a number of possibilities:
If none of these situations apply and you’re still having trouble tagging something, please file a bug report.
Please make sure you’re using the latest version of beets—you might be using a version earlier than the one that introduced the plugin. In many cases, the plugin may be introduced in beets “trunk” (the latest source version) and might not be released yet. Take a look at the changelog to see which version added the plugin. (You can type beet version to check which version of beets you have installed.)
If you want to live on the bleeding edge and use the latest source version of beets, you can check out the source (see the next question).
To see the beets documentation for your version (and avoid confusion with new features in trunk), select your version from the left-hand sidebar (or the buttons at the bottom of the window).
Typing a ^C (control-C) control sequence will not halt beets’ multithreaded importer while it is waiting at a prompt for user input. Instead, hit “return” (dismissing the prompt) after typing ^C. Alternatively, just type a “b” for “aBort” at most prompts. Typing ^C will work if the importer interface is between prompts.
Also note that beets may take some time to quit after ^C is typed; it tries to clean up after itself briefly even when canceled.
(For developers: this is because the UI thread is blocking on raw_input and cannot be interrupted by the main thread, which is trying to close all pipeline stages in the exception handler by setting a flag. There is no simple way to remedy this.)
Beets writes ID3v2.4 tags by default. Some software, including Windows (i.e., Windows Explorer and Windows Media Player) and id3lib/id3v2, don’t support v2.4 tags. When using 2.4-unaware software, it might look like the tags are unmodified or missing completely.
To enable ID3v2.3 tags, enable the id3v23 config option.
Beets will log a message like “unreadable file: /path/to/music.mp3” when it encounters files that look like music files (according to their extension) but seem to be broken. Most of the time, this is because the file is corrupted. To check whether the file is intact, try opening it in another media player (e.g., VLC) to see whether it can read the file. You can also use specialized programs for checking file integrity—for example, type metaflac --list music.flac to check FLAC files.
If beets still complains about a file that seems to be valid, file a bug and we’ll look into it. There’s always a possibility that there’s a bug “upstream” in the Mutagen library used by beets, in which case we’ll forward the bug to that project’s tracker.
Probably not. Beets uses a multithreaded importer that overlaps many different activities: it can prompt you for decisions while, in the background, it talks to MusicBrainz and copies files. This means that, even after you make your last decision, there may be a backlog of files to be copied into place and tags to be written. (Plugin tasks, like looking up lyrics and genres, also run at this time.) If beets pauses after you see all the albums go by, have patience.
When naming files, beets replaces certain characters to avoid causing problems on the filesystem. For example, leading dots can confusingly hide files on Unix and several non-alphanumeric characters are forbidden on Windows.
The replace config option controls which replacements are made. By default, beets makes filenames safe for all known platforms by replacing several patterns with underscores. This means that, even on Unix, filenames are made Windows-safe so that network filesystems (such as SMB) can be used safely.
Most notably, Windows forbids trailing dots, so a folder called “M.I.A.” will be rewritten to “M.I.A_” by default. Change the replace config if you don’t want this behavior and don’t need Windows-safe names.