<commit_before>FAQ
###

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

.. _IRC: irc://irc.freenode.net/beets
.. _mailing list: http://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


.. _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:

-  ``http://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 <http://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 <http://www.pip-installer.org>`__ 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. There are a few easy ways to do this:

   -  Use ``pip`` to install the latest snapshot tarball: just type
      ``pip install https://github.com/sampsyo/beets/tarball/master``.
   -  Grab the source using Mercurial
      (``hg clone https://bitbucket.org/adrian/beets``) or git
      (``git clone https://github.com/sampsyo/beets.git``). Then
      ``cd beets`` and type ``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 hg+https://bitbucket.org/adrian/beets#egg=beets``
      to clone beets from BitBucket using Mercurial and install it,
      allowing you to modify the source in-place to try out changes.

More details about the beets source are available on the :doc:dev:`index`
page.


.. _bugs:

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

We use the `issue tracker <https://github.com/sampsyo/beets/issues>`__
on GitHub. `Enter a new issue <https://github.com/sampsyo/beets/issues/new>`__
there to report a bug. Please follow these guidelines when reporting an issue:

-  Most importantly: if beets is crashing, please `include the
   traceback <http://imgur.com/jacoj>`__. Tracebacks can be more
   readable if you put them in a pastebin (e.g.,
   `Gist <https://gist.github.com/>`__ or
   `Hastebin <http://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>`<commit_msg>Fixing last commit<commit_after>FAQ
###

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

.. _IRC: irc://irc.freenode.net/beets
.. _mailing list: http://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


.. _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:

-  ``http://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 <http://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 <http://www.pip-installer.org>`__ 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. There are a few easy ways to do this:

   -  Use ``pip`` to install the latest snapshot tarball: just type
      ``pip install https://github.com/sampsyo/beets/tarball/master``.
   -  Grab the source using Mercurial
      (``hg clone https://bitbucket.org/adrian/beets``) or git
      (``git clone https://github.com/sampsyo/beets.git``). Then
      ``cd beets`` and type ``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 hg+https://bitbucket.org/adrian/beets#egg=beets``
      to clone beets from BitBucket using Mercurial and install it,
      allowing you to modify the source in-place to try out changes.

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 <https://github.com/sampsyo/beets/issues>`__
on GitHub. `Enter a new issue <https://github.com/sampsyo/beets/issues/new>`__
there to report a bug. Please follow these guidelines when reporting an issue:

-  Most importantly: if beets is crashing, please `include the
   traceback <http://imgur.com/jacoj>`__. Tracebacks can be more
   readable if you put them in a pastebin (e.g.,
   `Gist <https://gist.github.com/>`__ or
   `Hastebin <http://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>`
{'fraction_non_alphanumeric': 0.1403818655900412, 'fraction_numerical': 0.009252249978972159, 'mean_word_length': 2.91247120763409, 'pattern_counts': {'":': 0, '<': 26, '<?xml version=': 0, '>': 28, 'https://': 14, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1141241', 'n_tokens_mistral': 3623, 'n_tokens_neox': 3386, 'n_words': 1569}