Beets

--------------------

This release focuses on a large number of small fixes and improvements that turn
beets into a well-oiled, music-devouring machine. See the full release notes,
below, for a plethora of new features.

* **Queries can now contain whitespace.** Spaces passed as shell arguments are
now preserved, so you can use your shell's escaping syntax (quotes or
backslashes, for instance) to include spaces in queries. For example,
typing``beet ls "the knife"`` or ``beet ls the\ knife``. Read more in
:doc:`/reference/query`.

* Queries can **match items from the library by directory**. A ``path:`` prefix
is optional; any query containing a path separator (/ on POSIX systems) is
assumed to be a path query. Running ``beet ls path/to/music`` will show all
the music in your library under the specified directory. The
:doc:`/reference/query` reference again has more details.

* **Local album art** is now automatically discovered and copied from the
imported directories when available.

* When choosing the "as-is" import album (or doing a non-autotagged import),
**every album either has an "album artist" set or is marked as a compilation
(Various Artists)**. The choice is made based on the homogeneity of the
tracks' artists. This prevents compilations that are imported as-is from being
scattered across many directories after they are imported.

* The release **label** for albums and tracks is now fetched from !MusicBrainz,
written to files, and stored in the database.

* The "list" command now accepts a ``-p`` switch that causes it to **show
paths** instead of titles. This makes the output of ``beet ls -p`` suitable
for piping into another command such as `xargs`_.

* Release year and label are now shown in the candidate selection list to help
disambiguate different releases of the same album.

* Prompts in the importer interface are now colorized for easy reading. The
default option is always highlighted.

* The importer now provides the option to specify a MusicBrainz ID manually if
the built-in searching isn't working for a particular album or track.

* ``$bitrate`` in path formats is now formatted as a human-readable kbps value
instead of as a raw integer.

* The import logger has been improved for "always-on" use. First, it is now
possible to specify a log file in .beetsconfig. Also, logs are now appended
rather than overwritten and contain timestamps.

* Album art fetching and plugin events are each now run in separate pipeline
stages during imports. This should bring additional performance when using
album art plugins like embedart or beets-lyrics.

* Accents and other Unicode decorators on characters are now treated more fairly
by the autotagger. For example, if you're missing the acute accent on the "e"
in "café", that change won't be penalized. This introduces a new dependency
on the `unidecode`_ Python module.

* When tagging a track with no title set, the track's filename is now shown
(instead of nothing at all).

* The bitrate of lossless files is now calculated from their file size (rather
than being fixed at 0 or reflecting the uncompressed audio bitrate).

* Fixed a problem where duplicate albums or items imported at the same time
would fail to be detected.

* BPD now uses a persistent "virtual filesystem" in order to fake a directory
structure. This means that your path format settings are respected in BPD's
browsing hierarchy. This may come at a performance cost, however. The virtual
filesystem used by BPD is available for reuse by plugins (e.g., the FUSE
plugin).

* Singleton imports (``beet import -s``) can now take individual files as
arguments as well as directories.

* Fix Unicode queries given on the command line.

* Fix crasher in quiet singleton imports (``import -qs``).

* Fix crash when autotagging files with no metadata.

* Fix a rare deadlock when finishing the import pipeline.

* Fix an issue that was causing mpdupdate to run twice for every album.

* Fix a bug that caused release dates/years not to be fetched.

* Fix a crasher when setting MBIDs on MP3s file metadata.

* Fix a "broken pipe" error when piping beets' standard output.

* A better error message is given when the database file is unopenable.

* Suppress errors due to timeouts and bad responses from MusicBrainz.

* Fix a crash on album queries with item-only field names.

.. _xargs: https://en.wikipedia.org/wiki/xargs

----------------------

This release of beets brings two significant new features. First, beets now has
first-class support for "singleton" tracks. Previously, it was only really meant
to manage whole albums, but many of us have lots of non-album tracks to keep
track of alongside our collections of albums. So now beets makes it easy to tag,
catalog, and manipulate your individual tracks. Second, beets can now
(optionally) embed album art directly into file metadata rather than only
storing it in a "file on the side." Check out the :doc:`/plugins/embedart` for
that functionality.

* Better support for **singleton (non-album) tracks**. Whereas beets previously
only really supported full albums, now it can also keep track of individual,
off-album songs. The "singleton" path format can be used to customize where
these tracks are stored. To import singleton tracks, provide the -s switch to
the import command or, while doing a normal full-album import, choose the "as
Tracks" (T) option to add singletons to your library. To list only singleton
or only album tracks, use the new ``singleton:`` query term: the query
``singleton:true`` matches only singleton tracks; ``singleton:false`` matches
only album tracks. The ``lastid`` plugin has been extended to support
matching individual items as well.

* The importer/autotagger system has been heavily refactored in this release.
If anything breaks as a result, please get in touch or just file a bug.

* Support for **album art embedded in files**. A new :doc:`/plugins/embedart`
implements this functionality. Enable the plugin to automatically embed
downloaded album art into your music files' metadata. The plugin also provides
the "embedart" and "extractart" commands for moving image files in and out of
metadata. See the wiki for more details. (Thanks, daenney!)

* The "distance" number, which quantifies how different an album's current and
proposed metadata are, is now displayed as "similarity" instead. This should
be less noisy and confusing; you'll now see 99.5% instead of 0.00489323.

* A new "timid mode" in the importer asks the user every time, even when it
makes a match with very high confidence. The ``-t`` flag on the command line
and the ``import_timid`` config option control this mode. (Thanks to mdecker
on GitHub!)

* The multithreaded importer should now abort (either by selecting aBort or by
typing ^C) much more quickly. Previously, it would try to get a lot of work
done before quitting; now it gives up as soon as it can.

* Added a new plugin event, ``album_imported``, which is called every time an
album is added to the library. (Thanks, Lugoues!)

* A new plugin method, ``register_listener``, is an imperative alternative to
the ``listen`` decorator (Thanks again, Lugoues!)

* In path formats, ``$albumartist`` now falls back to ``$artist`` (as well as
the other way around).

* The importer now prints "(unknown album)" when no tags are present.

* When autotagging, "and" is considered equal to "&".

* Fix some crashes when deleting files that don't exist.

* Fix adding individual tracks in BPD.

* Fix crash when ``~/.beetsconfig`` does not exist.

---------------------

Beta 7's focus is on better support for "various artists" releases. These albums
can be treated differently via the new ``[paths]`` config section and the
autotagger is better at handling them. It also includes a number of
oft-requested improvements to the ``beet`` command-line tool, including several
new configuration options and the ability to clean up empty directory subtrees.

* **"Various artists" releases** are handled much more gracefully. The
autotagger now sets the ``comp`` flag on albums whenever the album is
identified as a "various artists" release by !MusicBrainz. Also, there is now
a distinction between the "album artist" and the "track artist", the latter of
which is never "Various Artists" or other such bogus stand-in. *(Thanks to
Jonathan for the bulk of the implementation work on this feature!)*

* The directory hierarchy can now be **customized based on release type**. In
particular, the ``path_format`` setting in .beetsconfig has been replaced with
a new ``[paths]`` section, which allows you to specify different path formats
for normal and "compilation" (various artists) releases as well as for each
album type (see below). The default path formats have been changed to use
``$albumartist`` instead of ``$artist``.

* A **new ``albumtype`` field** reflects the release type `as specified by
MusicBrainz`_.

* When deleting files, beets now appropriately "prunes" the directory
tree---empty directories are automatically cleaned up. *(Thanks to
wlof on GitHub for this!)*

* The tagger's output now always shows the album directory that is currently
being tagged. This should help in situations where files' current tags are
missing or useless.

* The logging option (``-l``) to the ``import`` command now logs duplicate
albums.

* A new ``import_resume`` configuration option can be used to disable the
importer's resuming feature or force it to resume without asking. This option
may be either ``yes``, ``no``, or ``ask``, with the obvious meanings. The
``-p`` and ``-P`` command-line flags override this setting and correspond to
the "yes" and "no" settings.

* Resuming is automatically disabled when the importer is in quiet (``-q``)
mode. Progress is still saved, however, and the ``-p`` flag (above) can be
used to force resuming.

* The ``BEETSCONFIG`` environment variable can now be used to specify the
location of the config file that is at ~/.beetsconfig by default.

* A new ``import_quiet_fallback`` config option specifies what should
happen in quiet mode when there is no strong recommendation. The options are
``skip`` (the default) and "asis".

* When importing with the "delete" option and importing files that are already
at their destination, files could be deleted (leaving zero copies afterward).
This is fixed.

* The ``version`` command now lists all the loaded plugins.

* A new plugin, called ``info``, just prints out audio file metadata.

* Fix a bug where some files would be erroneously interpreted as MPEG-4 audio.

* Fix permission bits applied to album art files.

* Fix malformed !MusicBrainz queries caused by null characters.

* Fix a bug with old versions of the Monkey's Audio format.

* Fix a crash on broken symbolic links.

* Retry in more cases when !MusicBrainz servers are slow/overloaded.

* The old "albumify" plugin for upgrading databases was removed.

.. _as specified by MusicBrainz: https://wiki.musicbrainz.org/ReleaseType

------------------------

This version consists primarily of bug fixes and other small improvements. It's
in preparation for a more feature-ful release in beta 7. The most important
issue involves correct ordering of autotagged albums.

* **Quiet import:** a new "-q" command line switch for the import command
suppresses all prompts for input; it pessimistically skips all albums that the
importer is not completely confident about.

* Added support for the **WavPack** and **Musepack** formats. Unfortunately, due
to a limitation in the Mutagen library (used by beets for metadata
manipulation), Musepack SV8 is not yet supported. Here's the `upstream bug`_
in question.

* BPD now uses a pure-Python socket library and no longer requires
eventlet/greenlet (the latter of which is a C extension). For the curious, the
socket library in question is called `Bluelet`_.

* Non-autotagged imports are now resumable (just like autotagged imports).

* Fix a terrible and long-standing bug where track orderings were never applied.
This manifested when the tagger appeared to be applying a reasonable ordering
to the tracks but, later, the database reflects a completely wrong association
of track names to files. The order applied was always just alphabetical by
filename, which is frequently but not always what you want.

* We now use Windows' "long filename" support. This API is fairly tricky,
though, so some instability may still be present---please file a bug if you
run into pathname weirdness on Windows. Also, filenames on Windows now never
end in spaces.

* Fix crash in lastid when the artist name is not available.

* Fixed a spurious crash when ``LANG`` or a related environment variable is set
to an invalid value (such as ``'UTF-8'`` on some installations of Mac OS X).

* Fixed an error when trying to copy a file that is already at its destination.

* When copying read-only files, the importer now tries to make the copy
writable. (Previously, this would just crash the import.)

* Fixed an ``UnboundLocalError`` when no matches are found during autotag.

* Fixed a Unicode encoding error when entering special characters into the
"manual search" prompt.

* Added `` beet version`` command that just shows the current release version.

.. _upstream bug: https://github.com/quodlibet/mutagen/issues/7
.. _Bluelet: https://github.com/sampsyo/bluelet

--------------------------

This version of beets focuses on increasing the accuracy of the autotagger. The
main addition is an included plugin that uses acoustic fingerprinting to match
based on the audio content (rather than existing metadata). Additional
heuristics were also added to the metadata-based tagger as well that should make
it more reliable. This release also greatly expands the capabilities of beets'
:doc:`plugin API </plugins/index>`. A host of other little features and fixes
are also rolled into this release.

* The ``lastid`` plugin adds Last.fm **acoustic fingerprinting
support** to the autotagger. Similar to the PUIDs used by !MusicBrainz Picard,
this system allows beets to recognize files that don't have any metadata at
all. You'll need to install some dependencies for this plugin to work.

* To support the above, there's also a new system for **extending the autotagger
via plugins**. Plugins can currently add components to the track and album
distance functions as well as augment the MusicBrainz search. The new API is
documented at :doc:`/plugins/index`.

* **String comparisons** in the autotagger have been augmented to act more
intuitively. Previously, if your album had the title "Something (EP)" and it
was officially called "Something", then beets would think this was a fairly
significant change. It now checks for and appropriately reweights certain
parts of each string. As another example, the title "The Great Album" is
considered equal to "Great Album, The".

* New **event system for plugins** (thanks, Jeff!). Plugins can now get
callbacks from beets when certain events occur in the core. Again, the API is
documented in :doc:`/plugins/index`.

* The BPD plugin is now disabled by default. This greatly simplifies
installation of the beets core, which is now 100% pure Python. To use BPD,
though, you'll need to set ``plugins: bpd`` in your .beetsconfig.

* The ``import`` command can now remove original files when it copies items into
your library. (This might be useful if you're low on disk space.) Set the
``import_delete`` option in your .beetsconfig to ``yes``.

* Importing without autotagging (``beet import -A``) now prints out album names
as it imports them to indicate progress.

* The new :doc:`/plugins/mpdupdate` will automatically update your MPD server's
index whenever your beets library changes.

* Efficiency tweak should reduce the number of !MusicBrainz queries per
autotagged album.

* A new ``-v`` command line switch enables debugging output.

* Fixed bug that completely broke non-autotagged imports (``import -A``).

* Fixed bug that logged the wrong paths when using ``import -l``.

* Fixed autotagging for the creatively-named band `!!!`_.

* Fixed normalization of relative paths.

* Fixed escaping of ``/`` characters in paths on Windows.

.. _!!!: https://musicbrainz.org/artist/f26c72d3-e52c-467b-b651-679c73d8e1a7.html

----------------------

This thrilling new release of beets focuses on making the tagger more usable in
a variety of ways. First and foremost, it should now be much faster: the tagger
now uses a multithreaded algorithm by default (although, because the new tagger
is experimental, a single-threaded version is still available via a config
option). Second, the tagger output now uses a little bit of ANSI terminal
coloring to make changes stand out. This way, it should be faster to decide what
to do with a proposed match: the more red you see, the worse the match is.
Finally, the tagger can be safely interrupted (paused) and restarted later at
the same point. Just enter ``b`` for aBort at any prompt to stop the tagging
process and save its progress. (The progress-saving also works in the
unthinkable event that beets crashes while tagging.)

Among the under-the-hood changes in 1.0b4 is a major change to the way beets
handles paths (filenames). This should make the whole system more tolerant to
special characters in filenames, but it may break things (especially databases
created with older versions of beets). As always, let me know if you run into
weird problems with this release.

Finally, this release's ``setup.py`` should install a ``beet.exe`` startup stub
for Windows users. This should make running beets much easier: just type
``beet`` if you have your ``PATH`` environment variable set up correctly. The
:doc:`/guides/main` guide has some tips on installing beets on Windows.

Here's the detailed list of changes:

* **Parallel tagger.** The autotagger has been reimplemented to use multiple
threads. This means that it can concurrently read files from disk, talk to the
user, communicate with MusicBrainz, and write data back to disk. Not only does
this make the tagger much faster because independent work may be performed in
parallel, but it makes the tagging process much more pleasant for large
imports. The user can let albums queue up in the background while making a
decision rather than waiting for beets between each question it asks. The
parallel tagger is on by default but a sequential (single- threaded) version
is still available by setting the ``threaded`` config value to ``no`` (because
the parallel version is still quite experimental).

* **Colorized tagger output.** The autotagger interface now makes it a little
easier to see what's going on at a glance by highlighting changes with
terminal colors. This feature is on by default, but you can turn it off by
setting ``color`` to ``no`` in your ``.beetsconfig`` (if, for example, your
terminal doesn't understand colors and garbles the output).

* **Pause and resume imports.** The ``import`` command now keeps track of its
progress, so if you're interrupted (beets crashes, you abort the process, an
alien devours your motherboard, etc.), beets will try to resume from the point
where you left off. The next time you run ``import`` on the same directory, it
will ask if you want to resume. It accomplishes this by "fast-forwarding"
through the albums in the directory until it encounters the last one it saw.
(This means it might fail if that album can't be found.) Also, you can now
abort the tagging process by entering ``b`` (for aBort) at any of the prompts.

* Overhauled methods for handling fileystem paths to allow filenames that have
badly encoded special characters. These changes are pretty fragile, so please
report any bugs involving ``UnicodeError`` or SQLite ``ProgrammingError``
messages in this version.

* The destination paths (the library directory structure) now respect
album-level metadata. This means that if you have an album in which two tracks
have different album-level attributes (like year, for instance), they will
still wind up in the same directory together. (There's currently not a very
smart method for picking the "correct" album-level metadata, but we'll fix
that later.)

* Fixed a bug where the CLI would fail completely if the ``LANG`` environment
variable was not set.

* Fixed removal of albums (``beet remove -a``): previously, the album record
would stay around although the items were deleted.

* The setup script now makes a ``beet.exe`` startup stub on Windows; Windows
users can now just type ``beet`` at the prompt to run beets.

* Fixed an occasional bug where Mutagen would complain that a tag was already
present.

* Fixed a bug with reading invalid integers from ID3 tags.

* The tagger should now be a little more reluctant to reorder tracks that
already have indices.