FAQ
***

Here are some answers to frequently-asked questions from IRC and
elsewhere. Got a question that isn't answered here? Try the discussion
board, or filing an issue in the bug tracker.

* How do I…

  * …rename my files according to a new path format configuration?

  * …find all the albums I imported "as-is"?

  * …create "Disc N" directories for multi-disc albums?

  * …import a multi-disc album?

  * …enter a MusicBrainz ID?

  * …upgrade to the latest version of beets?

  * …run the latest source version of beets?

  * …report a bug in beets?

  * …find the configuration file (config.yaml)?

  * …avoid using special characters in my filenames?

  * …point beets at a new music directory?

* Why does beets…

  * …complain that it can't find a match?

  * …appear to be missing some plugins?

  * …ignore control-C during an import?

  * …not change my ID3 tags?

  * …complain that a file is "unreadable"?

  * …seem to "hang" after an import finishes?

  * …put a bunch of underscores in my filenames?

  * …say "command not found"?


How do I…
=========


…rename my files according to a new path format configuration?
--------------------------------------------------------------

Just run the move command. Use a query to rename a subset of your
music or leave the query off to rename everything.


…find all the albums I imported "as-is"?
----------------------------------------

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.


…create "Disc N" directories for multi-disc albums?
---------------------------------------------------

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

This "paths" configuration only contains the "default" key: it leaves
the "comp" and "singleton" keys as their default values, as documented
in Path Format Configuration. To create "Disc N" directories for
compilations and singletons, you will need to specify similar
templates for those keys as well.


…import a multi-disc album?
---------------------------

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.


…enter a MusicBrainz ID?
------------------------

An MBID looks like one of these:

* "https://musicbrainz.org/release/ded77dcf-7279-457e-955d-
  625bd3801b87"

* "d569deba-8c6b-4d08-8c43-d0e5a1b8c7f3"

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.


…upgrade to the latest version of beets?
----------------------------------------

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


…run the latest source version of beets?
----------------------------------------

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:

1. Uninstall beets. If you installed using "pip", you can just run
   "pip uninstall beets".

2. Install from source. Choose one of these methods:

   * Directly from GitHub using "python -m pip install
     git+https://github.com/beetbox/beets.git" command. Depending on
     your system, you may need to use "pip3" and "python3" instead of
     "pip" and "python" respectively.

   * Use "pip" to install the latest snapshot tarball. Type: "pip
     install https://github.com/beetbox/beets/tarball/master"

   * Grab the source using git. First, clone the repository: "git
     clone https://github.com/beetbox/beets.git". Then, "cd beets" and
     "python setup.py install".

   * Use "pip" to install an "editable" version of beets based on an
     automatic source checkout. For example, run "pip install -e
     git+https://github.com/beetbox/beets#egg=beets" to clone beets
     and install it, allowing you to modify the source in-place to try
     out changes.

   * Combine the previous two approaches, cloning the source yourself,
     and then installing in editable mode: "git clone
     https://github.com/beetbox/beets.git" then "pip install -e
     beets". This approach lets you decide where the source is stored,
     with any changes immediately reflected in your environment.

More details about the beets source are available on the developer
documentation pages.


…report a bug in beets?
-----------------------

We use the issue tracker on GitHub. Enter a new issue there to report
a bug. Please follow these guidelines when reporting an issue:

* Most importantly: if beets is crashing, please include the
  traceback. Tracebacks can be more readable if you put them in a
  pastebin (e.g., Gist or Hastebin), especially when communicating
  over IRC or email.

* Turn on beets' debug output (using the -v option: for example, "beet
  -v import ...") and include that with your bug report. Look through
  this verbose output for any red flags that might point to the
  problem.

* If you can, try installing the latest beets source code to see if
  the bug is fixed in an unreleased version. You can also look at the
  latest changelog entries for descriptions of the problem you're
  seeing.

* Try to narrow your problem down to something specific. Is a
  particular plugin causing the problem? (You can disable plugins to
  see whether the problem goes away.) Is a some music file or a single
  album leading to the crash? (Try importing individual albums to
  determine which one is causing the problem.) Is some entry in your
  configuration file causing it? Et cetera.

* If you do narrow the problem down to a particular audio file or
  album, include it with your bug report so the developers can run
  tests.

If you've never reported a bug before, Mozilla has some well-written
general guidelines for good bug reports.


…find the configuration file (config.yaml)?
-------------------------------------------

You create this file yourself; beets just reads it. See Configuration.


…avoid using special characters in my filenames?
------------------------------------------------

Use the "%asciify{}" function in your path formats. See Template
Functions.


…point beets at a new music directory?
--------------------------------------

If you want to move your music from one directory to another, the best
way is to let beets do it for you. First, edit your configuration and
set the "directory" setting to the new place. Then, type "beet move"
to have beets move all your files.

If you've already moved your music *outside* of beets, you have a few
options:

* Move the music back (with an ordinary "mv") and then use the above
  steps.

* Delete your database and re-create it from the new paths using "beet
  import -AWC".

* Resort to manually modifying the SQLite database (not recommended).


Why does beets…
===============


…complain that it can't find a match?
-------------------------------------

There are a number of possibilities:

* First, make sure the album is 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 the album in question is a multi-disc release, see the relevant
  FAQ answer above.

* The music files' metadata might be insufficient. Try using the
  "enter search" or "enter ID" options to help the matching process
  find the right MusicBrainz entry.

* If you have a lot of files that are missing metadata, consider using
  acoustic fingerprinting or filename-based guesses for that music.

If none of these situations apply and you're still having trouble
tagging something, please file a bug report.


…appear to be missing some plugins?
-----------------------------------

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 relevant
question).

To see the beets documentation for your version (and avoid confusion
with new features in trunk), select your version from the menu in the
sidebar.


…ignore control-C during an import?
-----------------------------------

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 "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.)


…not change my ID3 tags?
------------------------

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.


…complain that a file is "unreadable"?
--------------------------------------

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.


…seem to "hang" after an import finishes?
-----------------------------------------

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.


…put a bunch of underscores in my filenames?
--------------------------------------------

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.


…say "command not found"?
-------------------------

You need to put the "beet" program on your system's search path. If
you installed using pip, the command "pip show -f beets" can show you
where "beet" was placed on your system. If you need help extending
your "$PATH", try this Super User answer.
