Release v2.14.12026-09-17
这次更新以问题修复为主。Discogs 插件现在会从 API 的 released 字段读取完整发行年月日,不再只剩年份,同时修正了导入时月份和日期被覆盖的问题。import 命令的交互式导入此前会忽略手动搜索(e)和手动输入 ID(i)给出的候选,现已恢复。Lyrics 插件的 LRC 解析支持三位小数的毫秒时间戳(如 [mm:ss.xxx]),带毫秒精度的同步歌词不再被误判而退回纯文本。跨磁盘移动临时文件新增可配置的 tempfile_prefix,解决硬编码前导点号在 Windows 和 Samba 共享上被当作隐藏文件的问题。路径格式前导字段留空再配合自定义 Replace 插件时,可能生成逃逸出曲库或 Convert 目标目录的绝对路径,如今渲染结果会剔除前导路径分隔符。另有 SQLite 改用 bytes 存储路径,以及压缩包导入测试在缺少依赖时自动跳过。
Release v2.14.02026-09-07
新功能:duplicate_action 新增 upgrade 选项——只有新副本码率更高时才替换重复曲目,新歌照常入库,专辑整体保持完整不拆开;list 命令加了 -l / --limit 限制结果条数;PlexUpdate 插件推出 beet plexupdate --auth,按 Plex 传统 PIN 流程登录并把访问令牌写入 token 文件,手动 token 配置随之废弃;交互式导入的专辑任务新增「重新扫描目录」,可在提示处暂停时清理重复与垃圾文件后直接重跑匹配,不必重启整个 import 命令。
修复方面:AURA 不再多值字段过滤崩溃,按字段排序也不再漏掉无值资源;BPD 的 search 命令在使用 any 字段时恢复正常;Convert 计算目标路径时开始考虑新格式;Deezer 修复了合辑识别、单曲搜索因查询混入字段过滤器而被降级成纯 artist 查询导致候选缺失,以及缺少 artist 字段时的 KeyError;Discogs 收到无效 JSON 会重试一次而非直接丢弃候选;Edit 让 itemfields 中的单曲字段在交互导入中仍可用;import 命令恢复了对 tar 与 7z 压缩包的导入。
Release v2.13.12026-07-29
修复了源码分发包遗漏内置 man 手册页的问题。此前通过源码分发方式安装的用户,安装后不会带上随项目一起打包的 man 页面,需要查阅手册时会扑空;现在这些文档会正常随包分发,打包安装与二进制安装的内容保持一致(#6882)。
Release v2.13.02026-07-27
beets 这版更新集中在插件与命令的细节打磨。Convert 新增 convert.refresh 与 --refresh,源文件比已转码文件更新时可强制重转;Edit 的导入编辑器把 albumfields 专辑字段以 YAML 头部呈现,与 itemfields 重复的字段不再逐轨显示。FetchArt 增加 fetchforasis,文件未被自动打标修改时也能去线上找封面,Tidal 插件新增的 coverarturl 正好供其取用。Lyrics 带来聚合多来源的 lrcmux 后端、--no-keep-synced 选项与 restdirectory 配置;LastGenre 新增 aliases,用内置正则统一曲风写法,默认开启。modify 支持 += 与 -=,可增删多值字段的单个值而不整体覆盖;ReplayGain 新增 metaflac 后端,用命令行工具为 FLAC 计算增益;Spotify 现在也认原生 URI。FtInTitle 的艺人改写提前到 MBSync 取元数据之前,修复了改写不生效的问题(#1153)。结构迁移前会自动备份数据库,可用 createbackupbeforemigrations(默认 yes)关闭。
Release v2.12.02026-06-22
新功能:convert 插件把 --force、--keep-new 落成配置项 force、keepnew;import 命令的 -M 现可覆盖 move: yes;歌词插件改为把带时间轴的 LRC 写入 ID3 的 SYLT 帧、纯文本写入 USLT,只支持 USLT 的播放器也能读到正常歌词;ListenBrainz 支持从导出文件导入收听历史;MusicBrainz 新增 aliasesascredits,别名作署名改为可选;badfiles 增加自动错误与警告动作;Tidal 导入时写入 tidaltrackid、tidalalbumpopularity 等灵活属性,并新增 beet tidalsync 刷新热度,旧库可用 beet modify datasource:tidal tidalalbumid='$mb_albumid' -a 迁移。
修复以稳定性为主:多线程导入合并重复专辑不再生成多余目录;歌词请求加入限速与指数退避,避免 429;mbsync/bpsync 在 import.from_scratch 下不再清空曲目元数据;fetchart 捕获 OSError,权限问题只记警告不再崩溃;另修 duplicates 输出与 --count 失效、fish 插件初始化报错、Musica.com 歌词抓取不全及 beet modify -a 的问题。
Release v2.11.02026-05-06
本次更新的重点在导入流程和几个插件的打磨。smartplaylist 的 splupdate 输出改成分层结构:默认只报每个歌单的曲目数,加 -v 才展开单曲明细;--pretend 改报「将更新 N 个歌单」,新增 --format 自定义曲目行格式,原 --pretend-paths 已移除,改用 --format='$path'。导入压缩包且设 move: yes 时,成功后会删掉源文件,只要包内有文件被跳过就保留。FromFilename 支持 track01.m4a 这类前缀解析曲目号。新增 Tidal 插件,可按 ID、ISRC、条码等批量取专辑与曲目元数据,初版已够日常使用。另支持副标题标签 TIT3。修复方面:Bad Files 尊重静音模式、Discogs 去掉重复客串艺人、重复导入不再堆积旧封面、并行时正确调用各元数据插件、多碟识别新增 cassette/digital media/vinyl、匹配界面不再显示零惩罚字段、original_date 生效后专辑年月日改用原始发行日、musixmatch 歌词撇号处理等。
Release v2.10.02026-04-19
本版把 beets 音乐库做成了可迁移结构:数据库里的曲目与专辑封面路径改为相对库存储,查询时仍兼容音乐目录下的绝对路径。升级后首次运行任意 beet 命令会自动完成迁移,务必先执行一次 beet version 再移动库目录,否则路径会失效。功能上,Inline 插件的内联字段新增 dbobj 对象;Discogs 导入 remixer、lyricist、composer、arranger 到对应的多值字段;Lyrics 增加 keepsynced 选项,开了 force 也跳过已有同步歌词的重新抓取;MusicBrainz 艺术家署名改用别名;多个元数据源插件改为并发查询,多插件同时启用时查找明显变快。修复方面,chroma 不再在未启用 MusicBrainz 插件时生成其候选,并恢复与 MusicBrainz Pseudo-Release 插件的兼容;导入时会把内嵌 MP3 流的 WAV 转成真正的 MP3,不再写入错误元数据,同时清掉专辑目录里的杂项;ListenBrainz 对临时失败自动重试;Web 插件修掉一处存储型 XSS。开发者注意:MusicBrainzAPI 现在返回下划线命名的规范化字段与 TypedDict 类型,直接读原始响应键的代码需要调整。
Release v2.9.02026-04-11
beets 现已正式支持 Python 3.14。功能上,AutoBPM 新增 force 配置并废弃 overwrite,Chromaprint 插件加入 chromasearch 命令按指纹搜库,FetchArt 支持 WebP 封面;import 命令改用 ffprobe 识别无扩展名的音频文件。查询新增 hascoverart 字段,可筛选带或不带内嵌封面的曲目。remixer、lyricist、composer、arranger 等人员信息改为多值字段存储,旧曲库自动迁移,MusicBrainz 插件也完整保留各自的 MBID。LastGenre 支持按艺人或全局配置流派忽略列表。修复方面:Deezer 解决 2.8.0 引入的崩溃回归与合辑艺人名误用本地化字符串的问题,Discogs 调整 style 与 genres 的写入规则,ReplayGain 写入时清除冲突标签,Smart Playlist 输出的可用列表改为字母排序并正确加引号,便于复制到 shell 使用。
Release v2.8.02026-03-28
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. :bug: (#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". :bug: (#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. :bug: (#6436)
- Fish Plugin: Fix AttributeError. :bug: (#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. :bug: (#6178) :bug: (#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 playcount to lastfmplaycount 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 lastfmplaycount='$playcount'.
- 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 vaname config for albumartistsort, albumartistssort, albumartistcredit, albumartists_credit, and albumartists on VA releases instead of hardcoded "Various Artists". :bug: (#6316)
- replace: Made drivesepreplace 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.metadataplugins.albumforid and beets.metadataplugins.trackforid 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.extradebug, 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. :bug: (#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.metadataplugins.SearchApiMetadataSourcePlugin.getsearchquerywithfilters and ~beets.metadataplugins.SearchApiMetadataSourcePlugin.getsearchresponse.
- Deprecate the Beatport Plugin and BPSync Plugin plugins. Beatport has retired the API these plugins rely on, making them non-functional. :bug: (#3862)
Release v2.7.12026-03-08
本次为纯修复版本:未安装可选依赖 langdetect 的用户此前会因相关测试直接报错,现在这类测试会自动跳过,不再阻断测试流程。对日常使用无功能影响,主要是改善了可选依赖缺失时的测试体验,也方便在最小化环境中跑完整测试套件。