beets/docs/faq.rst

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
:ref:`filing an issue <bugs>` in the bug tracker.

.. _discussion board: https://github.com/beetbox/beets/discussions/

.. _mailing list: https://groups.google.com/group/beets-users

.. contents::
    :local:
    :depth: 2

How do I…
---------

.. _move:

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

Just run the :ref:`move-cmd` command. Use a :doc:`query </reference/query>` to
rename a subset of your music or leave the query off to rename everything.

.. _asispostfacto:

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

Enable the :ref:`import log <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.

.. _discdir:

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

Use the :doc:`/plugins/inline` 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
:ref:`path-format-config`. To create "Disc N" directories for compilations and
singletons, you will need to specify similar templates for those keys as well.

.. _multidisc:

…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.

.. _mbid:

…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
<https://musicbrainz.org/>`__ 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:

…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

.. _src:

…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``
   - 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.
   - Clone source code and install it in editable mode

     .. code-block:: shell

         git clone https://github.com/beetbox/beets.git
         poetry install

     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 :doc:`developer
documentation </dev/index>` pages.

.. _bugs:

…report a bug in beets?
~~~~~~~~~~~~~~~~~~~~~~~

We use the `issue tracker`_ on GitHub where you can `open a new ticket`_. Please
follow these guidelines when reporting an issue:

- Most importantly: if beets is crashing, please `include the traceback
  <https://imgur.com/jacoj>`__. Tracebacks can be more readable if you put them
  in a pastebin (e.g., `Gist <https://gist.github.com/>`__ or `Hastebin
  <https://hastebin.com/>`__), 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 :doc:`latest
  changelog entries </changelog>` 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-config:

.. _general guidelines for good bug reports: https://developer.mozilla.org/en-US/docs/Mozilla/QA/Bug_writing_guidelines

.. _issue tracker: https://github.com/beetbox/beets/issues

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

You create this file yourself; beets just reads it. See
:doc:`/reference/config`.

.. _special-chars:

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

Use the ``%asciify{}`` function in your path formats. See
:ref:`template-functions`.

.. _move-dir:

…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…
---------------

.. _nomatch:

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

There are a number of possibilities:

- First, make sure you have at least one autotagger extension/plugin enabled.
  See :ref:`autotagger_extensions` for a list of valid plugins.
- Check that the album is in `the MusicBrainz database
  <https://musicbrainz.org/>`__. 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
  :doc:`acoustic fingerprinting </plugins/chroma>` or :doc:`filename-based
  guesses </plugins/fromfilename>` for that music.

If none of these situations apply and you're still having trouble tagging
something, please :ref:`file a bug report <bugs>`.

.. _plugins:

…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 :doc:`the changelog </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 :ref:`the relevant question <src>`).

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.

.. _kill:

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

.. _id3v24:

…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
<http://id3v2.sourceforge.net/>`__, 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 :ref:`id3v23` config option.

.. _id3v2.4: https://id3.org/id3v2.4.0-structure

.. _invalid:

…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 <https://www.videolan.org/vlc/index.html>`__) 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, `open a new
ticket`_ and we'll look into it. There's always a possibility that there's a bug
"upstream" in the `Mutagen <https://github.com/quodlibet/mutagen>`__ library
used by beets, in which case we'll forward the bug to that project's tracker.

.. _importhang:

…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.

.. _replaceq:

…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 :ref:`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.

.. _pathq:

…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`_.

.. _open a new ticket: https://github.com/beetbox/beets/issues/new?template=bug-report.md

.. _pip: https://pip.pypa.io/en/stable/

.. _this super user answer: https://superuser.com/a/284361/4569