Beets

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

This third beta of beets 1.1 brings a hodgepodge of little new features (and
internal overhauls that will make improvements easier in the future). There
are new options for getting metadata in a particular language and seeing more
detail during the import process. There's also a new plugin for synchronizing
your metadata with MusicBrainz. Under the hood, plugins can now extend the
query syntax.

New configuration options:

* :ref:`languages` controls the preferred languages when selecting an alias
from MusicBrainz. This feature requires `python-musicbrainzngs`_ 0.3 or
later. Thanks to Sam Doshi.
* :ref:`detail` enables a mode where all tracks are listed in the importer UI,
as opposed to only changed tracks.
* The ``--flat`` option to the ``beet import`` command treats an entire
directory tree of music files as a single album. This can help in situations
where a multi-disc album is split across multiple directories.
* :doc:`/plugins/importfeeds`: An option was added to use absolute, rather
than relative, paths. Thanks to Lucas Duailibe.

Other stuff:

* A new :doc:`/plugins/mbsync` provides a command that looks up each item and
track in MusicBrainz and updates your library to reflect it. This can help
you easily correct errors that have been fixed in the MB database. Thanks to
Jakob Schnitzer.
* :doc:`/plugins/fuzzy`: The ``fuzzy`` command was removed and replaced with a
new query type. To perform fuzzy searches, use the ``~`` prefix with
:ref:`list-cmd` or other commands. Thanks to Philippe Mongeau.
* As part of the above, plugins can now extend the query syntax and new kinds
of matching capabilities to beets. See :ref:`extend-query`. Thanks again to
Philippe Mongeau.
* :doc:`/plugins/convert`: A new ``--keep-new`` option lets you store
transcoded files in your library while backing up the originals (instead of
vice-versa). Thanks to Lucas Duailibe.
* :doc:`/plugins/convert`: Also, a new ``auto`` config option will transcode
audio files automatically during import. Thanks again to Lucas Duailibe.
* :doc:`/plugins/chroma`: A new ``fingerprint`` command lets you generate and
store fingerprints for items that don't yet have them. One more round of
applause for Lucas Duailibe.
* ``echonest_tempo``: API errors now issue a warning instead of
exiting with an exception. We also avoid an error when track metadata
contains newlines.
* When the importer encounters an error (insufficient permissions, for
example) when walking a directory tree, it now logs an error instead of
crashing.
* In path formats, null database values now expand to the empty string instead
of the string "None".
* Add "System Volume Information" (an internal directory found on some
Windows filesystems) to the default ignore list.
* Fix a crash when ReplayGain values were set to null.
* Fix a crash when iTunes Sound Check tags contained invalid data.
* Fix an error when the configuration file (``config.yaml``) is completely
empty.
* Fix an error introduced in 1.1b1 when importing using timid mode. Thanks to
Sam Doshi.
* :doc:`/plugins/convert`: Fix a bug when creating files with Unicode
pathnames.
* Fix a spurious warning from the Unidecode module when matching albums that
are missing all metadata.
* Fix Unicode errors when a directory or file doesn't exist when invoking the
import command. Thanks to Lucas Duailibe.
* :doc:`/plugins/mbcollection`: Show friendly, human-readable errors when
MusicBrainz exceptions occur.
* ``echonest_tempo``: Catch socket errors that are not handled by
the Echo Nest library.
* :doc:`/plugins/chroma`: Catch Acoustid Web service errors when submitting
fingerprints.

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

The second beta of beets 1.1 uses the fancy new configuration infrastructure to
add many, many new config options. The import process is more flexible;
filenames can be customized in more detail; and more. This release also
supports Windows Media (ASF) files and iTunes Sound Check volume normalization.

This version introduces one **change to the default behavior** that you should
be aware of. Previously, when importing new albums matched in MusicBrainz, the
date fields (``year``, ``month``, and ``day``) would be set to the release date
of the *original* version of the album, as opposed to the specific date of the
release selected. Now, these fields reflect the specific release and
``original_year``, etc., reflect the earlier release date. If you want the old
behavior, just set :ref:`original_date` to true in your config file.

New configuration options:

* :ref:`default_action` lets you determine the default (just-hit-return) option
is when considering a candidate.
* :ref:`none_rec_action` lets you skip the prompt, and automatically choose an
action, when there is no good candidate. Thanks to Tai Lee.
* :ref:`max_rec` lets you define a maximum recommendation for albums with
missing/extra tracks or differing track lengths/numbers. Thanks again to Tai
Lee.
* :ref:`original_date` determines whether, when importing new albums, the
``year``, ``month``, and ``day`` fields should reflect the specific (e.g.,
reissue) release date or the original release date. Note that the original
release date is always available as ``original_year``, etc.
* :ref:`clutter` controls which files should be ignored when cleaning up empty
directories. Thanks to Steinþór Pálsson.
* :doc:`/plugins/lastgenre`: A new configuration option lets you choose to
retrieve artist-level tags as genres instead of album- or track-level tags.
Thanks to Peter Fern and Peter Schnebel.
* :ref:`max_filename_length` controls truncation of long filenames. Also, beets
now tries to determine the filesystem's maximum length automatically if you
leave this option unset.
* :doc:`/plugins/fetchart`: The ``remote_priority`` option searches remote
(Web) art sources even when local art is present.
* You can now customize the character substituted for path separators (e.g., /)
in filenames via ``path_sep_replace``. The default is an underscore. Use this
setting with caution.

Other new stuff:

* Support for Windows Media/ASF audio files. Thanks to Dave Hayes.
* New :doc:`/plugins/smartplaylist`: generate and maintain m3u playlist files
based on beets queries. Thanks to Dang Mai Hai.
* ReplayGain tags on MPEG-4/AAC files are now supported. And, even more
astonishingly, ReplayGain values in MP3 and AAC files are now compatible with
`iTunes Sound Check`_. Thanks to Dave Hayes.
* Track titles in the importer UI's difference display are now either aligned
vertically or broken across two lines for readability. Thanks to Tai Lee.
* Albums and items have new fields reflecting the *original* release date
(``original_year``, ``original_month``, and ``original_day``). Previously,
when tagging from MusicBrainz, *only* the original date was stored; now, the
old fields refer to the *specific* release date (e.g., when the album was
reissued).
* Some changes to the way candidates are recommended for selection, thanks to
Tai Lee:

* According to the new :ref:`max_rec` configuration option, partial album
matches are downgraded to a "low" recommendation by default.
* When a match isn't great but is either better than all the others or the
only match, it is given a "low" (rather than "medium") recommendation.
* There is no prompt default (i.e., input is required) when matches are
bad: "low" or "none" recommendations or when choosing a candidate
other than the first.

* The importer's heuristic for coalescing the directories in a multi-disc album
has been improved. It can now detect when two directories alongside each
other share a similar prefix but a different number (e.g., "Album Disc 1" and
"Album Disc 2") even when they are not alone in a common parent directory.
Thanks once again to Tai Lee.
* Album listings in the importer UI now show the release medium (CD, Vinyl,
3xCD, etc.) as well as the disambiguation string. Thanks to Peter Schnebel.
* :doc:`/plugins/lastgenre`: The plugin can now get different genres for
individual tracks on an album. Thanks to Peter Schnebel.
* When getting data from MusicBrainz, the album disambiguation string
(``albumdisambig``) now reflects both the release and the release group.
* :doc:`/plugins/mpdupdate`: Sends an update message whenever *anything* in the
database changes---not just when importing. Thanks to Dang Mai Hai.
* When the importer UI shows a difference in track numbers or durations, they
are now colorized based on the *suffixes* that differ. For example, when
showing the difference between 2:01 and 2:09, only the last digit will be
highlighted.
* The importer UI no longer shows a change when the track length difference is
less than 10 seconds. (This threshold was previously 2 seconds.)
* Two new plugin events were added: *database_change* and *cli_exit*. Thanks
again to Dang Mai Hai.
* Plugins are now loaded in the order they appear in the config file. Thanks to
Dang Mai Hai.
* :doc:`/plugins/bpd`: Browse by album artist and album artist sort name.
Thanks to Steinþór Pálsson.
* ``echonest_tempo``: Don't attempt a lookup when the artist or
track title is missing.
* Fix an error when migrating the ``.beetsstate`` file on Windows.
* A nicer error message is now given when the configuration file contains tabs.
(YAML doesn't like tabs.)
* Fix the ``-l`` (log path) command-line option for the ``import`` command.

.. _iTunes Sound Check: https://support.apple.com/kb/HT2425

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

This release entirely revamps beets' configuration system. The configuration
file is now a `YAML`_ document and is located, along with other support files,
in a common directory (e.g., ``~/.config/beets`` on Unix-like systems).

.. _YAML: https://en.wikipedia.org/wiki/YAML

* Renamed plugins: The ``rdm`` plugin has been renamed to ``random`` and
``fuzzy_search`` has been renamed to ``fuzzy``.
* Renamed config options: Many plugins have a flag dictating whether their
action runs at import time. This option had many names (``autofetch``,
``autoembed``, etc.) but is now consistently called ``auto``.
* Reorganized import config options: The various ``import_*`` options are now
organized under an ``import:`` heading and their prefixes have been removed.
* New default file locations: The default filename of the library database is
now ``library.db`` in the same directory as the config file, as opposed to
``~/.beetsmusic.blb`` previously. Similarly, the runtime state file is now
called ``state.pickle`` in the same directory instead of ``~/.beetsstate``.

It also adds some new features:

* :doc:`/plugins/inline`: Inline definitions can now contain statements or
blocks in addition to just expressions. Thanks to Florent Thoumie.
* Add a configuration option, :ref:`terminal_encoding`, controlling the text
encoding used to print messages to standard output.
* The MusicBrainz hostname (and rate limiting) are now configurable. See
:ref:`musicbrainz-config`.
* You can now configure the similarity thresholds used to determine when the
autotagger automatically accepts a metadata match. See :ref:`match-config`.
* :doc:`/plugins/importfeeds`: Added a new configuration option that controls
the base for relative paths used in m3u files. Thanks to Philippe Mongeau.

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

After fifteen betas and two release candidates, beets has finally hit
one-point-oh. Congratulations to everybody involved. This version of beets will
remain stable and receive only bug fixes from here on out. New development is
ongoing in the betas of version 1.1.

* :doc:`/plugins/scrub`: Fix an incompatibility with Python 2.6.
* :doc:`/plugins/lyrics`: Fix an issue that failed to find lyrics when metadata
contained "real" apostrophes.
* :doc:`/plugins/replaygain`: On Windows, emit a warning instead of
crashing when analyzing non-ASCII filenames.
* Silence a spurious warning from version 0.04.12 of the Unidecode module.

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

This second release candidate follows quickly after rc1 and fixes a few small
bugs found since that release. There were a couple of regressions and some bugs
in a newly added plugin.

* ``echonest_tempo``: If the Echo Nest API limit is exceeded or a
communication error occurs, the plugin now waits and tries again instead of
crashing. Thanks to Zach Denton.
* :doc:`/plugins/fetchart`: Fix a regression that caused crashes when art was
not available from some sources.
* Fix a regression on Windows that caused all relative paths to be "not found".

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

The first release candidate for beets 1.0 includes a deluge of new features
contributed by beets users. The vast majority of the credit for this release
goes to the growing and vibrant beets community. A million thanks to everybody
who contributed to this release.

There are new plugins for transcoding music, fuzzy searches, tempo collection,
and fiddling with metadata. The ReplayGain plugin has been rebuilt from
scratch. Album art images can now be resized automatically. Many other smaller
refinements make things "just work" as smoothly as possible.

With this release candidate, beets 1.0 is feature-complete. We'll be fixing
bugs on the road to 1.0 but no new features will be added. Concurrently, work
begins today on features for version 1.1.

* New plugin: :doc:`/plugins/convert` **transcodes** music and embeds album art
while copying to a separate directory. Thanks to Jakob Schnitzer and Andrew G.
Dunn.
* New plugin: :doc:`/plugins/fuzzy` lets you find albums and tracks
using **fuzzy string matching** so you don't have to type (or even remember)
their exact names. Thanks to Philippe Mongeau.
* New plugin: ``echonest_tempo`` fetches **tempo** (BPM) information
from `The Echo Nest`_. Thanks to David Brenner.
* New plugin: :doc:`/plugins/the` adds a template function that helps format
text for nicely-sorted directory listings. Thanks to Blemjhoo Tezoulbr.
* New plugin: :doc:`/plugins/zero` **filters out undesirable fields** before
they are written to your tags. Thanks again to Blemjhoo Tezoulbr.
* New plugin: :doc:`/plugins/ihate` automatically skips (or warns you about)
importing albums that match certain criteria. Thanks once again to Blemjhoo
Tezoulbr.
* :doc:`/plugins/replaygain`: This plugin has been completely overhauled to use
the `mp3gain`_ or `aacgain`_ command-line tools instead of the failure-prone
Gstreamer ReplayGain implementation. Thanks to Fabrice Laporte.
* :doc:`/plugins/fetchart` and :doc:`/plugins/embedart`: Both plugins can now
**resize album art** to avoid excessively large images. Use the ``maxwidth``
config option with either plugin. Thanks to Fabrice Laporte.
* :doc:`/plugins/scrub`: Scrubbing now removes *all* types of tags from a file
rather than just one. For example, if your FLAC file has both ordinary FLAC
tags and ID3 tags, the ID3 tags are now also removed.
* :ref:`stats-cmd` command: New ``--exact`` switch to make the file size
calculation more accurate (thanks to Jakob Schnitzer).
* :ref:`list-cmd` command: Templates given with ``-f`` can now show items' and
albums' paths (using ``$path``).
* The output of the :ref:`update-cmd`, :ref:`remove-cmd`, and :ref:`modify-cmd`
commands now respects the :ref:`list_format_album` and
:ref:`list_format_item` config options. Thanks to Mike Kazantsev.
* The :ref:`art-filename` option can now be a template rather than a simple
string. Thanks to Jarrod Beardwood.
* Fix album queries for ``artpath`` and other non-item fields.
* Null values in the database can now be matched with the empty-string regular
expression, ``^$``.
* Queries now correctly match non-string values in path format predicates.
* When autotagging a various-artists album, the album artist field is now
used instead of the majority track artist.
* :doc:`/plugins/lastgenre`: Use the albums' existing genre tags if they pass
the whitelist (thanks to Fabrice Laporte).
* :doc:`/plugins/lastgenre`: Add a ``lastgenre`` command for fetching genres
post facto (thanks to Jakob Schnitzer).
* :doc:`/plugins/fetchart`: Local image filenames are now used in alphabetical
order.
* :doc:`/plugins/fetchart`: Fix a bug where cover art filenames could lack
a ``.jpg`` extension.
* :doc:`/plugins/lyrics`: Fix an exception with non-ASCII lyrics.
* :doc:`/plugins/web`: The API now reports file sizes (for use with the
`Tomahawk resolver`_).
* :doc:`/plugins/web`: Files now download with a reasonable filename rather
than just being called "file" (thanks to Zach Denton).
* :doc:`/plugins/importfeeds`: Fix error in symlink mode with non-ASCII
filenames.
* :doc:`/plugins/mbcollection`: Fix an error when submitting a large number of
releases (we now submit only 200 releases at a time instead of 350). Thanks
to Jonathan Towne.
* :doc:`/plugins/embedart`: Made the method for embedding art into FLAC files
`standard
<https://wiki.xiph.org/VorbisComment#METADATA_BLOCK_PICTURE>`_-compliant.
Thanks to Daniele Sluijters.
* Add the track mapping dictionary to the ``album_distance`` plugin function.
* When an exception is raised while reading a file, the path of the file in
question is now logged (thanks to Mike Kazantsev).
* Truncate long filenames based on their *bytes* rather than their Unicode
*characters*, fixing situations where encoded names could be too long.
* Filename truncation now incorporates the length of the extension.
* Fix an assertion failure when the MusicBrainz main database and search server
disagree.
* Fix a bug that caused the :doc:`/plugins/lastgenre` and other plugins not to
modify files' tags even when they successfully change the database.
* Fix a VFS bug leading to a crash in the :doc:`/plugins/bpd` when files had
non-ASCII extensions.
* Fix for changing date fields (like "year") with the :ref:`modify-cmd`
command.
* Fix a crash when input is read from a pipe without a specified encoding.
* Fix some problem with identifying files on Windows with Unicode directory
names in their path.
* Fix a crash when Unicode queries were used with ``import -L`` re-imports.
* Fix an error when fingerprinting files with Unicode filenames on Windows.
* Warn instead of crashing when importing a specific file in singleton mode.
* Add human-readable error messages when writing files' tags fails or when a
directory can't be created.
* Changed plugin loading so that modules can be imported without
unintentionally loading the plugins they contain.

.. _The Echo Nest: https://web.archive.org/web/20180329103558/http://the.echonest.com/
.. _Tomahawk resolver: https://beets.io/blog/tomahawk-resolver.html
.. _mp3gain: http://mp3gain.sourceforge.net/download.php
.. _aacgain: https://aacgain.altosdesign.com