Beets

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

This release of beets fixes all the bugs, and you can be confident that you
will never again find any bugs in beets, ever.
It also adds support for plain old AIFF files and adds three more plugins,
including a nifty one that lets you measure a song's tempo by tapping out the
beat on your keyboard.
The importer deals more elegantly with duplicates and you can broaden your
cover art search to the entire web with Google Image Search.

The big new features are:

* Support for AIFF files. Tags are stored as ID3 frames in one of the file's
IFF chunks. Thanks to Evan Purkhiser for contributing support to `Mutagen`_.
* The new :doc:`/plugins/importadded` reads files' modification times to set
their "added" date. Thanks to Stig Inge Lea Bjørnsen.
* The new :doc:`/plugins/bpm` lets you manually measure the tempo of a playing
song. Thanks to aroquen.
* The new :doc:`/plugins/spotify` generates playlists for your `Spotify`_
account. Thanks to Olin Gay.
* A new :ref:`required` configuration option for the importer skips matches
that are missing certain data. Thanks to oprietop.
* When the importer detects duplicates, it now shows you some details about
the potentially-replaced music so you can make an informed decision. Thanks
to Howard Jones.
* :doc:`/plugins/fetchart`: You can now optionally search for cover art on
Google Image Search. Thanks to Lemutar.
* A new :ref:`asciify-paths` configuration option replaces all non-ASCII
characters in paths.

.. _Mutagen: https://github.com/quodlibet/mutagen
.. _Spotify: https://www.spotify.com/

And the multitude of little improvements and fixes:

* Compatibility with the latest version of `Mutagen`_, 1.23.
* :doc:`/plugins/web`: Lyrics now display readably with correct line breaks.
Also, the detail view scrolls to reveal all of the lyrics. Thanks to Meet
Udeshi.
* :doc:`/plugins/play`: The ``command`` config option can now contain
arguments (rather than just an executable). Thanks to Alessandro Ghedini.
* Fix an error when using the :ref:`modify-cmd` command to remove a flexible
attribute. Thanks to Pierre Rust.
* :doc:`/plugins/info`: The command now shows audio properties (e.g., bitrate)
in addition to metadata. Thanks Alessandro Ghedini.
* Avoid a crash on Windows when writing to files with special characters in
their names.
* :doc:`/plugins/play`: Playing albums now generates filenames by default (as
opposed to directories) for better compatibility. The ``use_folders`` option
restores the old behavior. Thanks to Lucas Duailibe.
* Fix an error when importing an empty directory with the ``--flat`` option.
* :doc:`/plugins/mpdstats`: The last song in a playlist is now correctly
counted as played. Thanks to Johann Klähn.
* :doc:`/plugins/zero`: Prevent accidental nulling of dangerous fields (IDs
and paths). Thanks to brunal.
* The :ref:`remove-cmd` command now shows the paths of files that will be
deleted. Thanks again to brunal.
* Don't display changes for fields that are not in the restricted field set.
This fixes :ref:`write-cmd` showing changes for fields that are not written
to the file.
* The :ref:`write-cmd` command avoids displaying the item name if there are
no changes for it.
* When using both the :doc:`/plugins/convert` and the :doc:`/plugins/scrub`,
avoid scrubbing the source file of conversions. (Fix a regression introduced
in the previous release.)
* :doc:`/plugins/replaygain`: Logging is now quieter during import. Thanks to
Yevgeny Bezman.
* :doc:`/plugins/fetchart`: When loading art from the filesystem, we now
prioritize covers with more keywords in them. This means that
``cover-front.jpg`` will now be taken before ``cover-back.jpg`` because it
contains two keywords rather than one. Thanks to Fabrice Laporte.
* :doc:`/plugins/lastgenre`: Remove duplicates from canonicalized genre lists.
Thanks again to Fabrice Laporte.
* The importer now records its progress when skipping albums. This means that
incremental imports will no longer try to import albums again after you've
chosen to skip them, and erroneous invitations to resume "interrupted"
imports should be reduced. Thanks to jcassette.
* :doc:`/plugins/bucket`: You can now customize the definition of alphanumeric
"ranges" using regular expressions. And the heuristic for detecting years
has been improved. Thanks to sotho.
* Already-imported singleton tracks are skipped when resuming an
import.
* :doc:`/plugins/chroma`: A new ``auto`` configuration option disables
fingerprinting on import. Thanks to ddettrittus.
* :doc:`/plugins/convert`: A new ``--format`` option to can select the
transcoding preset from the command-line.
* :doc:`/plugins/convert`: Transcoding presets can now omit their filename
extensions (extensions default to the name of the preset).
* :doc:`/plugins/convert`: A new ``--pretend`` option lets you preview the
commands the plugin will execute without actually taking any action. Thanks
to Dietrich Daroch.
* Fix a crash when a float-valued tag field only contained a ``+`` or ``-``
character.
* Fixed a regression in the core that caused the :doc:`/plugins/scrub` not to
work in ``auto`` mode. Thanks to Harry Khanna.
* The :ref:`write-cmd` command now has a ``--force`` flag. Thanks again to
Harry Khanna.
* :doc:`/plugins/mbsync`: Track alignment now works with albums that have
multiple copies of the same recording. Thanks to Rui Gonçalves.

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

This is primarily a bugfix release, but it also brings two new plugins: one
for playing music in desktop players and another for organizing your
directories into "buckets." It also brings huge performance optimizations to
queries---your ``beet ls`` commands will now go much faster.

New features:

* The new :doc:`/plugins/play` lets you start your desktop music player with
the songs that match a query. Thanks to David Hamp-Gonsalves.
* The new :doc:`/plugins/bucket` provides a ``%bucket{}`` function for path
formatting to generate folder names representing ranges of years or initial
letter. Thanks to Fabrice Laporte.
* Item and album queries are much faster.
* :doc:`/plugins/ftintitle`: A new option lets you remove featured artists
entirely instead of moving them to the title. Thanks to SUTJael.

And those all-important bug fixes:

* :doc:`/plugins/mbsync`: Fix a regression in 1.3.5 that broke the plugin
entirely.
* :ref:`Shell completion <completion>` now searches more common paths for its
``bash_completion`` dependency.
* Fix encoding-related logging errors in :doc:`/plugins/convert` and
:doc:`/plugins/replaygain`.
* :doc:`/plugins/replaygain`: Suppress a deprecation warning emitted by later
versions of PyGI.
* Fix a crash when reading files whose iTunes SoundCheck tags contain
non-ASCII characters.
* The ``%if{}`` template function now appropriately interprets the condition
as false when it contains the string "false". Thanks to Ayberk Yilmaz.
* :doc:`/plugins/convert`: Fix conversion for files that include a video
stream by ignoring it. Thanks to brunal.
* :doc:`/plugins/fetchart`: Log an error instead of crashing when tag
manipulation fails.
* :doc:`/plugins/convert`: Log an error instead of crashing when
embedding album art fails.
* :doc:`/plugins/convert`: Embed cover art into converted files.
Previously they were embedded into the source files.
* New plugin event: `before_item_moved`. Thanks to Robert Speicher.

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

This is a short-term release that adds some great new stuff to beets. There's
support for tracking and calculating musical keys, the ReplayGain plugin was
expanded to work with more music formats via GStreamer, we can now import
directly from compressed archives, and the lyrics plugin is more robust.

One note for upgraders and packagers: this version of beets has a new
dependency in `enum34`_, which is a backport of the new `enum`_ standard
library module.

The major new features are:

* Beets can now import `zip`, `tar`, and `rar` archives. Just type ``beet
import music.zip`` to have beets transparently extract the files to import.
* :doc:`/plugins/replaygain`: Added support for calculating ReplayGain values
with GStreamer as well the mp3gain program. This enables ReplayGain
calculation for any audio format. Thanks to Yevgeny Bezman.
* :doc:`/plugins/lyrics`: Lyrics should now be found for more songs. Searching
is now sensitive to featured artists and parenthesized title suffixes.
When a song has multiple titles, lyrics from all the named songs are now
concatenated. Thanks to Fabrice Laporte and Paul Phillips.

In particular, a full complement of features for supporting musical keys are
new in this release:

* A new `initial_key` field is available in the database and files' tags. You
can set the field manually using a command like ``beet modify
initial_key=Am``.
* The ``echonest`` plugin sets the `initial_key` field if the data is
available.
* A new :doc:`/plugins/keyfinder` runs a command-line tool to get the key from
audio data and store it in the `initial_key` field.

There are also many bug fixes and little enhancements:

* ``echonest`` plugin: Truncate files larger than 50MB before uploading for
analysis.
* :doc:`/plugins/fetchart`: Fix a crash when the server does not specify a
content type. Thanks to Lee Reinhardt.
* :doc:`/plugins/convert`: The ``--keep-new`` flag now works correctly
and the library includes the converted item.
* The importer now logs a message instead of crashing when errors occur while
opening the files to be imported.
* :doc:`/plugins/embedart`: Better error messages in exceptional conditions.
* Silenced some confusing error messages when searching for a non-MusicBrainz
ID. Using an invalid ID (of any kind---Discogs IDs can be used there too) at
the "Enter ID:" importer prompt now just silently returns no results. More
info is in the verbose logs.
* :doc:`/plugins/mbsync`: Fix application of album-level metadata. Due to a
regression a few releases ago, only track-level metadata was being updated.
* On Windows, paths on network shares (UNC paths) no longer cause "invalid
filename" errors.
* :doc:`/plugins/replaygain`: Fix crashes when attempting to log errors.
* The :ref:`modify-cmd` command can now accept query arguments that contain =
signs. An argument is considered a query part when a : appears before any
=s. Thanks to mook.

.. _enum34: https://pypi.python.org/pypi/enum34
.. _enum: https://docs.python.org/3.4/library/enum.html

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

This release brings a hodgepodge of medium-sized conveniences to beets. A new
:ref:`config-cmd` command manages your configuration, we now have :ref:`bash
completion <completion>`, and the :ref:`modify-cmd` command can delete
attributes. There are also some significant performance optimizations to the
autotagger's matching logic.

One note for upgraders: if you use the :doc:`/plugins/fetchart`, it has a new
dependency, the `requests`_ module.

New stuff:

* Added a :ref:`config-cmd` command to manage your configuration. It can show
you what you currently have in your config file, point you at where the file
should be, or launch your text editor to let you modify the file. Thanks to
geigerzaehler.
* Beets now ships with a shell command completion script! See
:ref:`completion`. Thanks to geigerzaehler.
* The :ref:`modify-cmd` command now allows removing flexible attributes. For
example, ``beet modify artist:beatles oldies!`` deletes the ``oldies``
attribute from matching items. Thanks to brilnius.
* Internally, beets has laid the groundwork for supporting multi-valued
fields. Thanks to geigerzaehler.
* The importer interface now shows the URL for MusicBrainz matches. Thanks to
johtso.
* :doc:`/plugins/smartplaylist`: Playlists can now be generated from multiple
queries (combined with "or" logic). Album-level queries are also now
possible and automatic playlist regeneration can now be disabled. Thanks to
brilnius.
* ``echonest`` plugin: Echo Nest similarity now weights the tempo in
better proportion to other metrics. Also, options were added to specify
custom thresholds and output formats. Thanks to Adam M.
* Added the :ref:`after_write <plugin_events>` plugin event.
* :doc:`/plugins/lastgenre`: Separator in genre lists can now be
configured. Thanks to brilnius.
* We now only use "primary" aliases for artist names from MusicBrainz. This
eliminates some strange naming that could occur when the `languages` config
option was set. Thanks to Filipe Fortes.
* The performance of the autotagger's matching mechanism is vastly improved.
This should be noticeable when matching against very large releases such as
box sets.
* The :ref:`import-cmd` command can now accept individual files as arguments
even in non-singleton mode. Files are imported as one-track albums.

Fixes:

* Error messages involving paths no longer escape non-ASCII characters (for
legibility).
* Fixed a regression that made it impossible to use the :ref:`modify-cmd`
command to add new flexible fields. Thanks to brilnius.
* ``echonest`` plugin: Avoid crashing when the audio analysis fails.
Thanks to Pedro Silva.
* :doc:`/plugins/duplicates`: Fix checksumming command execution for files
with quotation marks in their names. Thanks again to Pedro Silva.
* Fix a crash when importing with both of the :ref:`group_albums` and
:ref:`incremental` options enabled. Thanks to geigerzaehler.
* Give a sensible error message when ``BEETSDIR`` points to a file. Thanks
again to geigerzaehler.
* Fix a crash when reading WMA files whose boolean-valued fields contain
strings. Thanks to johtso.
* :doc:`/plugins/fetchart`: The plugin now sends "beets" as the User-Agent
when making scraping requests. This helps resolve some blocked requests. The
plugin now also depends on the `requests`_ Python library.
* The :ref:`write-cmd` command now only shows the changes to fields that will
actually be written to a file.
* :doc:`/plugins/duplicates`: Spurious reports are now avoided for tracks with
missing values (e.g., no MBIDs). Thanks to Pedro Silva.
* The default :ref:`replace` sanitation options now remove leading whitespace
by default. Thanks to brilnius.
* :doc:`/plugins/importfeeds`: Fix crash when importing albums
containing ``/`` with the ``m3u_multi`` format.
* Avoid crashing on Mutagen bugs while writing files' tags.
* :doc:`/plugins/convert`: Display a useful error message when the FFmpeg
executable can't be found.

.. _requests: https://requests.readthedocs.io/en/master/

internally. Along with laying the groundwork for some great things in the
future, this brings a number of improvements to how you interact with beets.
Here's what's new with fields in particular:

* Plugin-provided fields can now be used in queries. For example, if you use
the :doc:`/plugins/inline` to define a field called ``era``, you can now
filter your library based on that field by typing something like
``beet list era:goldenage``.
* Album-level flexible attributes and plugin-provided attributes can now be
used in path formats (and other item-level templates).
* :ref:`Date-based queries <datequery>` are now possible. Try getting every
track you added in February 2014 with ``beet ls added:2014-02`` or in the
whole decade with ``added:2010..``. Thanks to Stig Inge Lea Bjørnsen.
* The :ref:`modify-cmd` command is now better at parsing and formatting
fields. You can assign to boolean fields like ``comp``, for example, using
either the words "true" or "false" or the numerals 1 and 0. Any
boolean-esque value is normalized to a real boolean. The :ref:`update-cmd`
and :ref:`write-cmd` commands also got smarter at formatting and colorizing
changes.

For developers, the short version of the story is that Item and Album objects
provide *uniform access* across fixed, flexible, and computed attributes. You
can write ``item.foo`` to access the ``foo`` field without worrying about
where the data comes from.

Unrelated new stuff:

* The importer has a new interactive option (*G* for "Group albums"),
command-line flag (``--group-albums``), and config option
(:ref:`group_albums`) that lets you split apart albums that are mixed
together in a single directory. Thanks to geigerzaehler.
* A new ``--config`` command-line option lets you specify an additional
configuration file. This option *combines* config settings with your default
config file. (As part of this change, the ``BEETSDIR`` environment variable
no longer combines---it *replaces* your default config file.) Thanks again
to geigerzaehler.
* :doc:`/plugins/ihate`: The plugin's configuration interface was overhauled.
Its configuration is now much simpler---it uses beets queries instead of an
ad-hoc per-field configuration. This is *backwards-incompatible*---if you
use this plugin, you will need to update your configuration. Thanks to
BrainDamage.

Other little fixes:

* ``echonest`` plugin: Tempo (BPM) is now always stored as an integer.
Thanks to Heinz Wiesinger.
* Fix Python 2.6 compatibility in some logging statements in
:doc:`/plugins/chroma` and :doc:`/plugins/lastgenre`.
* Prevent some crashes when things go really wrong when writing file metadata
at the end of the import process.
* New plugin events: ``item_removed`` (thanks to Romuald Conty) and
``item_copied`` (thanks to Stig Inge Lea Bjørnsen).
* The ``pluginpath`` config option can now point to the directory containing
plugin code. (Previously, it awkwardly needed to point at a directory
containing a ``beetsplug`` directory, which would then contain your code.
This is preserved as an option for backwards compatibility.) This change
should also work around a long-standing issue when using ``pluginpath`` when
beets is installed using pip. Many thanks to geigerzaehler.
* :doc:`/plugins/web`: The ``/item/`` and ``/album/`` API endpoints now
produce full details about albums and items, not just lists of IDs. Thanks
to geigerzaehler.
* Fix a potential crash when using image resizing with the
:doc:`/plugins/fetchart` or :doc:`/plugins/embedart` without ImageMagick
installed.
* Also, when invoking ``convert`` for image resizing fails, we now log an
error instead of crashing.
* :doc:`/plugins/fetchart`: The ``beet fetchart`` command can now associate
local images with albums (unless ``--force`` is provided). Thanks to
brilnius.
* :doc:`/plugins/fetchart`: Command output is now colorized. Thanks again to
brilnius.
* The :ref:`modify-cmd` command avoids writing files and committing to the
database when nothing has changed. Thanks once more to brilnius.
* The importer now uses the album artist field when guessing existing
metadata for albums (rather than just the track artist field). Thanks to
geigerzaehler.
* :doc:`/plugins/fromfilename`: Fix a crash when a filename contained only a
track number (e.g., ``02.mp3``).
* :doc:`/plugins/convert`: Transcoding should now work on Windows.
* :doc:`/plugins/duplicates`: The ``move`` and ``copy`` destination arguments
are now treated as directories. Thanks to Pedro Silva.
* The :ref:`modify-cmd` command now skips confirmation and prints a message if
no changes are necessary. Thanks to brilnius.
* :doc:`/plugins/fetchart`: When using the ``remote_priority`` config option,
local image files are no longer completely ignored.
* ``echonest`` plugin: Fix an issue causing the plugin to appear twice in
the output of the ``beet version`` command.
* :doc:`/plugins/lastgenre`: Fix an occasional crash when no tag weight was
returned by Last.fm.
* :doc:`/plugins/mpdstats`: Restore the ``last_played`` field. Thanks to
Johann Klähn.
* The :ref:`modify-cmd` command's output now clearly shows when a file has
been deleted.
* Album art in files with Vorbis Comments is now marked with the "front cover"
type. Thanks to Jason Lefley.

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

This update brings new plugins for fetching acoustic metrics and listening
statistics, many more options for the duplicate detection plugin, and flexible
options for fetching multiple genres.

The "core" of beets gained a new built-in command: :ref:`beet write
<write-cmd>` updates the metadata tags for files, bringing them back
into sync with your database. Thanks to Heinz Wiesinger.

We added some plugins and overhauled some existing ones:

* The new ``echonest`` plugin plugin can fetch a wide range of `acoustic
attributes`_ from `The Echo Nest`_, including the "speechiness" and
"liveness" of each track. The new plugin supersedes an older version
(``echonest_tempo``) that only fetched the BPM field. Thanks to Pedro Silva
and Peter Schnebel.

* The :doc:`/plugins/duplicates` got a number of new features, thanks to Pedro
Silva:

* The ``keys`` option lets you specify the fields used detect duplicates.
* You can now use checksumming (via an external command) to find
duplicates instead of metadata via the ``checksum`` option.
* The plugin can perform actions on the duplicates it find. The new
``copy``, ``move``, ``delete``, ``delete_file``, and ``tag`` options
perform those actions.

* The new :doc:`/plugins/mpdstats` collects statistics about your
listening habits from `MPD`_. Thanks to Peter Schnebel and Johann Klähn.

* :doc:`/plugins/lastgenre`: The new ``multiple`` option has been replaced
with the ``count`` option, which lets you limit the number of genres added
to your music. (No more thousand-character genre fields!) Also, the
``min_weight`` field filters out nonsense tags to make your genres more
relevant. Thanks to Peter Schnebel and rashley60.

* :doc:`/plugins/lyrics`: A new ``--force`` option optionally re-downloads
lyrics even when files already have them. Thanks to Bitdemon.

As usual, there are also innumerable little fixes and improvements:

* When writing ID3 tags for ReplayGain normalization, tags are written with
both upper-case and lower-case TXXX frame descriptions. Previous versions of
beets used only the upper-case style, which seems to be more standard, but
some players (namely, Quod Libet and foobar2000) seem to only use lower-case
names.
* :doc:`/plugins/missing`: Avoid a possible error when an album's
``tracktotal`` field is missing.
* :doc:`/plugins/ftintitle`: Fix an error when the sort artist is missing.
* ``echonest_tempo``: The plugin should now match songs more
reliably (i.e., fewer "no tempo found" messages). Thanks to Peter Schnebel.
* :doc:`/plugins/convert`: Fix an "Item has no library" error when using the
``auto`` config option.
* :doc:`/plugins/convert`: Fix an issue where files of the wrong format would
have their transcoding skipped (and files with the right format would be
needlessly transcoded). Thanks to Jakob Schnitzer.
* Fix an issue that caused the :ref:`id3v23` option to work only occasionally.
* Also fix using :ref:`id3v23` in conjunction with the ``scrub`` and
``embedart`` plugins. Thanks to Chris Cogburn.
* :doc:`/plugins/ihate`: Fix an error when importing singletons. Thanks to
Mathijs de Bruin.
* The :ref:`clutter` option can now be a whitespace-separated list in addition
to a YAML list.
* Values for the :ref:`replace` option can now be empty (i.e., null is
equivalent to the empty string).
* :doc:`/plugins/lastgenre`: Fix a conflict between canonicalization and
multiple genres.
* When a match has a year but not a month or day, the autotagger now "zeros
out" the month and day fields after applying the year.
* For plugin developers: added an ``optparse`` callback utility function for
performing actions based on arguments. Thanks to Pedro Silva.
* :doc:`/plugins/scrub`: Fix scrubbing of MPEG-4 files. Thanks to Yevgeny
Bezman.


.. _Acoustic Attributes: https://web.archive.org/web/20160701063109/http://developer.echonest.com/acoustic-attributes.html
.. _MPD: https://www.musicpd.org/