Beets

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

This is primarily a bug fix release: it cleans up a couple of regressions that
appeared in the last version. But it also features the triumphant return of the
:doc:`/plugins/beatport` and a modernized :doc:`/plugins/bpd`.

It's also the first version where beets passes all its tests on Windows! May
this herald a new age of cross-platform reliability for beets.

New features:

* :doc:`/plugins/beatport`: This metadata source plugin has arisen from the
dead! It now works with Beatport's new OAuth-based API. Thanks to
:user:`jbaiter`. :bug:`1989` :bug:`2067`
* :doc:`/plugins/bpd`: The plugin now uses the modern GStreamer 1.0 instead of
the old 0.10. Thanks to :user:`philippbeckmann`. :bug:`2057` :bug:`2062`
* A new ``--force`` option for the :ref:`remove-cmd` command allows removal of
items without prompting beforehand. :bug:`2042`
* A new :ref:`duplicate_action` importer config option controls how duplicate
albums or tracks treated in import task. :bug:`185`

Some fixes for Windows:

* Queries are now detected as paths when they contain backslashes (in
addition to forward slashes). This only applies on Windows.
* :doc:`/plugins/embedart`: Image similarity comparison with ImageMagick
should now work on Windows.
* :doc:`/plugins/fetchart`: The plugin should work more reliably with
non-ASCII paths.

And other fixes:

* :doc:`/plugins/replaygain`: The ``bs1770gain`` backend now correctly
calculates sample peak instead of true peak. This comes with a major
speed increase. :bug:`2031`
* :doc:`/plugins/lyrics`: Avoid a crash and a spurious warning introduced in
the last version about a Google API key, which appeared even when you hadn't
enabled the Google lyrics source.
* Fix a hard-coded path to ``bash-completion`` to work better with Homebrew
installations. Thanks to :user:`bismark`. :bug:`2038`
* Fix a crash introduced in the previous version when the standard input was
connected to a Unix pipe. :bug:`2041`
* Fix a crash when specifying non-ASCII format strings on the command line
with the ``-f`` option for many commands. :bug:`2063`
* :doc:`/plugins/fetchart`: Determine the file extension for downloaded images
based on the image's magic bytes. The plugin prints a warning if result is
not consistent with the server-supplied ``Content-Type`` header. In previous
versions, the plugin would use a ``.jpg`` extension for all images.
:bug:`2053`

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

This update adds a new :doc:`/plugins/hook` that lets you integrate beets with
command-line tools and an :doc:`/plugins/export` that can dump data from the
beets database as JSON. You can also automatically translate lyrics using a
machine translation service.

The ``echonest`` plugin has been removed in this version because the API it
used is `shutting down`_. You might want to try the
:doc:`/plugins/acousticbrainz` instead.

.. _shutting down: https://developer.spotify.com/news-stories/2016/03/29/api-improvements-update/

Some of the larger new features:

* The new :doc:`/plugins/hook` lets you execute commands in response to beets
events.
* The new :doc:`/plugins/export` can export data from beets' database as
JSON. Thanks to :user:`GuilhermeHideki`.
* :doc:`/plugins/lyrics`: The plugin can now translate the fetched lyrics to
your native language using the Bing translation API. Thanks to
:user:`Kraymer`.
* :doc:`/plugins/fetchart`: Album art can now be fetched from `fanart.tv`_.

Smaller new things:

* There are two new functions available in templates: ``%first`` and ``%ifdef``.
See :ref:`template-functions`.
* :doc:`/plugins/convert`: A new `album_art_maxwidth` setting lets you resize
album art while copying it.
* :doc:`/plugins/convert`: The `extension` setting is now optional for
conversion formats. By default, the extension is the same as the name of the
configured format.
* :doc:`/plugins/importadded`: A new `preserve_write_mtimes` option
lets you preserve mtime of files even when beets updates their metadata.
* :doc:`/plugins/fetchart`: The `enforce_ratio` option now lets you tolerate
images that are *almost* square but differ slightly from an exact 1:1
aspect ratio.
* :doc:`/plugins/fetchart`: The plugin can now optionally save the artwork's
source in an attribute in the database.
* The :ref:`terminal_encoding` configuration option can now also override the
*input* encoding. (Previously, it only affected the encoding of the standard
*output* stream.)
* A new :ref:`ignore_hidden` configuration option lets you ignore files that
your OS marks as invisible.
* :doc:`/plugins/web`: A new `values` endpoint lets you get the distinct values
of a field. Thanks to :user:`sumpfralle`. :bug:`2010`

.. _fanart.tv: https://fanart.tv/

Fixes:

* Fix a problem with the :ref:`stats-cmd` command in exact mode when filenames
on Windows use non-ASCII characters. :bug:`1891`
* Fix a crash when iTunes Sound Check tags contained invalid data. :bug:`1895`
* :doc:`/plugins/mbcollection`: The plugin now redacts your MusicBrainz
password in the ``beet config`` output. :bug:`1907`
* :doc:`/plugins/scrub`: Fix an occasional problem where scrubbing on import
could undo the :ref:`id3v23` setting. :bug:`1903`
* :doc:`/plugins/lyrics`: Add compatibility with some changes to the
LyricsWiki page markup. :bug:`1912` :bug:`1909`
* :doc:`/plugins/lyrics`: Fix retrieval from Musixmatch by improving the way
we guess the URL for lyrics on that service. :bug:`1880`
* :doc:`/plugins/edit`: Fail gracefully when the configured text editor
command can't be invoked. :bug:`1927`
* :doc:`/plugins/fetchart`: Fix a crash in the Wikipedia backend on non-ASCII
artist and album names. :bug:`1960`
* :doc:`/plugins/convert`: Change the default `ogg` encoding quality from 2 to
3 (to fit the default from the `oggenc(1)` manpage). :bug:`1982`
* :doc:`/plugins/convert`: The `never_convert_lossy_files` option now
considers AIFF a lossless format. :bug:`2005`
* :doc:`/plugins/web`: A proper 404 error, instead of an internal exception,
is returned when missing album art is requested. Thanks to
:user:`sumpfralle`. :bug:`2011`
* Tolerate more malformed floating-point numbers in metadata tags. :bug:`2014`
* The :ref:`ignore` configuration option now includes the ``lost+found``
directory by default.
* :doc:`/plugins/acousticbrainz`: AcousticBrainz lookups are now done over
HTTPS. Thanks to :user:`Freso`. :bug:`2007`

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

This release introduces one new plugin to fetch audio information from the
`AcousticBrainz`_ project and another plugin to make it easier to submit your
handcrafted metadata back to MusicBrainz.
The importer also gained two oft-requested features: a way to skip the initial
search process by specifying an ID ahead of time, and a way to *manually*
provide metadata in the middle of the import process (via the
:doc:`/plugins/edit`).

Also, as of this release, the beets project has some new Internet homes! Our
new domain name is `beets.io`_, and we have a shiny new GitHub organization:
`beetbox`_.

Here are the big new features:

* A new :doc:`/plugins/acousticbrainz` fetches acoustic-analysis information
from the `AcousticBrainz`_ project. Thanks to :user:`opatel99`, and thanks
to `Google Code-In`_! :bug:`1784`
* A new :doc:`/plugins/mbsubmit` lets you print music's current metadata in a
format that the MusicBrainz data parser can understand. You can trigger it
during an interactive import session. :bug:`1779`
* A new ``--search-id`` importer option lets you manually specify
IDs (i.e., MBIDs or Discogs IDs) for imported music. Doing this skips the
initial candidate search, which can be important for huge albums where this
initial lookup is slow.
Also, the ``enter Id`` prompt choice now accepts several IDs, separated by
spaces. :bug:`1808`
* :doc:`/plugins/edit`: You can now edit metadata *on the fly* during the
import process. The plugin provides two new interactive options: one to edit
*your music's* metadata, and one to edit the *matched metadata* retrieved
from MusicBrainz (or another data source). This feature is still in its
early stages, so please send feedback if you find anything missing.
:bug:`1846` :bug:`396`

There are even more new features:

* :doc:`/plugins/fetchart`: The Google Images backend has been restored. It
now requires an API key from Google. Thanks to :user:`lcharlick`.
:bug:`1778`
* :doc:`/plugins/info`: A new option will print only fields' names and not
their values. Thanks to :user:`GuilhermeHideki`. :bug:`1812`
* The :ref:`fields-cmd` command now displays flexible attributes.
Thanks to :user:`GuilhermeHideki`. :bug:`1818`
* The :ref:`modify-cmd` command lets you interactively select which albums or
items you want to change. :bug:`1843`
* The :ref:`move-cmd` command gained a new ``--timid`` flag to print and
confirm which files you want to move. :bug:`1843`
* The :ref:`move-cmd` command no longer prints filenames for files that
don't actually need to be moved. :bug:`1583`

.. _Google Code-In: https://codein.withgoogle.com/
.. _AcousticBrainz: https://acousticbrainz.org/

Fixes:

* :doc:`/plugins/play`: Fix a regression in the last version where there was
no default command. :bug:`1793`
* :doc:`/plugins/lastimport`: The plugin now works again after being broken by
some unannounced changes to the Last.fm API. :bug:`1574`
* :doc:`/plugins/play`: Fixed a typo in a configuration option. The option is
now ``warning_threshold`` instead of ``warning_treshold``, but we kept the
old name around for compatibility. Thanks to :user:`JesseWeinstein`.
:bug:`1802` :bug:`1803`
* :doc:`/plugins/edit`: Editing metadata now moves files, when appropriate
(like the :ref:`modify-cmd` command). :bug:`1804`
* The :ref:`stats-cmd` command no longer crashes when files are missing or
inaccessible. :bug:`1806`
* :doc:`/plugins/fetchart`: Possibly fix a Unicode-related crash when using
some versions of pyOpenSSL. :bug:`1805`
* :doc:`/plugins/replaygain`: Fix an intermittent crash with the GStreamer
backend. :bug:`1855`
* :doc:`/plugins/lastimport`: The plugin now works with the beets API key by
default. You can still provide a different key the configuration.
* :doc:`/plugins/replaygain`: Fix a crash using the Python Audio Tools
backend. :bug:`1873`

.. _beets.io: https://beets.io/
.. _Beetbox: https://github.com/beetbox

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

The big news in this release is a new :doc:`interactive editor plugin
</plugins/edit>`. It's really nifty: you can now change your music's metadata
by making changes in a visual text editor, which can sometimes be far more
efficient than the built-in :ref:`modify-cmd` command. No more carefully
retyping the same artist name with slight capitalization changes.

This version also adds an oft-requested "not" operator to beets' queries, so
you can exclude music from any operation. It also brings friendlier formatting
(and querying!) of song durations.

The big new stuff:

* A new :doc:`/plugins/edit` lets you manually edit your music's metadata
using your favorite text editor. :bug:`164` :bug:`1706`
* Queries can now use "not" logic. Type a ``^`` before part of a query to
*exclude* matching music from the results. For example, ``beet list -a
beatles ^album:1`` will find all your albums by the Beatles except for their
singles compilation, "1." See :ref:`not_query`. :bug:`819` :bug:`1728`
* A new :doc:`/plugins/embyupdate` can trigger a library refresh on an `Emby`_
server when your beets database changes.
* Track length is now displayed as "M:SS" rather than a raw number of seconds.
Queries on track length also accept this format: for example, ``beet list
length:5:30..`` will find all your tracks that have a duration over 5
minutes and 30 seconds. You can turn off this new behavior using the
``format_raw_length`` configuration option. :bug:`1749`

Smaller changes:

* Three commands, ``modify``, ``update``, and ``mbsync``, would previously
move files by default after changing their metadata. Now, these commands
will only move files if you have the :ref:`config-import-copy` or
:ref:`config-import-move` options enabled in your importer configuration.
This way, if you configure the importer not to touch your filenames, other
commands will respect that decision by default too. Each command also
sprouted a ``--move`` command-line option to override this default (in
addition to the ``--nomove`` flag they already had). :bug:`1697`
* A new configuration option, ``va_name``, controls the album artist name for
various-artists albums. The setting defaults to "Various Artists," the
MusicBrainz standard. In order to match MusicBrainz, the
:doc:`/plugins/discogs` also adopts the same setting.
* :doc:`/plugins/info`: The ``info`` command now accepts a ``-f/--format``
option for customizing how items are displayed, just like the built-in
``list`` command. :bug:`1737`

Some changes for developers:

* Two new :ref:`plugin hooks <plugin_events>`, ``albuminfo_received`` and
``trackinfo_received``, let plugins intercept metadata as soon as it is
received, before it is applied to music in the database. :bug:`872`
* Plugins can now add options to the interactive importer prompts. See
:ref:`append_prompt_choices`. :bug:`1758`

Fixes:

* :doc:`/plugins/plexupdate`: Fix a crash when Plex libraries use non-ASCII
collection names. :bug:`1649`
* :doc:`/plugins/discogs`: Maybe fix a crash when using some versions of the
``requests`` library. :bug:`1656`
* Fix a race in the importer when importing two albums with the same artist
and name in quick succession. The importer would fail to detect them as
duplicates, claiming that there were "empty albums" in the database even
when there were not. :bug:`1652`
* :doc:`plugins/lastgenre`: Clean up the reggae-related genres somewhat.
Thanks to :user:`Freso`. :bug:`1661`
* The importer now correctly moves album art files when re-importing.
:bug:`314`
* :doc:`/plugins/fetchart`: In auto mode, the plugin now skips albums that
already have art attached to them so as not to interfere with re-imports.
:bug:`314`
* :doc:`plugins/fetchart`: The plugin now only resizes album art if necessary,
rather than always by default. :bug:`1264`
* :doc:`plugins/fetchart`: Fix a bug where a database reference to a
non-existent album art file would prevent the command from fetching new art.
:bug:`1126`
* :doc:`/plugins/thumbnails`: Fix a crash with Unicode paths. :bug:`1686`
* :doc:`/plugins/embedart`: The ``remove_art_file`` option now works on import
(as well as with the explicit command). :bug:`1662` :bug:`1675`
* :doc:`/plugins/metasync`: Fix a crash when syncing with recent versions of
iTunes. :bug:`1700`
* :doc:`/plugins/duplicates`: Fix a crash when merging items. :bug:`1699`
* :doc:`/plugins/smartplaylist`: More gracefully handle malformed queries and
missing configuration.
* Fix a crash with some files with unreadable iTunes SoundCheck metadata.
:bug:`1666`
* :doc:`/plugins/thumbnails`: Fix a nasty segmentation fault crash that arose
with some library versions. :bug:`1433`
* :doc:`/plugins/convert`: Fix a crash with Unicode paths in ``--pretend``
mode. :bug:`1735`
* Fix a crash when sorting by nonexistent fields on queries. :bug:`1734`
* Probably fix some mysterious errors when dealing with images using
ImageMagick on Windows. :bug:`1721`
* Fix a crash when writing some Unicode comment strings to MP3s that used
older encodings. The encoding is now always updated to UTF-8. :bug:`879`
* :doc:`/plugins/fetchart`: The Google Images backend has been removed. It
used an API that has been shut down. :bug:`1760`
* :doc:`/plugins/lyrics`: Fix a crash in the Google backend when searching for
bands with regular-expression characters in their names, like Sunn O))).
:bug:`1673`
* :doc:`/plugins/scrub`: In ``auto`` mode, the plugin now *actually* only
scrubs files on import, as the documentation always claimed it did---not
every time files were written, as it previously did. :bug:`1657`
* :doc:`/plugins/scrub`: Also in ``auto`` mode, album art is now correctly
restored. :bug:`1657`
* Possibly allow flexible attributes to be used with the ``%aunique`` template
function. :bug:`1775`
* :doc:`/plugins/lyrics`: The Genius backend is now more robust to
communication errors. The backend has also been disabled by default, since
the API it depends on is currently down. :bug:`1770`

.. _Emby: https://emby.media

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

This release adds a new plugin for checking file quality and a new source for
lyrics. The larger features are:

* A new :doc:`/plugins/badfiles` helps you scan for corruption in your music
collection. Thanks to :user:`fxthomas`. :bug:`1568`
* :doc:`/plugins/lyrics`: You can now fetch lyrics from Genius.com.
Thanks to :user:`sadatay`. :bug:`1626` :bug:`1639`
* :doc:`/plugins/zero`: The plugin can now use a "whitelist" policy as an
alternative to the (default) "blacklist" mode. Thanks to :user:`adkow`.
:bug:`1621` :bug:`1641`

And there are smaller new features too:

* Add new color aliases for standard terminal color names (e.g., cyan and
magenta). Thanks to :user:`mathstuf`. :bug:`1548`
* :doc:`/plugins/play`: A new ``--args`` option lets you specify options for
the player command. :bug:`1532`
* :doc:`/plugins/play`: A new ``raw`` configuration option lets the command
work with players (such as VLC) that expect music filenames as arguments,
rather than in a playlist. Thanks to :user:`nathdwek`. :bug:`1578`
* :doc:`/plugins/play`: You can now configure the number of tracks that
trigger a "lots of music" warning. :bug:`1577`
* :doc:`/plugins/embedart`: A new ``remove_art_file`` option lets you clean up
if you prefer *only* embedded album art. Thanks to :user:`jackwilsdon`.
:bug:`1591` :bug:`733`
* :doc:`/plugins/plexupdate`: A new ``library_name`` option allows you to select
which Plex library to update. :bug:`1572` :bug:`1595`
* A new ``include`` option lets you import external configuration files.

This release has plenty of fixes:

* :doc:`/plugins/lastgenre`: Fix a bug that prevented tag popularity from
being considered. Thanks to :user:`svoos`. :bug:`1559`
* Fixed a bug where plugins wouldn't be notified of the deletion of an item's
art, for example with the ``clearart`` command from the
:doc:`/plugins/embedart`. Thanks to :user:`nathdwek`. :bug:`1565`
* :doc:`/plugins/fetchart`: The Google Images source is disabled by default
(as it was before beets 1.3.9), as is the Wikipedia source (which was
causing lots of unnecessary delays due to DBpedia downtime). To re-enable
these sources, add ``wikipedia google`` to your ``sources`` configuration
option.
* The :ref:`list-cmd` command's help output now has a small query and format
string example. Thanks to :user:`pkess`. :bug:`1582`
* :doc:`/plugins/fetchart`: The plugin now fetches PNGs but not GIFs. (It
still fetches JPEGs.) This avoids an error when trying to embed images,
since not all formats support GIFs. :bug:`1588`
* Date fields are now written in the correct order (year-month-day), which
eliminates an intermittent bug where the latter two fields would not get
written to files. Thanks to :user:`jdetrey`. :bug:`1303` :bug:`1589`
* :doc:`/plugins/replaygain`: Avoid a crash when the PyAudioTools backend
encounters an error. :bug:`1592`
* The case sensitivity of path queries is more useful now: rather than just
guessing based on the platform, we now check the case sensitivity of your
filesystem. :bug:`1586`
* Case-insensitive path queries might have returned nothing because of a
wrong SQL query.
* Fix a crash when a query contains a "+" or "-" alone in a component.
:bug:`1605`
* Fixed unit of file size to powers of two (MiB, GiB, etc.) instead of powers
of ten (MB, GB, etc.). :bug:`1623`

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

This is mainly a bugfix release, but we also have a nifty new plugin for
`ipfs`_ and a bunch of new configuration options.

The new features:

* A new :doc:`/plugins/ipfs` lets you share music via a new, global,
decentralized filesystem. :bug:`1397`
* :doc:`/plugins/duplicates`: You can now merge duplicate
track metadata (when detecting duplicate items), or duplicate album
tracks (when detecting duplicate albums).
* :doc:`/plugins/duplicates`: Duplicate resolution now uses an ordering to
prioritize duplicates. By default, it prefers music with more complete
metadata, but you can configure it to use any list of attributes.
* :doc:`/plugins/metasync`: Added a new backend to fetch metadata from iTunes.
This plugin is still in an experimental phase. :bug:`1450`
* The `move` command has a new ``--pretend`` option, making the command show
how the items will be moved without actually changing anything.
* The importer now supports matching of "pregap" or HTOA (hidden track-one
audio) tracks when they are listed in MusicBrainz. (This feature depends on a
new version of the `python-musicbrainzngs`_ library that is not yet released, but
will start working when it is available.) Thanks to :user:`ruippeixotog`.
:bug:`1104` :bug:`1493`
* :doc:`/plugins/plexupdate`: A new ``token`` configuration option lets you
specify a key for Plex Home setups. Thanks to :user:`edcarroll`. :bug:`1494`

Fixes:

* :doc:`/plugins/fetchart`: Complain when the `enforce_ratio`
or `min_width` options are enabled but no local imaging backend is available
to carry them out. :bug:`1460`
* :doc:`/plugins/importfeeds`: Avoid generating incorrect m3u filename when
both of the `m3u` and `m3u_multi` options are enabled. :bug:`1490`
* :doc:`/plugins/duplicates`: Avoid a crash when misconfigured. :bug:`1457`
* :doc:`/plugins/mpdstats`: Avoid a crash when the music played is not in the
beets library. Thanks to :user:`CodyReichert`. :bug:`1443`
* Fix a crash with ArtResizer on Windows systems (affecting
:doc:`/plugins/embedart`, :doc:`/plugins/fetchart`,
and :doc:`/plugins/thumbnails`). :bug:`1448`
* :doc:`/plugins/permissions`: Fix an error with non-ASCII paths. :bug:`1449`
* Fix sorting by paths when the :ref:`sort_case_insensitive` option is
enabled. :bug:`1451`
* :doc:`/plugins/embedart`: Avoid an error when trying to embed invalid images
into MPEG-4 files.
* :doc:`/plugins/fetchart`: The Wikipedia source can now better deal artists
that use non-standard capitalization (e.g., alt-J, dEUS).
* :doc:`/plugins/web`: Fix searching for non-ASCII queries. Thanks to
:user:`oldtopman`. :bug:`1470`
* :doc:`/plugins/mpdupdate`: We now recommend the newer ``python-mpd2``
library instead of its unmaintained parent. Thanks to :user:`Somasis`.
:bug:`1472`
* The importer interface and log file now output a useful list of files
(instead of the word "None") when in album-grouping mode. :bug:`1475`
:bug:`825`
* Fix some logging errors when filenames and other user-provided strings
contain curly braces. :bug:`1481`
* Regular expression queries over paths now work more reliably with non-ASCII
characters in filenames. :bug:`1482`
* Fix a bug where the autotagger's :ref:`ignored` setting was sometimes, well,
ignored. :bug:`1487`
* Fix a bug with Unicode strings when generating image thumbnails. :bug:`1485`
* :doc:`/plugins/keyfinder`: Fix handling of Unicode paths. :bug:`1502`
* :doc:`/plugins/fetchart`: When album art is already present, the message is
now printed in the ``text_highlight_minor`` color (light gray). Thanks to
:user:`Somasis`. :bug:`1512`
* Some messages in the console UI now use plural nouns correctly. Thanks to
:user:`JesseWeinstein`. :bug:`1521`
* Sorting numerical fields (such as track) now works again. :bug:`1511`
* :doc:`/plugins/replaygain`: Missing GStreamer plugins now cause a helpful
error message instead of a crash. :bug:`1518`
* Fix an edge case when producing sanitized filenames where the maximum path
length conflicted with the :ref:`replace` rules. Thanks to Ben Ockmore.
:bug:`496` :bug:`1361`
* Fix an incompatibility with OS X 10.11 (where ``/usr/sbin`` seems not to be
on the user's path by default).
* Fix an incompatibility with certain JPEG files. Here's a relevant `Python
bug`_. Thanks to :user:`nathdwek`. :bug:`1545`
* Fix the :ref:`group_albums` importer mode so that it works correctly when
files are not already in order by album. :bug:`1550`
* The ``fields`` command no longer separates built-in fields from
plugin-provided ones. This distinction was becoming increasingly unreliable.
* :doc:`/plugins/duplicates`: Fix a Unicode warning when paths contained
non-ASCII characters. :bug:`1551`
* :doc:`/plugins/fetchart`: Work around a urllib3 bug that could cause a
crash. :bug:`1555` :bug:`1556`
* When you edit the configuration file with ``beet config -e`` and the file
does not exist, beets creates an empty file before editing it. This fixes an
error on OS X, where the ``open`` command does not work with non-existent
files. :bug:`1480`
* :doc:`/plugins/convert`: Fix a problem with filename encoding on Windows
under Python 3. :bug:`2515` :bug:`2516`

.. _Python bug: https://bugs.python.org/issue16512
.. _ipfs: https://ipfs.io