Beets

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

The highlight of this release is "album merging," an oft-requested option in
the importer to add new tracks to an existing album you already have in your
library. This way, you no longer need to resort to removing the partial album
from your library, combining the files manually, and importing again.

Here are the larger new features in this release:

* When the importer finds duplicate albums, you can now merge all the
tracks---old and new---together and try importing them as a single, combined
album.
Thanks to :user:`udiboy1209`.
:bug:`112` :bug:`2725`
* :doc:`/plugins/lyrics`: The plugin can now produce reStructuredText files
for beautiful, readable books of lyrics. Thanks to :user:`anarcat`.
:bug:`2628`
* A new :ref:`from_scratch` configuration option makes the importer remove old
metadata before applying new metadata. This new feature complements the
:doc:`zero </plugins/zero>` and :doc:`scrub </plugins/scrub>` plugins but is
slightly different: beets clears out all the old tags it knows about and
only keeps the new data it gets from the remote metadata source.
Thanks to :user:`tummychow`.
:bug:`934` :bug:`2755`

There are also somewhat littler, but still great, new features:

* :doc:`/plugins/convert`: A new ``no_convert`` option lets you skip
transcoding items matching a query. Instead, the files are just copied
as-is. Thanks to :user:`Stunner`.
:bug:`2732` :bug:`2751`
* :doc:`/plugins/fetchart`: A new quiet switch that only prints out messages
when album art is missing.
Thanks to :user:`euri10`.
:bug:`2683`
* :doc:`/plugins/mbcollection`: You can configure a custom MusicBrainz
collection via the new ``collection`` configuration option.
:bug:`2685`
* :doc:`/plugins/mbcollection`: The collection update command can now remove
albums from collections that are longer in the beets library.
* :doc:`/plugins/fetchart`: The ``clearart`` command now asks for confirmation
before touching your files.
Thanks to :user:`konman2`.
:bug:`2708` :bug:`2427`
* :doc:`/plugins/mpdstats`: The plugin now correctly updates song statistics
when MPD switches from a song to a stream and when it plays the same song
multiple times consecutively.
:bug:`2707`
* :doc:`/plugins/acousticbrainz`: The plugin can now be configured to write only
a specific list of tags.
Thanks to :user:`woparry`.

There are lots and lots of bug fixes:

* :doc:`/plugins/hook`: Fixed a problem where accessing non-string properties
of ``item`` or ``album`` (e.g., ``item.track``) would cause a crash.
Thanks to :user:`broddo`.
:bug:`2740`
* :doc:`/plugins/play`: When ``relative_to`` is set, the plugin correctly
emits relative paths even when querying for albums rather than tracks.
Thanks to :user:`j000`.
:bug:`2702`
* We suppress a spurious Python warning about a ``BrokenPipeError`` being
ignored. This was an issue when using beets in simple shell scripts.
Thanks to :user:`Azphreal`.
:bug:`2622` :bug:`2631`
* :doc:`/plugins/replaygain`: Fix a regression in the previous release related
to the new R128 tags. :bug:`2615` :bug:`2623`
* :doc:`/plugins/lyrics`: The MusixMatch backend now detects and warns
when the server has blocked the client.
Thanks to :user:`anarcat`. :bug:`2634` :bug:`2632`
* :doc:`/plugins/importfeeds`: Fix an error on Python 3 in certain
configurations. Thanks to :user:`djl`. :bug:`2467` :bug:`2658`
* :doc:`/plugins/edit`: Fix a bug when editing items during a re-import with
the ``-L`` flag. Previously, diffs against against unrelated items could be
shown or beets could crash. :bug:`2659`
* :doc:`/plugins/kodiupdate`: Fix the server URL and add better error
reporting.
:bug:`2662`
* Fixed a problem where "no-op" modifications would reset files' mtimes,
resulting in unnecessary writes. This most prominently affected the
:doc:`/plugins/edit` when saving the text file without making changes to some
music. :bug:`2667`
* :doc:`/plugins/chroma`: Fix a crash when running the ``submit`` command on
Python 3 on Windows with non-ASCII filenames. :bug:`2671`
* :doc:`/plugins/absubmit`: Fix an occasional crash on Python 3 when the AB
analysis tool produced non-ASCII metadata. :bug:`2673`
* :doc:`/plugins/duplicates`: Use the default tiebreak for items or albums
when the configuration only specifies a tiebreak for the other kind of
entity.
Thanks to :user:`cgevans`.
:bug:`2758`
* :doc:`/plugins/duplicates`: Fix the ``--key`` command line option, which was
ignored.
* :doc:`/plugins/replaygain`: Fix album ReplayGain calculation with the
GStreamer backend. :bug:`2636`
* :doc:`/plugins/scrub`: Handle errors when manipulating files using newer
versions of Mutagen. :bug:`2716`
* :doc:`/plugins/fetchart`: The plugin no longer gets skipped during import
when the "Edit Candidates" option is used from the :doc:`/plugins/edit`.
:bug:`2734`
* Fix a crash when numeric metadata fields contain just a minus or plus sign
with no following numbers. Thanks to :user:`eigengrau`. :bug:`2741`
* :doc:`/plugins/fromfilename`: Recognize file names that contain *only* a
track number, such as `01.mp3`. Also, the plugin now allows underscores as a
separator between fields.
Thanks to :user:`Vrihub`.
:bug:`2738` :bug:`2759`
* Fixed an issue where images would be resized according to their longest
edge, instead of their width, when using the ``maxwidth`` config option in
the :doc:`/plugins/fetchart` and :doc:`/plugins/embedart`. Thanks to
:user:`sekjun9878`. :bug:`2729`

There are some changes for developers:

* "Fixed fields" in Album and Item objects are now more strict about translating
missing values into type-specific null-like values. This should help in
cases where a string field is unexpectedly `None` sometimes instead of just
showing up as an empty string. :bug:`2605`
* Refactored the move functions the `beets.library` module and the
`manipulate_files` function in `beets.importer` to use a single parameter
describing the file operation instead of multiple Boolean flags.
There is a new numerated type describing how to move, copy, or link files.
:bug:`2682`

you can now manually set fields on the new music. Date queries have gotten
much more powerful: you can write precise queries down to the second, and we
now have *relative* queries like ``-1w``, which means *one week ago*.

Here are the new features:

* You can now set fields to certain values during :ref:`import-cmd`, using
either a ``--set field=value`` command-line flag or a new :ref:`set_fields`
configuration option under the `importer` section.
Thanks to :user:`bartkl`. :bug:`1881` :bug:`2581`
* :ref:`Date queries <datequery>` can now include times, so you can filter
your music down to the second. Thanks to :user:`discopatrick`. :bug:`2506`
:bug:`2528`
* :ref:`Date queries <datequery>` can also be *relative*. You can say
``added:-1w..`` to match music added in the last week, for example. Thanks
to :user:`euri10`. :bug:`2598`
* A new :doc:`/plugins/gmusic` lets you interact with your Google Play Music
library. Thanks to :user:`tigranl`. :bug:`2553` :bug:`2586`
* :doc:`/plugins/replaygain`: We now keep R128 data in separate tags from
classic ReplayGain data for formats that need it (namely, Ogg Opus). A new
`r128` configuration option enables this behavior for specific formats.
Thanks to :user:`autrimpo`. :bug:`2557` :bug:`2560`
* The :ref:`move-cmd` command gained a new ``--export`` flag, which copies
files to an external location without changing their paths in the library
database. Thanks to :user:`SpirosChadoulos`. :bug:`435` :bug:`2510`

There are also some bug fixes:

* :doc:`/plugins/lastgenre`: Fix a crash when using the `prefer_specific` and
`canonical` options together. Thanks to :user:`yacoob`. :bug:`2459`
:bug:`2583`
* :doc:`/plugins/web`: Fix a crash on Windows under Python 2 when serving
non-ASCII filenames. Thanks to :user:`robot3498712`. :bug:`2592` :bug:`2593`
* :doc:`/plugins/metasync`: Fix a crash in the Amarok backend when filenames
contain quotes. Thanks to :user:`aranc23`. :bug:`2595` :bug:`2596`
* More informative error messages are displayed when the file format is not
recognized. :bug:`2599`

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

This release built up a longer-than-normal list of nifty new features. We now
support DSF audio files and the importer can hard-link your files, for
example.

Here's a full list of new features:

* Added support for DSF files, once a future version of Mutagen is released
that supports them. Thanks to :user:`docbobo`. :bug:`459` :bug:`2379`
* A new :ref:`hardlink` config option instructs the importer to create hard
links on filesystems that support them. Thanks to :user:`jacobwgillespie`.
:bug:`2445`
* A new :doc:`/plugins/kodiupdate` lets you keep your Kodi library in sync
with beets. Thanks to :user:`Pauligrinder`. :bug:`2411`
* A new :ref:`bell` configuration option under the ``import`` section enables
a terminal bell when input is required. Thanks to :user:`SpirosChadoulos`.
:bug:`2366` :bug:`2495`
* A new field, ``composer_sort``, is now supported and fetched from
MusicBrainz.
Thanks to :user:`dosoe`.
:bug:`2519` :bug:`2529`
* The MusicBrainz backend and :doc:`/plugins/discogs` now both provide a new
attribute called ``track_alt`` that stores more nuanced, possibly
non-numeric track index data. For example, some vinyl or tape media will
report the side of the record using a letter instead of a number in that
field. :bug:`1831` :bug:`2363`
* :doc:`/plugins/web`: Added a new endpoint, ``/item/path/foo``, which will
return the item info for the file at the given path, or 404.
* :doc:`/plugins/web`: Added a new config option, ``include_paths``,
which will cause paths to be included in item API responses if set to true.
* The ``%aunique`` template function for :ref:`aunique` now takes a third
argument that specifies which brackets to use around the disambiguator
value. The argument can be any two characters that represent the left and
right brackets. It defaults to `[]` and can also be blank to turn off
bracketing. :bug:`2397` :bug:`2399`
* Added a ``--move`` or ``-m`` option to the importer so that the files can be
moved to the library instead of being copied or added "in place."
:bug:`2252` :bug:`2429`
* :doc:`/plugins/badfiles`: Added a ``--verbose`` or ``-v`` option. Results are
now displayed only for corrupted files by default and for all the files when
the verbose option is set. :bug:`1654` :bug:`2434`
* :doc:`/plugins/embedart`: The explicit ``embedart`` command now asks for
confirmation before embedding art into music files. Thanks to
:user:`Stunner`. :bug:`1999`
* You can now run beets by typing `python -m beets`. :bug:`2453`
* :doc:`/plugins/smartplaylist`: Different playlist specifications that
generate identically-named playlist files no longer conflict; instead, the
resulting lists of tracks are concatenated. :bug:`2468`
* :doc:`/plugins/missing`: A new mode lets you see missing albums from artists
you have in your library. Thanks to :user:`qlyoung`. :bug:`2481`
* :doc:`/plugins/web` : Add new `reverse_proxy` config option to allow serving
the web plugins under a reverse proxy.
* Importing a release with multiple release events now selects the
event based on your :ref:`preferred` countries. :bug:`2501`
* :doc:`/plugins/play`: A new ``-y`` or ``--yes`` parameter lets you skip
the warning message if you enqueue more items than the warning threshold
usually allows.
* Fix a bug where commands which forked subprocesses would sometimes prevent
further inputs. This bug mainly affected :doc:`/plugins/convert`.
Thanks to :user:`jansol`.
:bug:`2488`
:bug:`2524`

There are also quite a few fixes:

* In the :ref:`replace` configuration option, we now replace a leading hyphen
(-) with an underscore. :bug:`549` :bug:`2509`
* :doc:`/plugins/absubmit`: We no longer filter audio files for specific
formats---we will attempt the submission process for all formats. :bug:`2471`
* :doc:`/plugins/mpdupdate`: Fix Python 3 compatibility. :bug:`2381`
* :doc:`/plugins/replaygain`: Fix Python 3 compatibility in the ``bs1770gain``
backend. :bug:`2382`
* :doc:`/plugins/bpd`: Report playback times as integers. :bug:`2394`
* :doc:`/plugins/mpdstats`: Fix Python 3 compatibility. The plugin also now
requires version 0.4.2 or later of the ``python-mpd2`` library. :bug:`2405`
* :doc:`/plugins/mpdstats`: Improve handling of MPD status queries.
* :doc:`/plugins/badfiles`: Fix Python 3 compatibility.
* Fix some cases where album-level ReplayGain/SoundCheck metadata would be
written to files incorrectly. :bug:`2426`
* :doc:`/plugins/badfiles`: The command no longer bails out if the validator
command is not found or exits with an error. :bug:`2430` :bug:`2433`
* :doc:`/plugins/lyrics`: The Google search backend no longer crashes when the
server responds with an error. :bug:`2437`
* :doc:`/plugins/discogs`: You can now authenticate with Discogs using a
personal access token. :bug:`2447`
* Fix Python 3 compatibility when extracting rar archives in the importer.
Thanks to :user:`Lompik`. :bug:`2443` :bug:`2448`
* :doc:`/plugins/duplicates`: Fix Python 3 compatibility when using the
``copy`` and ``move`` options. :bug:`2444`
* :doc:`/plugins/mbsubmit`: The tracks are now sorted properly. Thanks to
:user:`awesomer`. :bug:`2457`
* :doc:`/plugins/thumbnails`: Fix a string-related crash on Python 3.
:bug:`2466`
* :doc:`/plugins/beatport`: More than just 10 songs are now fetched per album.
:bug:`2469`
* On Python 3, the :ref:`terminal_encoding` setting is respected again for
output and printing will no longer crash on systems configured with a
limited encoding.
* :doc:`/plugins/convert`: The default configuration uses FFmpeg's built-in
AAC codec instead of faac. Thanks to :user:`jansol`. :bug:`2484`
* Fix the importer's detection of multi-disc albums when other subdirectories
are present. :bug:`2493`
* Invalid date queries now print an error message instead of being silently
ignored. Thanks to :user:`discopatrick`. :bug:`2513` :bug:`2517`
* When the SQLite database stops being accessible, we now print a friendly
error message. Thanks to :user:`Mary011196`. :bug:`1676` :bug:`2508`
* :doc:`/plugins/web`: Avoid a crash when sending binary data, such as
Chromaprint fingerprints, in music attributes. :bug:`2542` :bug:`2532`
* Fix a hang when parsing templates that end in newlines. :bug:`2562`
* Fix a crash when reading non-ASCII characters in configuration files on
Windows under Python 3. :bug:`2456` :bug:`2565` :bug:`2566`

We removed backends from two metadata plugins because of bitrot:

* :doc:`/plugins/lyrics`: The Lyrics.com backend has been removed. (It stopped
working because of changes to the site's URL structure.)
:bug:`2548` :bug:`2549`
* :doc:`/plugins/fetchart`: The documentation no longer recommends iTunes
Store artwork lookup because the unmaintained `python-itunes`_ is broken.
Want to adopt it? :bug:`2371` :bug:`1610`

.. _python-itunes: https://github.com/ocelma/python-itunes

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

Happy new year! This new version includes a cornucopia of new features from
contributors, including new tags related to classical music and a new
:doc:`/plugins/absubmit` for performing acoustic analysis on your music. The
:doc:`/plugins/random` has a new mode that lets you generate time-limited
music---for example, you might generate a random playlist that lasts the
perfect length for your walk to work. We also access as many Web services as
possible over secure connections now---HTTPS everywhere!

The most visible new features are:

* We now support the composer, lyricist, and arranger tags. The MusicBrainz
data source will fetch data for these fields when the next version of
`python-musicbrainzngs`_ is released. Thanks to :user:`ibmibmibm`.
:bug:`506` :bug:`507` :bug:`1547` :bug:`2333`
* A new :doc:`/plugins/absubmit` lets you run acoustic analysis software and
upload the results for others to use. Thanks to :user:`inytar`. :bug:`2253`
:bug:`2342`
* :doc:`/plugins/play`: The plugin now provides an importer prompt choice to
play the music you're about to import. Thanks to :user:`diomekes`.
:bug:`2008` :bug:`2360`
* We now use SSL to access Web services whenever possible. That includes
MusicBrainz itself, several album art sources, some lyrics sources, and
other servers. Thanks to :user:`tigranl`. :bug:`2307`
* :doc:`/plugins/random`: A new ``--time`` option lets you generate a random
playlist that takes a given amount of time. Thanks to :user:`diomekes`.
:bug:`2305` :bug:`2322`

Some smaller new features:

* :doc:`/plugins/zero`: A new ``zero`` command manually triggers the zero
plugin. Thanks to :user:`SJoshBrown`. :bug:`2274` :bug:`2329`
* :doc:`/plugins/acousticbrainz`: The plugin will avoid re-downloading data
for files that already have it by default. You can override this behavior
using a new ``force`` option. Thanks to :user:`SusannaMaria`. :bug:`2347`
:bug:`2349`
* :doc:`/plugins/bpm`: The ``import.write`` configuration option now
decides whether or not to write tracks after updating their BPM. :bug:`1992`

And the fixes:

* :doc:`/plugins/bpd`: Fix a crash on non-ASCII MPD commands. :bug:`2332`
* :doc:`/plugins/scrub`: Avoid a crash when files cannot be read or written.
:bug:`2351`
* :doc:`/plugins/scrub`: The image type values on scrubbed files are preserved
instead of being reset to "other." :bug:`2339`
* :doc:`/plugins/web`: Fix a crash on Python 3 when serving files from the
filesystem. :bug:`2353`
* :doc:`/plugins/discogs`: Improve the handling of releases that contain
subtracks. :bug:`2318`
* :doc:`/plugins/discogs`: Fix a crash when a release does not contain format
information, and increase robustness when other fields are missing.
:bug:`2302`
* :doc:`/plugins/lyrics`: The plugin now reports a beets-specific User-Agent
header when requesting lyrics. :bug:`2357`
* :doc:`/plugins/embyupdate`: The plugin now checks whether an API key or a
password is provided in the configuration.
* :doc:`/plugins/play`: The misspelled configuration option
``warning_treshold`` is no longer supported.

For plugin developers: when providing new importer prompt choices (see
:ref:`append_prompt_choices`), you can now provide new candidates for the user
to consider. For example, you might provide an alternative strategy for
picking between the available alternatives or for looking up a release on
MusicBrainz.

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

This is just a little bug fix release. With 1.4.2, we're also confident enough
to recommend that anyone who's interested give Python 3 a try: bugs may still
lurk, but we've deemed things safe enough for broad adoption. If you can,
please install beets with ``pip3`` instead of ``pip2`` this time and let us
know how it goes!

Here are the fixes:

* :doc:`/plugins/badfiles`: Fix a crash on non-ASCII filenames. :bug:`2299`
* The ``%asciify{}`` path formatting function and the :ref:`asciify-paths`
setting properly substitute path separators generated by converting some
Unicode characters, such as ½ and ¢, into ASCII.
* :doc:`/plugins/convert`: Fix a logging-related crash when filenames contain
curly braces. Thanks to :user:`kierdavis`. :bug:`2323`
* We've rolled back some changes to the included zsh completion script that
were causing problems for some users. :bug:`2266`

Also, we've removed some special handling for logging in the
:doc:`/plugins/discogs` that we believe was unnecessary. If spurious log
messages appear in this version, please let us know by filing a bug.

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

Version 1.4 has **alpha-level** Python 3 support. Thanks to the heroic efforts
of :user:`jrobeson`, beets should run both under Python 2.7, as before, and
now under Python 3.4 and above. The support is still new: it undoubtedly
contains bugs, so it may replace all your music with Limp Bizkit---but if
you're brave and you have backups, please try installing on Python 3. Let us
know how it goes.

If you package beets for distribution, here's what you'll want to know:

* This version of beets now depends on the `six`_ library.
* We also bumped our minimum required version of `Mutagen`_ to 1.33 (from
1.27).
* Please don't package beets as a Python 3 application *yet*, even though most
things work under Python 3.4 and later.

This version also makes a few changes to the command-line interface and
configuration that you may need to know about:

* :doc:`/plugins/duplicates`: The ``duplicates`` command no longer accepts
multiple field arguments in the form ``-k title albumartist album``. Each
argument must be prefixed with ``-k``, as in ``-k title -k albumartist -k
album``.
* The old top-level ``colors`` configuration option has been removed (the
setting is now under ``ui``).
* The deprecated ``list_format_album`` and ``list_format_item``
configuration options have been removed (see :ref:`format_album` and
:ref:`format_item`).

The are a few new features:

* :doc:`/plugins/mpdupdate`, :doc:`/plugins/mpdstats`: When the ``host`` option
is not set, these plugins will now look for the ``$MPD_HOST`` environment
variable before falling back to ``localhost``. Thanks to :user:`tarruda`.
:bug:`2175`
* :doc:`/plugins/web`: Added an ``expand`` option to show the items of an
album. :bug:`2050`
* :doc:`/plugins/embyupdate`: The plugin can now use an API key instead of a
password to authenticate with Emby. :bug:`2045` :bug:`2117`
* :doc:`/plugins/acousticbrainz`: The plugin now adds a ``bpm`` field.
* ``beet --version`` now includes the Python version used to run beets.
* :doc:`/reference/pathformat` can now include unescaped commas (``,``) when
they are not part of a function call. :bug:`2166` :bug:`2213`
* The :ref:`update-cmd` command takes a new ``-F`` flag to specify the fields
to update. Thanks to :user:`dangmai`. :bug:`2229` :bug:`2231`

And there are a few bug fixes too:

* :doc:`/plugins/convert`: The plugin no longer asks for confirmation if the
query did not return anything to convert. :bug:`2260` :bug:`2262`
* :doc:`/plugins/embedart`: The plugin now uses ``jpg`` as an extension rather
than ``jpeg``, to ensure consistency with the :doc:`plugins/fetchart`.
Thanks to :user:`tweitzel`. :bug:`2254` :bug:`2255`
* :doc:`/plugins/embedart`: The plugin now works for all jpeg files, including
those that are only recognizable by their magic bytes.
:bug:`1545` :bug:`2255`
* :doc:`/plugins/web`: The JSON output is no longer pretty-printed (for a
space savings). :bug:`2050`
* :doc:`/plugins/permissions`: Fix a regression in the previous release where
the plugin would always fail to set permissions (and log a warning).
:bug:`2089`
* :doc:`/plugins/beatport`: Use track numbers from Beatport (instead of
determining them from the order of tracks) and set the `medium_index`
value.
* With :ref:`per_disc_numbering` enabled, some metadata sources (notably, the
:doc:`/plugins/beatport`) would not set the track number at all. This is
fixed. :bug:`2085`
* :doc:`/plugins/play`: Fix ``$args`` getting passed verbatim to the play
command if it was set in the configuration but ``-A`` or ``--args`` was
omitted.
* With :ref:`ignore_hidden` enabled, non-UTF-8 filenames would cause a crash.
This is fixed. :bug:`2168`
* :doc:`/plugins/embyupdate`: Fixes authentication header problem that caused
a problem that it was not possible to get tokens from the Emby API.
* :doc:`/plugins/lyrics`: Some titles use a colon to separate the main title
from a subtitle. To find more matches, the plugin now also searches for
lyrics using the part part preceding the colon character. :bug:`2206`
* Fix a crash when a query uses a date field and some items are missing that
field. :bug:`1938`
* :doc:`/plugins/discogs`: Subtracks are now detected and combined into a
single track, two-sided mediums are treated as single discs, and tracks
have ``media``, ``medium_total`` and ``medium`` set correctly. :bug:`2222`
:bug:`2228`.
* :doc:`/plugins/missing`: ``missing`` is now treated as an integer, allowing
the use of (for example) ranges in queries.
* :doc:`/plugins/smartplaylist`: Playlist names will be sanitized to
ensure valid filenames. :bug:`2258`
* The ID3 APIC tag now uses the Latin-1 encoding when possible instead of a
Unicode encoding. This should increase compatibility with other software,
especially with iTunes and when using ID3v2.3. Thanks to :user:`lazka`.
:bug:`899` :bug:`2264` :bug:`2270`

The last release, 1.3.19, also erroneously reported its version as "1.3.18"
when you typed ``beet version``. This has been corrected.

.. _six: https://pypi.org/project/six/