Beets

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

Changelog goes here!

New features:

* :doc:`/plugins/kodiupdate`: Now supports multiple kodi instances
:bug:`4101`
* Add the item fields ``bitrate_mode``, ``encoder_info`` and ``encoder_settings``.
* Add query prefixes ``=`` and ``~``.

Bug fixes:

* :doc:`/plugins/convert`: Resize album art when embedding
:bug:`2116`
* :doc:`/plugins/deezer`: Fix auto tagger pagination issues (fetch beyond the
first 25 tracks of a release).
* :doc:`/plugins/spotify`: Fix auto tagger pagination issues (fetch beyond the
first 50 tracks of a release).
* :doc:`/plugins/lyrics`: Fix Genius search by using query params instead of body.
* :doc:`/plugins/unimported`: The new ``ignore_subdirectories`` configuration
option added in 1.6.0 now has a default value if it hasn't been set.
* :doc:`/plugins/deezer`: Tolerate missing fields when searching for singleton
tracks.
:bug:`4116`
* :doc:`/plugins/replaygain`: The type of the internal ``r128_track_gain`` and
``r128_album_gain`` fields was changed from integer to float to fix loss of
precision due to truncation.
:bug:`4169`
* Fix a regression in the previous release that caused a `TypeError` when
moving files across filesystems.
:bug:`4168`
* :doc:`/plugins/convert`: Deleting the original files during conversion no
longer logs output when the ``quiet`` flag is enabled.
* :doc:`plugins/web`: Fix handling of "query" requests. Previously queries
consisting of more than one token (separated by a slash) always returned an
empty result.
* :doc:`/plugins/discogs`: Skip Discogs query on insufficiently tagged files
(artist and album tags missing) to prevent arbitrary candidate results.
:bug:`4227`
* :doc:`plugins/lyrics`: Fixed issues with the Tekstowo.pl and Genius
backends where some non-lyrics content got included in the lyrics
* :doc:`plugins/limit`: Better header formatting to improve index
* :doc:`plugins/replaygain`: Correctly handle the ``overwrite`` config option,
which forces recomputing ReplayGain values on import even for tracks
that already have the tags.
* :doc:`plugins/embedart`: Fix a crash when using recent versions of
ImageMagick and the ``compare_threshold`` option.
:bug:`4272`

For packagers:

* We fixed a version for the dependency on the `Confuse`_ library.
:bug:`4167`
* The minimum required version of :pypi:`mediafile` is now 0.9.0.

Other new things:

* :doc:`/plugins/limit`: Limit query results to head or tail (``lslimit``
command only)

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

This release is our first experiment with time-based releases! We are aiming
to publish a new release of beets every 3 months. We therefore have a healthy
but not dizzyingly long list of new features and fixes.

With this release, beets now requires Python 3.6 or later (it removes support
for Python 2.7, 3.4, and 3.5). There are also a few other dependency
changes---if you're a maintainer of a beets package for a package manager,
thank you for your ongoing efforts, and please see the list of notes below.

Major new features:

* When fetching genres from MusicBrainz, we now include genres from the
release group (in addition to the release). We also prioritize genres based
on the number of votes.
Thanks to :user:`aereaux`.
* Primary and secondary release types from MusicBrainz are now stored in a new
``albumtypes`` field.
Thanks to :user:`edgars-supe`.
:bug:`2200`
* An accompanying new :doc:`/plugins/albumtypes` includes some options for
formatting this new ``albumtypes`` field.
Thanks to :user:`edgars-supe`.

Other new things:

* :doc:`/plugins/permissions`: The plugin now sets cover art permissions to
match the audio file permissions.
* :doc:`/plugins/unimported`: A new configuration option supports excluding
specific subdirectories in library.
* :doc:`/plugins/info`: Add support for an ``--album`` flag.
* :doc:`/plugins/export`: Similarly add support for an ``--album`` flag.
* ``beet move`` now highlights path differences in color (when enabled).
* When moving files and a direct rename of a file is not possible (for
example, when crossing filesystems), beets now copies to a temporary file in
the target folder first and then moves to the destination instead of
directly copying the target path. This gets us closer to always updating
files atomically.
Thanks to :user:`catap`.
:bug:`4060`
* :doc:`/plugins/fetchart`: Add a new option to store cover art as
non-progressive image. This is useful for DAPs that do not support
progressive images. Set ``deinterlace: yes`` in your configuration to enable
this conversion.
* :doc:`/plugins/fetchart`: Add a new option to change the file format of
cover art images. This may also be useful for DAPs that only support some
image formats.
* Support flexible attributes in ``%aunique``.
:bug:`2678` :bug:`3553`
* Make ``%aunique`` faster, especially when using inline fields.
:bug:`4145`

Bug fixes:

* :doc:`/plugins/lyrics`: Fix a crash when Beautiful Soup is not installed.
:bug:`4027`
* :doc:`/plugins/discogs`: Support a new Discogs URL format for IDs.
:bug:`4080`
* :doc:`/plugins/discogs`: Remove built-in rate-limiting because the Discogs
Python library we use now has its own rate-limiting.
:bug:`4108`
* :doc:`/plugins/export`: Fix some duplicated output.
* :doc:`/plugins/aura`: Fix a potential security hole when serving image
files.
:bug:`4160`

For plugin developers:

* :py:meth:`beets.library.Item.destination` now accepts a `replacements`
argument to be used in favor of the default.
* The `pluginload` event is now sent after plugin types and queries are
available, not before.
* A new plugin event, `album_removed`, is called when an album is removed from
the library (even when its file is not deleted from disk).

Here are some notes for packagers:

* As noted above, the minimum Python version is now 3.6.
* We fixed a flaky test, named `test_album_art` in the `test_zero.py` file,
that some distributions had disabled. Disabling this test should no longer
be necessary.
:bug:`4037` :bug:`4038`
* This version of beets no longer depends on the `six`_ library.
:bug:`4030`
* The `gmusic` plugin was removed since Google Play Music has been shut down.
Thus, the optional dependency on `gmusicapi` does not exist anymore.
:bug:`4089`

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

This long overdue release of beets includes far too many exciting and useful
features than could ever be satisfactorily enumerated.
As a technical detail, it also introduces two new external libraries:
`MediaFile`_ and `Confuse`_ used to be part of beets but are now reusable
dependencies---packagers, please take note.
Finally, this is the last version of beets where we intend to support Python
2.x and 3.5; future releases will soon require Python 3.6.

One non-technical change is that we moved our official ``beets`` home
on IRC from freenode to `Libera.Chat`_.

.. _Libera.Chat: https://libera.chat/

Major new features:

* Fields in queries now fall back to an item's album and check its fields too.
Notably, this allows querying items by an album's attribute: in other words,
``beet list foo:bar`` will not only find tracks with the `foo` attribute; it
will also find tracks *on albums* that have the `foo` attribute. This may be
particularly useful in the :ref:`path-format-config`, which matches
individual items to decide which path to use.
Thanks to :user:`FichteFoll`.
:bug:`2797` :bug:`2988`
* A new :ref:`reflink` config option instructs the importer to create fast,
copy-on-write file clones on filesystems that support them. Thanks to
:user:`rubdos`.
* A new :doc:`/plugins/unimported` lets you find untracked files in your
library directory.
* The :doc:`/plugins/aura` has arrived! Try out the future of remote music
library access today.
* We now fetch information about `works`_ from MusicBrainz.
MusicBrainz matches provide the fields ``work`` (the title), ``mb_workid``
(the MBID), and ``work_disambig`` (the disambiguation string).
Thanks to :user:`dosoe`.
:bug:`2580` :bug:`3272`
* A new :doc:`/plugins/parentwork` gets information about the original work,
which is useful for classical music.
Thanks to :user:`dosoe`.
:bug:`2580` :bug:`3279`
* :doc:`/plugins/bpd`: BPD now supports most of the features of version 0.16
of the MPD protocol. This is enough to get it talking to more complicated
clients like ncmpcpp, but there are still some incompatibilities, largely due
to MPD commands we don't support yet. (Let us know if you find an MPD client
that doesn't get along with BPD!)
:bug:`3214` :bug:`800`
* A new :doc:`/plugins/deezer` can autotag tracks and albums using the
`Deezer`_ database.
Thanks to :user:`rhlahuja`.
:bug:`3355`
* A new :doc:`/plugins/bareasc` provides a new query type: "bare ASCII"
queries that ignore accented characters, treating them as though they
were plain ASCII characters. Use the ` prefix with :ref:`list-cmd` or
other commands. :bug:`3882`
* :doc:`/plugins/fetchart`: The plugin can now get album art from `last.fm`_.
:bug:`3530`
* :doc:`/plugins/web`: The API now supports the HTTP `DELETE` and `PATCH`
methods for modifying items.
They are disabled by default; set ``readonly: no`` in your configuration
file to enable modification via the API.
:bug:`3870`

Other new things:

* ``beet remove`` now also allows interactive selection of items from the query,
similar to ``beet modify``.
* Enable HTTPS for MusicBrainz by default and add configuration option
`https` for custom servers. See :ref:`musicbrainz-config` for more details.
* :doc:`/plugins/mpdstats`: Add a new `strip_path` option to help build the
right local path from MPD information.
* :doc:`/plugins/convert`: Conversion can now parallelize conversion jobs on
Python 3.
* :doc:`/plugins/lastgenre`: Add a new `title_case` config option to make
title-case formatting optional.
* There's a new message when running ``beet config`` when there's no available
configuration file.
:bug:`3779`
* When importing a duplicate album, the prompt now says "keep all" instead of
"keep both" to reflect that there may be more than two albums involved.
:bug:`3569`
* :doc:`/plugins/chroma`: The plugin now updates file metadata after
generating fingerprints through the `submit` command.
* :doc:`/plugins/lastgenre`: Added more heavy metal genres to the built-in
genre filter lists.
* A new :doc:`/plugins/subsonicplaylist` can import playlists from a Subsonic
server.
* :doc:`/plugins/subsonicupdate`: The plugin now automatically chooses between
token- and password-based authentication based on the server version.
* A new :ref:`extra_tags` configuration option lets you use more metadata in
MusicBrainz queries to further narrow the search.
* A new :doc:`/plugins/fish` adds `Fish shell`_ tab autocompletion to beets.
* :doc:`plugins/fetchart` and :doc:`plugins/embedart`: Added a new ``quality``
option that controls the quality of the image output when the image is
resized.
* :doc:`plugins/keyfinder`: Added support for `keyfinder-cli`_.
Thanks to :user:`BrainDamage`.
* :doc:`plugins/fetchart`: Added a new ``high_resolution`` config option to
allow downloading of higher resolution iTunes artwork (at the expense of
file size).
:bug:`3391`
* :doc:`plugins/discogs`: The plugin applies two new fields: `discogs_labelid`
and `discogs_artistid`.
:bug:`3413`
* :doc:`/plugins/export`: Added a new ``-f`` (``--format``) flag,
which can export your data as JSON, JSON lines, CSV, or XML.
Thanks to :user:`austinmm`.
:bug:`3402`
* :doc:`/plugins/convert`: Added a new ``-l`` (``--link``) flag and ``link``
option as well as the ``-H`` (``--hardlink``) flag and ``hardlink``
option, which symlink or hardlink files that do not need to
be converted (instead of copying them).
:bug:`2324`
* :doc:`/plugins/replaygain`: The plugin now supports a ``per_disc`` option
that enables calculation of album ReplayGain on disc level instead of album
level.
Thanks to :user:`samuelnilsson`.
:bug:`293`
* :doc:`/plugins/replaygain`: The new ``ffmpeg`` ReplayGain backend supports
``R128_`` tags.
:bug:`3056`
* :doc:`plugins/replaygain`: A new ``r128_targetlevel`` configuration option
defines the reference volume for files using ``R128_`` tags. ``targetlevel``
only configures the reference volume for ``REPLAYGAIN_`` files.
:bug:`3065`
* :doc:`/plugins/discogs`: The plugin now collects the "style" field.
Thanks to :user:`thedevilisinthedetails`.
:bug:`2579` :bug:`3251`
* :doc:`/plugins/absubmit`: By default, the plugin now avoids re-analyzing
files that already have AcousticBrainz data.
There are new ``force`` and ``pretend`` options to help control this new
behavior.
Thanks to :user:`SusannaMaria`.
:bug:`3318`
* :doc:`/plugins/discogs`: The plugin now also gets genre information and a
new ``discogs_albumid`` field from the Discogs API.
Thanks to :user:`thedevilisinthedetails`.
:bug:`465` :bug:`3322`
* :doc:`/plugins/acousticbrainz`: The plugin now fetches two more additional
fields: ``moods_mirex`` and ``timbre``.
Thanks to :user:`malcops`.
:bug:`2860`
* :doc:`/plugins/playlist` and :doc:`/plugins/smartplaylist`: A new
``forward_slash`` config option facilitates compatibility with MPD on
Windows.
Thanks to :user:`MartyLake`.
:bug:`3331` :bug:`3334`
* The `data_source` field, which indicates which metadata source was used
during an autotagging import, is now also applied as an album-level flexible
attribute.
:bug:`3350` :bug:`1693`
* :doc:`/plugins/beatport`: The plugin now gets the musical key, BPM, and
genre for each track.
:bug:`2080`
* A new :doc:`/plugins/bpsync` can synchronize metadata changes from the
Beatport database (like the existing :doc:`/plugins/mbsync` for MusicBrainz).
* :doc:`/plugins/hook`: The plugin now treats non-zero exit codes as errors.
:bug:`3409`
* :doc:`/plugins/subsonicupdate`: A new ``url`` configuration replaces the
older (and now deprecated) separate ``host``, ``port``, and ``contextpath``
config options. As a consequence, the plugin can now talk to Subsonic over
HTTPS.
Thanks to :user:`jef`.
:bug:`3449`
* :doc:`/plugins/discogs`: The new ``index_tracks`` option enables
incorporation of work names and intra-work divisions into imported track
titles.
Thanks to :user:`cole-miller`.
:bug:`3459`
* :doc:`/plugins/web`: The query API now interprets backslashes as path
separators to support path queries.
Thanks to :user:`nmeum`.
:bug:`3567`
* ``beet import`` now handles tar archives with bzip2 or gzip compression.
:bug:`3606`
* ``beet import`` *also* now handles 7z archives, via the `py7zr`_ library.
Thanks to :user:`arogl`.
:bug:`3906`
* :doc:`/plugins/plexupdate`: Added an option to use a secure connection to
Plex server, and to ignore certificate validation errors if necessary.
:bug:`2871`
* :doc:`/plugins/convert`: A new ``delete_originals`` configuration option can
delete the source files after conversion during import.
Thanks to :user:`logan-arens`.
:bug:`2947`
* There is a new ``--plugins`` (or ``-p``) CLI flag to specify a list of
plugins to load.
* A new :ref:`genres` option fetches genre information from MusicBrainz. This
functionality depends on functionality that is currently unreleased in the
`python-musicbrainzngs`_ library: see PR `266
<https://github.com/alastair/python-musicbrainzngs/pull/266>`_.
Thanks to :user:`aereaux`.
* :doc:`/plugins/replaygain`: Analysis now happens in parallel using the
``command`` and ``ffmpeg`` backends.
:bug:`3478`
* :doc:`plugins/replaygain`: The bs1770gain backend is removed.
Thanks to :user:`SamuelCook`.
* Added ``trackdisambig`` which stores the recording disambiguation from
MusicBrainz for each track.
:bug:`1904`
* :doc:`plugins/fetchart`: The new ``max_filesize`` configuration sets a
maximum target image file size.
* :doc:`/plugins/badfiles`: Checkers can now run during import with the
``check_on_import`` config option.
* :doc:`/plugins/export`: The plugin is now much faster when using the
`--include-keys` option is used.
Thanks to :user:`ssssam`.
* The importer's :ref:`set_fields` option now saves all updated fields to
on-disk metadata.
:bug:`3925` :bug:`3927`
* We now fetch ISRC identifiers from MusicBrainz.
Thanks to :user:`aereaux`.
* :doc:`/plugins/metasync`: The plugin now also fetches the "Date Added" field
from iTunes databases and stores it in the ``itunes_dateadded`` field.
Thanks to :user:`sandersantema`.
* :doc:`/plugins/lyrics`: Added a new Tekstowo.pl lyrics provider. Thanks to
various people for the implementation and for reporting issues with the
initial version.
:bug:`3344` :bug:`3904` :bug:`3905` :bug:`3994`
* ``beet update`` will now confirm that the user still wants to update if
their library folder cannot be found, preventing the user from accidentally
wiping out their beets database.
Thanks to user: `logan-arens`.
:bug:`1934`

Fixes:

* Adapt to breaking changes in Python's ``ast`` module in Python 3.8.
* :doc:`/plugins/beatport`: Fix the assignment of the `genre` field, and
rename `musical_key` to `initial_key`.
:bug:`3387`
* :doc:`/plugins/lyrics`: Fixed the Musixmatch backend for lyrics pages when
lyrics are divided into multiple elements on the webpage, and when the
lyrics are missing.
* :doc:`/plugins/web`: Allow use of the backslash character in regex queries.
:bug:`3867`
* :doc:`/plugins/web`: Fixed a small bug that caused the album art path to be
redacted even when ``include_paths`` option is set.
:bug:`3866`
* :doc:`/plugins/discogs`: Fixed a bug with the ``index_tracks`` option that
sometimes caused the index to be discarded. Also, remove the extra semicolon
that was added when there is no index track.
* :doc:`/plugins/subsonicupdate`: The API client was using the `POST` method
rather the `GET` method.
Also includes better exception handling, response parsing, and tests.
* :doc:`/plugins/the`: Fixed incorrect regex for "the" that matched any
3-letter combination of the letters t, h, e.
:bug:`3701`
* :doc:`/plugins/fetchart`: Fixed a bug that caused the plugin to not take
environment variables, such as proxy servers, into account when making
requests.
:bug:`3450`
* :doc:`/plugins/fetchart`: Temporary files for fetched album art that fail
validation are now removed.
* :doc:`/plugins/inline`: In function-style field definitions that refer to
flexible attributes, values could stick around from one function invocation
to the next. This meant that, when displaying a list of objects, later
objects could seem to reuse values from earlier objects when they were
missing a value for a given field. These values are now properly undefined.
:bug:`2406`
* :doc:`/plugins/bpd`: Seeking by fractions of a second now works as intended,
fixing crashes in MPD clients like mpDris2 on seek.
The ``playlistid`` command now works properly in its zero-argument form.
:bug:`3214`
* :doc:`/plugins/replaygain`: Fix a Python 3 incompatibility in the Python
Audio Tools backend.
:bug:`3305`
* :doc:`/plugins/importadded`: Fixed a crash that occurred when the
``after_write`` signal was emitted.
:bug:`3301`
* :doc:`plugins/replaygain`: Fix the storage format for R128 gain tags.
:bug:`3311` :bug:`3314`
* :doc:`/plugins/discogs`: Fixed a crash that occurred when the master URI
isn't set in the API response.
:bug:`2965` :bug:`3239`
* :doc:`/plugins/spotify`: Fix handling of year-only release dates
returned by the Spotify albums API.
Thanks to :user:`rhlahuja`.
:bug:`3343`
* Fixed a bug that caused the UI to display incorrect track numbers for tracks
with index 0 when the ``per_disc_numbering`` option was set.
:bug:`3346`
* ``none_rec_action`` does not import automatically when ``timid`` is enabled.
Thanks to :user:`RollingStar`.
:bug:`3242`
* Fix a bug that caused a crash when tagging items with the beatport plugin.
:bug:`3374`
* ``beet import`` now logs which files are ignored when in debug mode.
:bug:`3764`
* :doc:`/plugins/bpd`: Fix the transition to next track when in consume mode.
Thanks to :user:`aereaux`.
:bug:`3437`
* :doc:`/plugins/lyrics`: Fix a corner-case with Genius lowercase artist names
:bug:`3446`
* :doc:`/plugins/parentwork`: Don't save tracks when nothing has changed.
:bug:`3492`
* Added a warning when configuration files defined in the `include` directive
of the configuration file fail to be imported.
:bug:`3498`
* Added normalization to integer values in the database, which should avoid
problems where fields like ``bpm`` would sometimes store non-integer values.
:bug:`762` :bug:`3507` :bug:`3508`
* Fix a crash when querying for null values.
:bug:`3516` :bug:`3517`
* :doc:`/plugins/lyrics`: Tolerate a missing lyrics div in the Genius scraper.
Thanks to :user:`thejli21`.
:bug:`3535` :bug:`3554`
* :doc:`/plugins/lyrics`: Use the artist sort name to search for lyrics, which
can help find matches when the artist name has special characters.
Thanks to :user:`hashhar`.
:bug:`3340` :bug:`3558`
* :doc:`/plugins/replaygain`: Trying to calculate volume gain for an album
consisting of some formats using ``ReplayGain`` and some using ``R128``
will no longer crash; instead it is skipped and and a message is logged.
The log message has also been rewritten for to improve clarity.
Thanks to :user:`autrimpo`.
:bug:`3533`
* :doc:`/plugins/lyrics`: Adapt the Genius backend to changes in markup to
reduce the scraping failure rate.
:bug:`3535` :bug:`3594`
* :doc:`/plugins/lyrics`: Fix a crash when writing ReST files for a query
without results or fetched lyrics.
:bug:`2805`
* :doc:`/plugins/fetchart`: Attempt to fetch pre-resized thumbnails from Cover
Art Archive if the ``maxwidth`` option matches one of the sizes supported by
the Cover Art Archive API.
Thanks to :user:`trolley`.
:bug:`3637`
* :doc:`/plugins/ipfs`: Fix Python 3 compatibility.
Thanks to :user:`musoke`.
:bug:`2554`
* Fix a bug that caused metadata starting with something resembling a drive
letter to be incorrectly split into an extra directory after the colon.
:bug:`3685`
* :doc:`/plugins/mpdstats`: Don't record a skip when stopping MPD, as MPD keeps
the current track in the queue.
Thanks to :user:`aereaux`.
:bug:`3722`
* String-typed fields are now normalized to string values, avoiding an
occasional crash when using both the :doc:`/plugins/fetchart` and the
:doc:`/plugins/discogs` together.
:bug:`3773` :bug:`3774`
* Fix a bug causing PIL to generate poor quality JPEGs when resizing artwork.
:bug:`3743`
* :doc:`plugins/keyfinder`: Catch output from ``keyfinder-cli`` that is missing key.
:bug:`2242`
* :doc:`plugins/replaygain`: Disable parallel analysis on import by default.
:bug:`3819`
* :doc:`/plugins/mpdstats`: Fix Python 2/3 compatibility
:bug:`3798`
* :doc:`/plugins/discogs`: Replace the deprecated official `discogs-client`
library with the community supported `python3-discogs-client`_ library.
:bug:`3608`
* :doc:`/plugins/chroma`: Fixed submitting AcoustID information for tracks
that already have a fingerprint.
:bug:`3834`
* Allow equals within the value part of the ``--set`` option to the ``beet
import`` command.
:bug:`2984`
* Duplicates can now generate checksums. Thanks :user:`wisp3rwind`
for the pointer to how to solve. Thanks to :user:`arogl`.
:bug:`2873`
* Templates that use ``%ifdef`` now produce the expected behavior when used in
conjunction with non-string fields from the :doc:`/plugins/types`.
:bug:`3852`
* :doc:`/plugins/lyrics`: Fix crashes when a website could not be retrieved,
affecting at least the Genius source.
:bug:`3970`
* :doc:`/plugins/duplicates`: Fix a crash when running the ``dup`` command with
a query that returns no results.
:bug:`3943`
* :doc:`/plugins/beatport`: Fix the default assignment of the musical key.
:bug:`3377`
* :doc:`/plugins/lyrics`: Improved searching on the Genius backend when the
artist contains special characters.
:bug:`3634`
* :doc:`/plugins/parentwork`: Also get the composition date of the parent work,
instead of just the child work.
Thanks to :user:`aereaux`.
:bug:`3650`
* :doc:`/plugins/lyrics`: Fix a bug in the heuristic for detecting valid
lyrics in the Google source.
:bug:`2969`
* :doc:`/plugins/thumbnails`: Fix a crash due to an incorrect string type on
Python 3.
:bug:`3360`
* :doc:`/plugins/fetchart`: The Cover Art Archive source now iterates over
all front images instead of blindly selecting the first one.
* :doc:`/plugins/lyrics`: Removed the LyricWiki source (the site shut down on
21/09/2020).
* :doc:`/plugins/subsonicupdate`: The plugin is now functional again. A new
`auth` configuration option is required in the configuration to specify the
flavor of authentication to use.
:bug:`4002`

For plugin developers:

* `MediaFile`_ has been split into a standalone project. Where you used to do
``from beets import mediafile``, now just do ``import mediafile``. Beets
re-exports MediaFile at the old location for backwards-compatibility, but a
deprecation warning is raised if you do this since we might drop this wrapper
in a future release.
* Similarly, we've replaced beets' configuration library (previously called
Confit) with a standalone version called `Confuse`_. Where you used to do
``from beets.util import confit``, now just do ``import confuse``. The code
is almost identical apart from the name change. Again, we'll re-export at the
old location (with a deprecation warning) for backwards compatibility, but
we might stop doing this in a future release.
* ``beets.util.command_output`` now returns a named tuple containing both the
standard output and the standard error data instead of just stdout alone.
Client code will need to access the ``stdout`` attribute on the return
value.
Thanks to :user:`zsinskri`.
:bug:`3329`
* There were sporadic failures in ``test.test_player``. Hopefully these are
fixed. If they resurface, please reopen the relevant issue.
:bug:`3309` :bug:`3330`
* The ``beets.plugins.MetadataSourcePlugin`` base class has been added to
simplify development of plugins which query album, track, and search
APIs to provide metadata matches for the importer. Refer to the
:doc:`/plugins/spotify` and the :doc:`/plugins/deezer` for examples of using
this template class.
:bug:`3355`
* Accessing fields on an `Item` now falls back to the album's
attributes. So, for example, ``item.foo`` will first look for a field `foo` on
`item` and, if it doesn't exist, next tries looking for a field named `foo`
on the album that contains `item`. If you specifically want to access an
item's attributes, use ``Item.get(key, with_album=False)``. :bug:`2988`
* ``Item.keys`` also has a ``with_album`` argument now, defaulting to ``True``.
* A ``revision`` attribute has been added to ``Database``. It is increased on
every transaction that mutates it. :bug:`2988`
* The classes ``AlbumInfo`` and ``TrackInfo`` now convey arbitrary attributes
instead of a fixed, built-in set of field names (which was important to
address :bug:`1547`).
Thanks to :user:`dosoe`.
* Two new events, ``mb_album_extract`` and ``mb_track_extract``, let plugins
add new fields based on MusicBrainz data. Thanks to :user:`dosoe`.

For packagers:

* Beets' library for manipulating media file metadata has now been split to a
standalone project called `MediaFile`_, released as :pypi:`mediafile`. Beets
now depends on this new package. Beets now depends on Mutagen transitively
through MediaFile rather than directly, except in the case of one of beets'
plugins (in particular, the :doc:`/plugins/scrub`).
* Beets' library for configuration has been split into a standalone project
called `Confuse`_, released as :pypi:`confuse`. Beets now depends on this
package. Confuse has existed separately for some time and is used by
unrelated projects, but until now we've been bundling a copy within beets.
* We attempted to fix an unreliable test, so a patch to `skip <https://sources.debian.org/src/beets/1.4.7-2/debian/patches/skip-broken-test/>`_
or `repair <https://build.opensuse.org/package/view_file/openSUSE:Factory/beets/fix_test_command_line_option_relative_to_working_dir.diff?expand=1>`_
the test may no longer be necessary.
* This version drops support for Python 3.4.
* We have removed an optional dependency on bs1770gain.

.. _Fish shell: https://fishshell.com/
.. _MediaFile: https://github.com/beetbox/mediafile
.. _Confuse: https://github.com/beetbox/confuse
.. _works: https://musicbrainz.org/doc/Work
.. _Deezer: https://www.deezer.com
.. _keyfinder-cli: https://github.com/EvanPurkhiser/keyfinder-cli
.. _last.fm: https://last.fm
.. _python3-discogs-client: https://github.com/joalla/discogs_client
.. _py7zr: https://pypi.org/project/py7zr/

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

This small update is part of our attempt to release new versions more often!
There are a few important fixes, and we're clearing the deck for a change to
beets' dependencies in the next version.

The new feature is:

* You can use the `NO_COLOR`_ environment variable to disable terminal colors.
:bug:`3273`

There are some fixes in this release:

* Fix a regression in the last release that made the image resizer fail to
detect older versions of ImageMagick.
:bug:`3269`
* :doc:`/plugins/gmusic`: The ``oauth_file`` config option now supports more
flexible path values, including ``~`` for the home directory.
:bug:`3270`
* :doc:`/plugins/gmusic`: Fix a crash when using version 12.0.0 or later of
the ``gmusicapi`` module.
:bug:`3270`
* Fix an incompatibility with Python 3.8's AST changes.
:bug:`3278`

Here's a note for packagers:

* ``pathlib`` is now an optional test dependency on Python 3.4+, removing the
need for `a Debian patch <https://sources.debian.org/src/beets/1.4.7-2/debian/patches/pathlib-is-stdlib/>`_.
:bug:`3275`

.. _NO_COLOR: https://no-color.org

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

This release is far too long in coming, but it's a good one. There is the
usual torrent of new features and a ridiculously long line of fixes, but there
are also some crucial maintenance changes.
We officially support Python 3.7 and 3.8, and some performance optimizations
can (anecdotally) make listing your library more than three times faster than
in the previous version.

The new core features are:

* A new :ref:`config-aunique` configuration option allows setting default
options for the :ref:`aunique` template function.
* The ``albumdisambig`` field no longer includes the MusicBrainz release group
disambiguation comment. A new ``releasegroupdisambig`` field has been added.
:bug:`3024`
* The :ref:`modify-cmd` command now allows resetting fixed attributes. For
example, ``beet modify -a artist:beatles artpath!`` resets ``artpath``
attribute from matching albums back to the default value.
:bug:`2497`
* A new importer option, :ref:`ignore_data_tracks`, lets you skip audio tracks
contained in data files. :bug:`3021`

There are some new plugins:

* The :doc:`/plugins/playlist` can query the beets library using M3U playlists.
Thanks to :user:`Holzhaus` and :user:`Xenopathic`.
:bug:`123` :bug:`3145`
* The :doc:`/plugins/loadext` allows loading of SQLite extensions, primarily
for use with the ICU SQLite extension for internationalization.
:bug:`3160` :bug:`3226`
* The :doc:`/plugins/subsonicupdate` can automatically update your Subsonic
library.
Thanks to :user:`maffo999`.
:bug:`3001`

And many improvements to existing plugins:

* :doc:`/plugins/lastgenre`: Added option ``-A`` to match individual tracks
and singletons.
:bug:`3220` :bug:`3219`
* :doc:`/plugins/play`: The plugin can now emit a UTF-8 BOM, fixing some
issues with foobar2000 and Winamp.
Thanks to :user:`mz2212`.
:bug:`2944`
* :doc:`/plugins/gmusic`:
* Add a new option to automatically upload to Google Play Music library on
track import.
Thanks to :user:`shuaiscott`.
* Add new options for Google Play Music authentication.
Thanks to :user:`thetarkus`.
:bug:`3002`
* :doc:`/plugins/replaygain`: ``albumpeak`` on large collections is calculated
as the average, not the maximum.
:bug:`3008` :bug:`3009`
* :doc:`/plugins/chroma`:
* Now optionally has a bias toward looking up more relevant releases
according to the :ref:`preferred` configuration options.
Thanks to :user:`archer4499`.
:bug:`3017`
* Fingerprint values are now properly stored as strings, which prevents
strange repeated output when running ``beet write``.
Thanks to :user:`Holzhaus`.
:bug:`3097` :bug:`2942`
* :doc:`/plugins/convert`: The plugin now has an ``id3v23`` option that allows
you to override the global ``id3v23`` option.
Thanks to :user:`Holzhaus`.
:bug:`3104`
* :doc:`/plugins/spotify`:
* The plugin now uses OAuth for authentication to the Spotify API.
Thanks to :user:`rhlahuja`.
:bug:`2694` :bug:`3123`
* The plugin now works as an import metadata
provider: you can match tracks and albums using the Spotify database.
Thanks to :user:`rhlahuja`.
:bug:`3123`
* :doc:`/plugins/ipfs`: The plugin now supports a ``nocopy`` option which
passes that flag to ipfs.
Thanks to :user:`wildthyme`.
* :doc:`/plugins/discogs`: The plugin now has rate limiting for the Discogs API.
:bug:`3081`
* :doc:`/plugins/mpdstats`, :doc:`/plugins/mpdupdate`: These plugins now use
the ``MPD_PORT`` environment variable if no port is specified in the
configuration file.
:bug:`3223`
* :doc:`/plugins/bpd`:
* MPD protocol commands ``consume`` and ``single`` are now supported along
with updated semantics for ``repeat`` and ``previous`` and new fields for
``status``. The bpd server now understands and ignores some additional
commands.
:bug:`3200` :bug:`800`
* MPD protocol command ``idle`` is now supported, allowing the MPD version
to be bumped to 0.14.
:bug:`3205` :bug:`800`
* MPD protocol command ``decoders`` is now supported.
:bug:`3222`
* The plugin now uses the main beets logging system.
The special-purpose ``--debug`` flag has been removed.
Thanks to :user:`arcresu`.
:bug:`3196`
* :doc:`/plugins/mbsync`: The plugin no longer queries MusicBrainz when either
the ``mb_albumid`` or ``mb_trackid`` field is invalid.
See also the discussion on `Google Groups`_
Thanks to :user:`arogl`.
* :doc:`/plugins/export`: The plugin now also exports ``path`` field if the user
explicitly specifies it with ``-i`` parameter. This only works when exporting
library fields.
:bug:`3084`
* :doc:`/plugins/acousticbrainz`: The plugin now declares types for all its
fields, which enables easier querying and avoids a problem where very small
numbers would be stored as strings.
Thanks to :user:`rain0r`.
:bug:`2790` :bug:`3238`

.. _Google Groups: https://groups.google.com/forum/#!searchin/beets-users/mbsync|sort:date/beets-users/iwCF6bNdh9A/i1xl4Gx8BQAJ

Some improvements have been focused on improving beets' performance:

* Querying the library is now faster:
* We only convert fields that need to be displayed.
Thanks to :user:`pprkut`.
:bug:`3089`
* We now compile templates once and reuse them instead of recompiling them
to print out each matching object.
Thanks to :user:`SimonPersson`.
:bug:`3258`
* Querying the library for items is now faster, for all queries that do not
need to access album level properties. This was implemented by lazily
fetching the album only when needed.
Thanks to :user:`SimonPersson`.
:bug:`3260`
* :doc:`/plugins/absubmit`, :doc:`/plugins/badfiles`: Analysis now works in
parallel (on Python 3 only).
Thanks to :user:`bemeurer`.
:bug:`2442` :bug:`3003`
* :doc:`/plugins/mpdstats`: Use the ``currentsong`` MPD command instead of
``playlist`` to get the current song, improving performance when the playlist
is long.
Thanks to :user:`ray66`.
:bug:`3207` :bug:`2752`

Several improvements are related to usability:

* The disambiguation string for identifying albums in the importer now shows
the catalog number.
Thanks to :user:`8h2a`.
:bug:`2951`
* Added whitespace padding to missing tracks dialog to improve readability.
Thanks to :user:`jams2`.
:bug:`2962`
* The :ref:`move-cmd` command now lists the number of items already in-place.
Thanks to :user:`RollingStar`.
:bug:`3117`
* Modify selection can now be applied early without selecting every item.
:bug:`3083`
* Beets now emits more useful messages during startup if SQLite returns an error. The
SQLite error message is now attached to the beets message.
:bug:`3005`
* Fixed a confusing typo when the :doc:`/plugins/convert` plugin copies the art
covers.
:bug:`3063`

Many fixes have been focused on issues where beets would previously crash:

* Avoid a crash when archive extraction fails during import.
:bug:`3041`
* Missing album art file during an update no longer causes a fatal exception
(instead, an error is logged and the missing file path is removed from the
library).
:bug:`3030`
* When updating the database, beets no longer tries to move album art twice.
:bug:`3189`
* Fix an unhandled exception when pruning empty directories.
:bug:`1996` :bug:`3209`
* :doc:`/plugins/fetchart`: Added network connection error handling to backends
so that beets won't crash if a request fails.
Thanks to :user:`Holzhaus`.
:bug:`1579`
* :doc:`/plugins/badfiles`: Avoid a crash when the underlying tool emits
undecodable output.
:bug:`3165`
* :doc:`/plugins/beatport`: Avoid a crash when the server produces an error.
:bug:`3184`
* :doc:`/plugins/bpd`: Fix crashes in the bpd server during exception handling.
:bug:`3200`
* :doc:`/plugins/bpd`: Fix a crash triggered when certain clients tried to list
the albums belonging to a particular artist.
:bug:`3007` :bug:`3215`
* :doc:`/plugins/replaygain`: Avoid a crash when the ``bs1770gain`` tool emits
malformed XML.
:bug:`2983` :bug:`3247`

There are many fixes related to compatibility with our dependencies including
addressing changes interfaces:

* On Python 2, pin the :pypi:`jellyfish` requirement to version 0.6.0 for
compatibility.
* Fix compatibility with Python 3.7 and its change to a name in the
:stdlib:`re` module.
:bug:`2978`
* Fix several uses of deprecated standard-library features on Python 3.7.
Thanks to :user:`arcresu`.
:bug:`3197`
* Fix compatibility with pre-release versions of Python 3.8.
:bug:`3201` :bug:`3202`
* :doc:`/plugins/web`: Fix an error when using more recent versions of Flask
with CORS enabled.
Thanks to :user:`rveachkc`.
:bug:`2979`: :bug:`2980`
* Avoid some deprecation warnings with certain versions of the MusicBrainz
library.
Thanks to :user:`zhelezov`.
:bug:`2826` :bug:`3092`
* Restore iTunes Store album art source, and remove the dependency on
:pypi:`python-itunes`, which had gone unmaintained and was not
Python-3-compatible.
Thanks to :user:`ocelma` for creating :pypi:`python-itunes` in the first place.
Thanks to :user:`nathdwek`.
:bug:`2371` :bug:`2551` :bug:`2718`
* :doc:`/plugins/lastgenre`, :doc:`/plugins/edit`: Avoid a deprecation warnings
from the :pypi:`PyYAML` library by switching to the safe loader.
Thanks to :user:`translit` and :user:`sbraz`.
:bug:`3192` :bug:`3225`
* Fix a problem when resizing images with :pypi:`PIL`/:pypi:`pillow` on Python 3.
Thanks to :user:`architek`.
:bug:`2504` :bug:`3029`

And there are many other fixes:

* R128 normalization tags are now properly deleted from files when the values
are missing.
Thanks to :user:`autrimpo`.
:bug:`2757`
* Display the artist credit when matching albums if the :ref:`artist_credit`
configuration option is set.
:bug:`2953`
* With the :ref:`from_scratch` configuration option set, only writable fields
are cleared. Beets now no longer ignores the format your music is saved in.
:bug:`2972`
* The ``%aunique`` template function now works correctly with the
``-f/--format`` option.
:bug:`3043`
* Fixed the ordering of items when manually selecting changes while updating
tags
Thanks to :user:`TaizoSimpson`.
:bug:`3501`
* The ``%title`` template function now works correctly with apostrophes.
Thanks to :user:`GuilhermeHideki`.
:bug:`3033`
* :doc:`/plugins/lastgenre`: It's now possible to set the ``prefer_specific``
option without also setting ``canonical``.
:bug:`2973`
* :doc:`/plugins/fetchart`: The plugin now respects the ``ignore`` and
``ignore_hidden`` settings.
:bug:`1632`
* :doc:`/plugins/hook`: Fix byte string interpolation in hook commands.
:bug:`2967` :bug:`3167`
* :doc:`/plugins/the`: Log a message when something has changed, not when it
hasn't.
Thanks to :user:`arcresu`.
:bug:`3195`
* :doc:`/plugins/lastgenre`: The ``force`` config option now actually works.
:bug:`2704` :bug:`3054`
* Resizing image files with ImageMagick now avoids problems on systems where
there is a ``convert`` command that is *not* ImageMagick's by using the
``magick`` executable when it is available.
Thanks to :user:`ababyduck`.
:bug:`2093` :bug:`3236`

There is one new thing for plugin developers to know about:

* In addition to prefix-based field queries, plugins can now define *named
queries* that are not associated with any specific field.
For example, the new :doc:`/plugins/playlist` supports queries like
``playlist:name`` although there is no field named ``playlist``.
See :ref:`extend-query` for details.

And some messages for packagers:

* Note the changes to the dependencies on :pypi:`jellyfish` and :pypi:`munkres`.
* The optional :pypi:`python-itunes` dependency has been removed.
* Python versions 3.7 and 3.8 are now supported.

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

This new release includes lots of new features in the importer and the
metadata source backends that it uses.
We've changed how the beets importer handles non-audio tracks listed in
metadata sources like MusicBrainz:

* The importer now ignores non-audio tracks (namely, data and video tracks)
listed in MusicBrainz. Also, a new option, :ref:`ignore_video_tracks`, lets
you return to the old behavior and include these video tracks.
:bug:`1210`
* A new importer option, :ref:`ignored_media`, can let you skip certain media
formats.
:bug:`2688`


There are other subtle improvements to metadata handling in the importer:

* In the MusicBrainz backend, beets now imports the
``musicbrainz_releasetrackid`` field. This is a first step toward
:bug:`406`.
Thanks to :user:`Rawrmonkeys`.
* A new importer configuration option, :ref:`artist_credit`, will tell beets
to prefer the artist credit over the artist when autotagging.
:bug:`1249`


And there are even more new features:

* :doc:`/plugins/replaygain`: The ``beet replaygain`` command now has
``--force``, ``--write`` and ``--nowrite`` options. :bug:`2778`
* A new importer configuration option, :ref:`incremental_skip_later`, lets you
avoid recording skipped directories to the list of "processed" directories
in :ref:`incremental` mode. This way, you can revisit them later with
another import.
Thanks to :user:`sekjun9878`.
:bug:`2773`
* :doc:`/plugins/fetchart`: The configuration options now support
finer-grained control via the ``sources`` option. You can now specify the
search order for different *matching strategies* within different backends.
* :doc:`/plugins/web`: A new ``cors_supports_credentials`` configuration
option lets in-browser clients communicate with the server even when it is
protected by an authorization mechanism (a proxy with HTTP authentication
enabled, for example).
* A new :doc:`/plugins/sonosupdate` plugin automatically notifies Sonos
controllers to update the music library when the beets library changes.
Thanks to :user:`cgtobi`.
* :doc:`/plugins/discogs`: The plugin now stores master release IDs into
``mb_releasegroupid``. It also "simulates" track IDs using the release ID
and the track list position.
Thanks to :user:`dbogdanov`.
:bug:`2336`
* :doc:`/plugins/discogs`: Fetch the original year from master releases.
:bug:`1122`


There are lots and lots of fixes:

* :doc:`/plugins/replaygain`: Fix a corner-case with the ``bs1770gain`` backend
where ReplayGain values were assigned to the wrong files. The plugin now
requires version 0.4.6 or later of the ``bs1770gain`` tool.
:bug:`2777`
* :doc:`/plugins/lyrics`: The plugin no longer crashes in the Genius source
when BeautifulSoup is not found. Instead, it just logs a message and
disables the source.
:bug:`2911`
* :doc:`/plugins/lyrics`: Handle network and API errors when communicating
with Genius. :bug:`2771`
* :doc:`/plugins/lyrics`: The ``lyrics`` command previously wrote ReST files
by default, even when you didn't ask for them. This default has been fixed.
* :doc:`/plugins/lyrics`: When writing ReST files, the ``lyrics`` command
now groups lyrics by the ``albumartist`` field, rather than ``artist``.
:bug:`2924`
* Plugins can now see updated import task state, such as when rejecting the
initial candidates and finding new ones via a manual search. Notably, this
means that the importer prompt options that the :doc:`/plugins/edit`
provides show up more reliably after doing a secondary import search.
:bug:`2441` :bug:`2731`
* :doc:`/plugins/importadded`: Fix a crash on non-autotagged imports.
Thanks to :user:`m42i`.
:bug:`2601` :bug:`1918`
* :doc:`/plugins/plexupdate`: The Plex token is now redacted in configuration
output.
Thanks to :user:`Kovrinic`.
:bug:`2804`
* Avoid a crash when importing a non-ASCII filename when using an ASCII locale
on Unix under Python 3.
:bug:`2793` :bug:`2803`
* Fix a problem caused by time zone misalignment that could make date queries
fail to match certain dates that are near the edges of a range. For example,
querying for dates within a certain month would fail to match dates within
hours of the end of that month.
:bug:`2652`
* :doc:`/plugins/convert`: The plugin now runs before other plugin-provided
import stages, which addresses an issue with generating ReplayGain data
incompatible between the source and target file formats.
Thanks to :user:`autrimpo`.
:bug:`2814`
* :doc:`/plugins/ftintitle`: The ``drop`` config option had no effect; it now
does what it says it should do.
:bug:`2817`
* Importing a release with multiple release events now selects the
event based on the order of your :ref:`preferred` countries rather than
the order of release events in MusicBrainz. :bug:`2816`
* :doc:`/plugins/web`: The time display in the web interface would incorrectly jump
at the 30-second mark of every minute. Now, it correctly changes over at zero
seconds. :bug:`2822`
* :doc:`/plugins/web`: Fetching album art now works (instead of throwing an
exception) under Python 3.
Additionally, the server will now return a 404 response when the album ID
is unknown (instead of throwing an exception and producing a 500 response).
:bug:`2823`
* :doc:`/plugins/web`: Fix an exception on Python 3 for filenames with
non-Latin1 characters. (These characters are now converted to their ASCII
equivalents.)
:bug:`2815`
* Partially fix bash completion for subcommand names that contain hyphens.
Thanks to :user:`jhermann`.
:bug:`2836` :bug:`2837`
* :doc:`/plugins/replaygain`: Really fix album gain calculation using the
GStreamer backend. :bug:`2846`
* Avoid an error when doing a "no-op" move on non-existent files (i.e., moving
a file onto itself). :bug:`2863`
* :doc:`/plugins/discogs`: Fix the ``medium`` and ``medium_index`` values, which
were occasionally incorrect for releases with two-sided mediums such as
vinyl. Also fix the ``medium_total`` value, which now contains total number
of tracks on the medium to which a track belongs, not the total number of
different mediums present on the release.
Thanks to :user:`dbogdanov`.
:bug:`2887`
* The importer now supports audio files contained in data tracks when they are
listed in MusicBrainz: the corresponding audio tracks are now merged into the
main track list. Thanks to :user:`jdetrey`. :bug:`1638`
* :doc:`/plugins/keyfinder`: Avoid a crash when trying to process unmatched
tracks. :bug:`2537`
* :doc:`/plugins/mbsync`: Support MusicBrainz recording ID changes, relying
on release track IDs instead. Thanks to :user:`jdetrey`. :bug:`1234`
* :doc:`/plugins/mbsync`: We can now successfully update albums even when the
first track has a missing MusicBrainz recording ID. :bug:`2920`


There are a couple of changes for developers:

* Plugins can now run their import stages *early*, before other plugins. Use
the ``early_import_stages`` list instead of plain ``import_stages`` to
request this behavior.
:bug:`2814`
* We again properly send ``albuminfo_received`` and ``trackinfo_received`` in
all cases, most notably when using the ``mbsync`` plugin. This was a
regression since version 1.4.1.
:bug:`2921`