Skip to content

Releases: beetbox/beets

Release v2.10.0

19 Apr 19:11

Choose a tag to compare

New features

  • Beets library is now made portable: item and album-art paths are now stored relative to the library root in the database while remaining absolute in the rest of beets. Path queries continue matching both library-relative paths and absolute paths under the currently configured music directory under the new storage model. The existing paths in the database are migrated automatically the first time you run any beet command after the update. πŸ› (#133)

Warning

make sure you run beet version (or any other command) at least once after upgrading to trigger the migration. Only then you can safely move the library to a new location.

  • Inline Plugin: Add access to the album or item object as db_obj in inline fields.
  • Discogs Plugin: Import Discogs remixer, lyricist, composer, and arranger credits into the multi-value remixers, lyricists, composers, and arrangers fields. πŸ› (#6380)
  • Lyrics Plugin: Add keep_synced config option and --keep-synced CLI flag to skip re-fetching lyrics for tracks that already have synced lyrics, even when force is enabled. πŸ› (#5249)
  • MusicBrainz Plugin: Use aliases for artist credit.
  • Metadata source plugin searches and lookups are now executed concurrently, speeding up lookups when multiple plugins (e.g. MusicBrainz and Spotify) are enabled.

Bug fixes

  • Chromaprint/Acoustid Plugin: Do not produce MusicBrainz-sourced autotagger candidates when the MusicBrainz Plugin plugin is not enabled. The chroma plugin now looks up the musicbrainz plugin through the metadata-source registry instead of unconditionally instantiating its own private instance, which also restores compatibility with MusicBrainz Pseudo-Release Plugin for chroma-triggered lookups. πŸ› (#6212) πŸ› (#6441)
  • import command Automatically remux WAV files containing MP3 streams (WAVE_FORMAT_MPEGLAYER3) to proper MP3 files during import, instead of silently importing them with incorrect metadata. πŸ› (#6455)
  • import command Remove clutter from imported album folders. πŸ› (#5016)
  • ListenBrainz Plugin: Retry listenbrainz requests for temporary failures.
  • Web Plugin: Fix a stored XSS vulnerability where unescaped metadata fields (artist, album, title, comments, lyrics) could execute arbitrary JavaScript in the browser. Template tags now use <%- (escaped interpolation) instead of <%= (raw interpolation).

For plugin developers

  • Consumers of beetsplug._utils.musicbrainz.MusicBrainzAPI now receive normalized MusicBrainz payloads with underscore-separated field names (for example artist_credit and release_group) and grouped relation lists such as work_relations, release_relations, and url_relations. The API responses are also now fully typed with concrete TypedDict models for releases, recordings, works, and relations. Update direct access to raw MusicBrainz response keys if needed.

Release v2.9.0

11 Apr 11:57

Choose a tag to compare

Beets now officially supports Python 3.14.

New features

  • AutoBPM Plugin: Add force configuration and CLI option and deprecate overwrite.
  • AutoBPM Plugin: The "BPM already exists for item" log message can now be hidden with the --quiet flag.
  • Chromaprint/Acoustid Plugin: Add new command chromasearch to search the local library by chromaprint fingerprint.
  • FetchArt Plugin: Add support for WebP images.
  • import command Use ffprobe to recognize format of any import music file that has no extension. If the file cannot be recognized as a music file, leave it alone. πŸ› (#4881)
  • LastGenre Plugin: Add support for a user-configurable ignorelist to exclude unwanted or incorrect Last.fm (or existing) genres, either per artist or globally πŸ› (#6449)
  • MusicBrainz Plugin: Store MBIDs for remixers, lyricists, composers, and arrangers in the new multi-valued fields remixers_mbid, lyricists_mbid, composers_mbid, and arrangers_mbid. πŸ› (#5698)
  • ReplayGain Plugin: Conflicting replay gain tags are now removed on write. RG* tags are removed when setting R128* and vice versa.
  • Smart Playlist Plugin: The list of available playlists shown when an unknown playlist name is passed as an argument is now sorted alphabetically and printed space-delimited and POSIX shell-quoted when required. This makes it easier to copy and paste multiple playlists for further use in the shell.
  • Query: Add has_cover_art computed field to query items by embedded cover art presence. Users can now search for tracks with or without embedded artwork using beet list has_cover_art:true or beet list has_cover_art:false.
  • Store track remixers, lyricists, composers, and arrangers in the multi-valued remixers, lyricists, composers, and arrangers fields instead of the legacy single-value remixer, lyricist, composer, and arranger fields. Existing libraries are migrated automatically, and MusicBrainz Plugin now preserves each MusicBrainz remixer, lyricist, composer, and arranger relation as a separate value.

Bug fixes

  • Deezer Plugin: Fix a regression in 2.8.0 where selecting a Deezer match during import could crash with AttributeError: 'AlbumInfo' object has no attribute 'raw_data' when Deezer returned numeric artist IDs. πŸ› (#6503)
  • Deezer Plugin: Fix Various Artists albums being tagged with a localized string instead of the configured va_name. Detection now uses Deezer's artist ID rather than the artist name string. πŸ› (#4956)
  • Discogs Plugin: Store specific Discogs styles in beets genres and broader Discogs genres in the style field. When append_style_genre is enabled, the broader Discogs genres are also appended to the genres list. πŸ› (#6390)
  • FetchArt Plugin: Error when a configured source does not exist or sources configuration is empty. πŸ› (#6336)
  • import command Fix albumartists_sort (and related fields) incorrectly prepending the full combined artist credit as the first element for multi-artist releases. πŸ› (#6470)
  • ListenBrainz Plugin: Fix lbimport crashing when ListenBrainz tracks are processed through Last.fm-specific play-count import logic. Play-count imports now use source-specific fields so ListenBrainz Plugin, LastImport Plugin, and MPDStats Plugin do not clash. πŸ› (#6469)
  • ListenBrainz Plugin: Paginate through all ListenBrainz listens instead of fetching only 25, aggregate individual listen events into correct play counts, use recording_mbid from the ListenBrainz mapping when available, and avoid per-listen MusicBrainz API lookups that caused imports to hang on large listen histories. πŸ› (#6469)
  • modify command accepts legacy singular field names such as genre, composer, lyricist, remixer, and arranger in assignments, rewrites them to the corresponding multi-valued fields, and warns users to switch to the plural field names. list command, and query expressions, accept the same legacy singular field names and warn users to switch to the plural field names. πŸ› (#6483)
  • Rewrite Plugin Advanced Rewrite Plugin: Fix rewriting multi-valued fields such as genres by applying rules to each matching list entry. Additionally, apply rewrite rules in config order, so that multiple rules can be applied to the same field. πŸ› (#6515)
  • Correctly handle semicolon-delimited genre values from externally-tagged files. πŸ› (#6450)

For plugin developers

  • If you maintain a metadata source plugin that populates any of arranger, composer, lyricist, remixer fields, update it to populate the respective multi-valued fields instead (arrangers, composers, lyricists, remixers).

Release v2.8.0

28 Mar 13:11

Choose a tag to compare

New features

  • Discogs Plugin: Add extra_tags option to use additional tags (such as barcode, catalognum, country, label, media, and year) in Discogs search queries.
  • Lyrics Plugin: Add auto_ignore configuration option to skip fetching lyrics for items matching a beets query during auto import.
  • Missing Plugin: When running in missing album mode, allows users to specify MusicBrainz release types to show using the --release-type flag. The default behavior is also changed to just show releases of type album. πŸ› (#2661)
  • Play Plugin: Added -R/--randomize flag to shuffle the playlist order before passing it to the player.
  • Smart Playlist Plugin: Add new configuration option dest_regen to regenerate items' path in the generated playlist instead of using those in the library. This is useful when items have been imported in don't copy-move (-C -M) mode in the library but are later passed through the Convert Plugin plugin which will regenerate new paths according to the Beets path format.

Bug fixes

  • Beatport Plugin: Use va_name config for the album artist on VA releases instead of hardcoded "Various Artists". πŸ› (#6316)
  • config command on Windows now uses cmd /c start "" for the default editor fallback so beet config -e works when VISUAL and EDITOR are unset. πŸ› (#6436)
  • Fish Plugin: Fix AttributeError. πŸ› (#6340)
  • import command Autotagging by explicit release or recording IDs now keeps candidates from all enabled metadata sources instead of dropping matches when different providers share the same ID. πŸ› (#6178) πŸ› (#6181)
  • import command Simplify autotag metadata application for albums and singletons, fixing null-overwrite handling and keeping singular/plural artist metadata fields in sync during tagging.
  • LastImport Plugin: Rename flexible field play_count to lastfm_play_count to avoid conflicts with MPDStats Plugin. Migration: This cannot be migrated automatically because of the field clash. If you use LastImport Plugin without MPDStats Plugin, migrate manually with beet modify lastfm_play_count='$play_count'.
  • MBSync Plugin and Missing Plugin now use each item's stored data_source for ID lookups, with a fallback to MusicBrainz.
  • Missing Plugin: Fix --album mode incorrectly reporting albums already in the library as missing. The comparison now correctly uses mb_releasegroupid.
  • MusicBrainz Plugin: Use va_name config for albumartist_sort, albumartists_sort, albumartist_credit, albumartists_credit, and albumartists on VA releases instead of hardcoded "Various Artists". πŸ› (#6316)
  • replace: Made drive_sep_replace regex logic more precise to prevent edge-case mismatches (e.g., a song titled "1:00 AM" would incorrectly be considered a Windows drive path).

For plugin developers

  • beets.metadata_plugins.album_for_id and beets.metadata_plugins.track_for_id now require a data_source argument and query only that provider.
  • Colorisation, diff and layout utility helpers previously imported from beets.ui now live in beets.util.color, beets.util.diff, and beets.util.layout. Update external imports accordingly.
  • The lastgenre tunelog helper was generalized into beets.logging.BeetsLogger.extra_debug, which emits DEBUG messages only at verbosity level 3 or higher (for example -vvv). Plugin authors can use it via self._log.extra_debug(...).

Other changes

  • Contributing: Update pipx installation guide link
  • Getting Started: Update quick installation section to reflect current installation guide structure.
  • Installation: Remove redundant macOS section from the installation guide. πŸ› (#5993)
  • Installation: Update installation guide to document plugin management with pipx and move package manager instructions to the FAQ.
  • Installation: Update pipx installation guide link
  • API-backed metadata source plugins can now use SearchApiMetadataSourcePlugin for shared search orchestration. Implement provider behavior in ~beets.metadata_plugins.SearchApiMetadataSourcePlugin.get_search_query_with_filters and ~beets.metadata_plugins.SearchApiMetadataSourcePlugin.get_search_response.
  • Deprecate the Beatport Plugin and BPSync Plugin plugins. Beatport has retired the API these plugins rely on, making them non-functional. πŸ› (#3862)

Release v2.7.1

08 Mar 08:31

Choose a tag to compare

Bug fixes

  • Tests that depend on the optional langdetect package are now skipped when the package is not installed. πŸ› (#6421)

Release v2.7.0

07 Mar 21:17

Choose a tag to compare

New features

  • LastGenre Plugin: Added cleanup_existing configuration flag to allow whitelist canonicalization of existing genres.

  • Add native support for multiple genres per album/track. The genres field now stores genres as a list and is written to files as multiple individual genre tags (e.g., separate GENRE tags for FLAC/MP3). The MusicBrainz Plugin, Beatport Plugin, Discogs Plugin and LastGenre Plugin plugins have been updated to populate the genres field as a list.

    Migration: Existing libraries with comma-separated, semicolon-separated, or slash-separated genre strings (e.g., "Rock, Alternative, Indie") are automatically migrated to the genres list when you first run beets after upgrading. The migration runs once when the database schema is updated, splitting genre strings and writing the changes to the database. The updated genres values will be written to media files the next time you run a command that writes tags (such as write command or during import). No manual action or MBSync Plugin is required.

    The genre field is split by the first separator found in the string, in the following order of precedence:

    1. LastGenre Plugin separator configuration
    2. Semicolon followed by a space
    3. Comma followed by a space
    4. Slash wrapped by spaces
  • Lyrics Plugin: With synced enabled, existing synced lyrics are no longer replaced by newly fetched plain lyrics, even when force is enabled.

  • Lyrics Plugin: Remove Source: <lyrics-url> suffix from lyrics. Store the backend name in lyrics_backend, URL in lyrics_url, language in lyrics_language and translation language (if translations present) in lyrics_translation_language flexible attributes. Lyrics are automatically migrated on the first beets run. πŸ› (#6370)

Bug fixes

  • Convert Plugin: Fix extension substitution inside path of the exported playlist.
  • FetchArt Plugin: Prevent deletion of configured fallback cover art
  • FtInTitle Plugin: Fix handling of multiple featured artists with ampersand.
  • Fuzzy Search Plugin: Force slow query evaluation whenever the fuzzy prefix is used (for example ~foo or %%foo), so fuzzy matching is applied consistently. πŸ› (#5638)
  • Fuzzy Search Plugin: Improve fuzzy matching when the query is shorter than the field value so substring-style searches produce more useful results. πŸ› (#2043)
  • import command Duplicate detection now works for as-is imports (when autotag is disabled). Previously, duplicate_keys and duplicate_action config options were silently ignored for as-is imports.
  • import command When autotagging, initialise empty multi-valued fields with None instead of empty list, which caused beets to overwrite existing metadata with empty list values instead of leaving them unchanged. πŸ› (#6403)
  • Zero Plugin: When the omit_single_disc option is set, disctotal is zeroed alongside disc.

For plugin developers

  • If you maintain a metadata source plugin that populates the genre field, please update it to populate a list of genres instead. You will see a deprecation warning for now, but support for populating the single genre field will be removed in version 3.0.0.

Other changes

  • Edit Plugin: Editing multi-valued fields now behaves more naturally, with list values handled directly to make metadata edits smoother and more predictable.
  • LastGenre Plugin: The separator configuration option is removed. Since genres are now stored as a list in the genres field and written to files as individual genre tags, this option has no effect and has been removed.
  • Lyrics Plugin: To cut down noise from the lrclib lyrics source, synced lyrics are now checked to ensure the final verse falls within the track's duration.
  • modify command: Use the following separator to delimit multiple field values: ; . For example beet modify albumtypes="album; ep". Previously, \␀ was used as a separator. This applies to fields such as artists, AlbumTypes Plugin etc.
  • Improve highlighting of multi-valued fields changes.
  • Updated URLs in the documentation to use HTTPS where possible and updated outdated links.

Release v2.6.2

22 Feb 16:06

Choose a tag to compare

Bug fixes

Other changes

  • Lyrics Plugin: Disable tekstowo by default because it blocks the beets User-Agent.

Release v2.6.1

02 Feb 02:30

Choose a tag to compare

Bug fixes

  • Make packaging a required dependency. πŸ› (#6332)

Release v2.6.0

01 Feb 14:44

Choose a tag to compare

Beets now requires Python 3.10 or later since support for EOL Python 3.9 has been dropped.

New features

  • Added support for Python 3.13.
  • Convert Plugin: force can be passed to override checks like no_convert, never_convert_lossy_files, same format, and max_bitrate
  • Discogs Plugin: Added support for multi value fields. πŸ› (#6068)
  • EmbedArt Plugin: Embedded arts can now be cleared during import with the clearart_on_import config option. Also, beet clearart is only going to update the files matching the query and with an embedded art, leaving untouched the files without.
  • FetchArt Plugin: Added config setting for a fallback cover art image.
  • FetchArt Plugin: Fix colorized output text.
  • Fish Plugin: Filenames are now completed in more places, like after import.
  • FtInTitle Plugin: Added album template value album_artist_no_feat.
  • FtInTitle Plugin: Added argument for custom feat. words in ftintitle.
  • FtInTitle Plugin: Added argument to skip the processing of artist and album artist are the same in ftintitle.
  • FtInTitle Plugin: Featured artists are now inserted before brackets containing remix/edit-related keywords (e.g., "Remix", "Live", "Edit") instead of being appended at the end. This improves formatting for titles like "Song 1 (Carol Remix) ft. Bob" which becomes "Song 1 ft. Bob (Carol Remix)". A variety of brackets are supported and a new bracket_keywords configuration option allows customizing the keywords. Setting bracket_keywords to an empty list matches any bracket content regardless of keywords.
  • ImportSource Plugin: Added new plugin that tracks original import paths and optionally suggests removing source files when items are removed from the library.
  • LastGenre Plugin: For tuning plugin settings -vvv can be passed to receive extra verbose logging around last.fm results and how they are resolved. The extended_debug config setting and --debug option have been removed.
  • MusicBrainz Plugin: Allow selecting tags or genres to populate the genres tag.
  • MusicBrainz Pseudo-Release Plugin: Add a new MusicBrainz Pseudo-Release Plugin plugin to proactively receive MusicBrainz pseudo-releases as recommendations during import.
  • Play Plugin: Added $playlist marker to precisely edit the playlist filepath into the command calling the player program.
  • Random Plugin: Added --field option to specify which field to use for equal-chance sampling (default: albumartist).
  • Spotify Plugin: Added support for multi-artist albums and tracks, saving all contributing artists to the respective fields.
  • Titlecase Plugin: Add the Titlecase Plugin plugin to allow users to resolve differences in metadata source styles.

Bug fixes

  • Errors in metadata plugins during autotage process will now be logged but won't crash beets anymore. If you want to raise exceptions instead, set the new configuration option raise_on_error to yes πŸ› (#5903), πŸ› (#4789).
  • Fix a bug introduced in release 2.4.0 where import from any valid import-log-file always threw a "none of the paths are importable" error.
  • Handle potential OSError when unlinking temporary files in ArtResizer. πŸ› (#5615)
  • Running beet --config <mypath> config -e now edits <mypath> rather than the default config path. πŸ› (#5652)
  • Sanitize log messages by removing control characters preventing terminal rendering issues.
  • When hardlinking from a symlink (e.g. importing a symlink with hardlinking enabled), dereference the symlink then hardlink, rather than creating a new (potentially broken) symlink πŸ› (#5676)
  • When using FromFilename Plugin together with Edit Plugin, temporary tags extracted from filenames are no longer lost when discarding or cancelling an edit session during import. πŸ› (#6104)
  • Command-Line Interface: Fix 'from_scratch' option for singleton imports: delete all (old) metadata when new metadata is applied. πŸ› (#3706)
  • Convert Plugin: auto_keep now respects no_convert and never_convert_lossy_files when deciding whether to copy/transcode items, avoiding extra lossy duplicates.
  • Discogs Plugin: Fixed unexpected flex attr from the Discogs plugin. πŸ› (#6177)
  • FtInTitle Plugin: Fixed artist name splitting to prioritize explicit featuring tokens (feat, ft, featuring) over generic separators (&, and), preventing incorrect splits when both are present.
  • Inline Plugin: Fix recursion error when an inline field definition shadows a built-in item field (e.g., redefining track_no). Inline expressions now skip self-references during evaluation to avoid infinite recursion. πŸ› (#6115)
  • LastGenre Plugin: Canonicalize genres when force and keep_existing are on, yet no genre info on lastfm could be found. πŸ› (#6303)
  • LastGenre Plugin: Fix the issue where last.fm doesn't return any result in the artist genre stage because "concatenation" words in the artist name (like "feat.", "+", or "&") prevent it. Using the albumartists list field and fetching a genre for each artist separately improves the chance of receiving valid results in that stage.
  • Lyrics Plugin: Accepts strings for lyrics sources (previously only accepted a list of strings). πŸ› (#5962)
  • Smart Playlist Plugin: Fixed an issue where multiple queries in a playlist configuration were not preserving their order, causing items to appear in database order rather than the order specified in the config. πŸ› (#6183)
  • Spotify Plugin: The plugin now gracefully handles audio-features API deprecation (HTTP 403 errors). When a 403 error is encountered from the audio-features endpoint, the plugin logs a warning once and skips audio features for all remaining tracks in the session, avoiding unnecessary API calls and rate limit exhaustion.
  • Spotify Plugin: Updated Spotify API credentials. πŸ› (#6270)
  • Web Plugin: repair broken /item/values/… and /albums/values/… endpoints. Previously, due to single-quotes (ie. string literal) in the SQL query, the query eg. GET /item/values/albumartist would return the literal "albumartist" instead of a list of unique album artists.
  • update Edit Plugin fix display formatting of field changes to clearly show added and removed flexible fields.

For plugin developers

Read more

Release v2.5.1

14 Oct 22:53

Choose a tag to compare

New features

  • Zero Plugin: Add new configuration option, omit_single_disc, to allow zeroing the disc number on write for single-disc albums. Defaults to False.

Bug fixes

For packagers

  • Fixed issue with legacy metadata plugins not copying properties from the base class.
  • Reverted the following: When installing beets via git or locally the version string now reflects the current git branch and commit hash. πŸ› (#6089)

Other changes

  • Removed outdated mailing list contact information from the documentation πŸ› (#5462).
  • Getting Started: Modernized the Getting Started guide with tabbed sections and dropdown menus. Installation instructions have been streamlined, and a new subpage now provides additional setup details.

Release v2.5.0

11 Oct 10:03

Choose a tag to compare

New features

  • Convert Plugin: Add a config option to disable writing metadata to converted files.
  • Discogs Plugin Added support for featured artists. πŸ› (#6038)
  • Discogs Plugin New configuration option featured_string to change the default string used to join featured artists. The default string is Feat..
  • Discogs Plugin Support for artist_credit in Discogs tags. πŸ› (#3354)
  • Discogs Plugin Support for name variations and config options to specify where the variations are written. πŸ› (#3354)
  • Discogs Plugin: New config option strip_disambiguation to toggle stripping discogs numeric disambiguation on artist and label fields.
  • LastGenre Plugin: Add a --pretend option to preview genre changes without storing or writing them.

Bug fixes

  • Metadata source plugins: Fixed data source penalty calculation that was incorrectly applied during import matching. The source_weight configuration option has been renamed to data_source_mismatch_penalty to better reflect its purpose. πŸ› (#6066)
  • Chromaprint/Acoustid Plugin BPSync Plugin Fix plugin loading issue caused by an import of another beets.plugins.BeetsPlugin class. πŸ› (#6033)
  • Discogs Plugin Fixed inconsistency in stripping disambiguation from artists but not labels. πŸ› (#5366)
  • FromFilename Plugin: Fix πŸ› (#5218), improve the code (refactor regexps, allow for more cases, add some logging), add tests.
  • MusicBrainz Plugin Refresh flexible MusicBrainz metadata on reimport so format changes are applied. πŸ› (#6036)
  • Spotify Plugin Ensure spotifysync keeps popularity, ISRC, and related fields current even when audio features requests fail. πŸ› (#6061)
  • Spotify Plugin Fixed an issue where candidate lookup would not find matches due to query escaping (single vs double quotes).
  • Spotify Plugin Fixed an issue where track matching and lookups could return incorrect or misleading results when using the Spotify plugin. The problem occurred primarily when no album was provided or when the album field was an empty string. πŸ› (#5189)
  • Spotify Plugin Removed old and undocumented config options artist_field, album_field and track that were causing issues with track matching. πŸ› (#5189)

Other changes

  • Moved art.py utility module from beets into beetsplug namespace as it is not used in the core beets codebase. It can now be found in beetsplug._utils.
  • Moved vfs.py utility module from beets into beetsplug namespace as it is not used in the core beets codebase. It can now be found in beetsplug._utils.
  • When installing beets via git or locally the version string now reflects the current git branch and commit hash. πŸ› (#4448)
  • Autotagger Matching Options: match.distance_weights.source configuration has been renamed to match.distance_weights.data_source for consistency with the name of the field it refers to.
  • FAQ: Add check for musicbrainz plugin if auto-tagger can't find a match πŸ› (#6020)
  • Plugins: Clarify that musicbrainz must be mentioned if plugin list modified πŸ› (#6020)
  • Using the Auto-Tagger: Section on no matching release found, related to possibly disabled musicbrainz plugin πŸ› (#6020)
  • beets.metadata_plugin.MetadataSourcePlugin: Remove discogs specific disambiguation stripping.

For developers and plugin authors

  • Metadata source plugins are now registered globally when instantiated, which makes their handling slightly more efficient.
  • The track_distance() and album_distance() methods have been removed from MetadataSourcePlugin. Distance calculation for data source mismatches is now handled automatically by the core matching logic. This change simplifies the plugin architecture and fixes incorrect penalty calculations. πŸ› (#6066)
  • Typing improvements in beets/logging.py: getLogger now returns BeetsLogger when called with a name, or RootLogger when called without a name.