beets thumbnails 插件:为专辑文件夹生成 freedesktop 兼容缩略图
beets thumbnails 插件:为专辑文件夹生成 freedesktop 兼容缩略图
beets 的 thumbnails 插件会在每个专辑文件夹中依据封面图生成标准缩略图,让 Nautilus、Thunar 等 freedesktop.org 规范兼容的文件管理器直接以专辑封面作为文件夹图标。本文基于 docs/plugins/thumbnails.rst 文档,结合 beetsplug/thumbnails.py 源码与 test/plugins/test_thumbnails.py 测试用例,完整讲解安装、配置、命令行用法与底层实现机制。
插件定位与适用环境
thumbnails 插件的核心职责是:为专辑文件夹创建带封面图的缩略图。它遵循 freedesktop.org 的 Thumbnail Managing Standard(缩略图管理规范),因此只对遵守该规范的桌面环境有效,典型代表是 GNOME 的 Nautilus 和 XFCE 的 Thunar;由于缩略图缓存目录基于 XDG 规范组织,该插件 仅支持 POSIX 系统(Linux/BSD/macOS 一类的类 Unix 平台)。
插件模块头部的 docstring 明确写明了这一点(beetsplug/thumbnails.py):
"""Create freedesktop.org-compliant thumbnails for album folders
This plugin is POSIX-only.
Spec: standards.freedesktop.org/thumbnail-spec/latest/index.html
"""
安装与启用
thumbnails 插件本身不执行封面抓取,它消费的是专辑已有的封面图(album.artpath),因此使用前必须同时启用 fetchart 插件来为专辑获取封面。安装 beets 时也需一并安装两个插件的可选依赖:
pip install "beets[fetchart,thumbnails]"
然后在 beets 配置文件的 plugins 列表中加入二者:
plugins: fetchart thumbnails
由于插件需要把封面图缩放成标准尺寸,本机还必须具备图片缩放能力,二选一:
- ImageMagick(通过
magick/convert命令调用); - Pillow(PIL)。
缩放能力由 beets 的图片抽象层 beets/util/artresizer.py 统一提供:它会依次探测 ImageMagick 与 PIL 两个后端,若两者都不可用则退化为远程缩放代理(WEBPROXY)。从源码看,thumbnails 插件在初始化时会检查 ArtResizer.shared.local(beetsplug/thumbnails.py),即仅接受本地缩放后端;若探测到的是 WEBPROXY 代理模式,会打印警告 “No local image resizing capabilities, cannot generate thumbnails” 并拒绝工作。
配置项详解
在配置文件中建立一个 thumbnails 小节即可配置该插件,可用选项如下:
| 选项 | 含义 | 默认值 |
|---|---|---|
auto |
是否在导入时(更准确地说,是每次专辑封面被设置后)自动生成缩略图 | yes |
force |
即使已存在看起来合适的缩略图(比封面图更新)也强制重新生成 | no |
dolphin |
生成 Dolphin(KDE 文件管理器)兼容的缩略图。Dolphin 不遵循 freedesktop.org 的缩略图标准,此功能用于取代已废弃的 freedesktop 插件 |
no |
这三项默认值与源码中插件初始化时注册的默认配置完全一致(beetsplug/thumbnails.py):
self.config.add({"auto": True, "force": False, "dolphin": False})
auto:随封面设置的自动生成
当 auto 为 yes 时,插件在初始化阶段注册 art_set 事件监听器(beetsplug/thumbnails.py):
if self.config["auto"] and self._check_local_ok():
self.register_listener("art_set", self.process_album)
art_set 事件由 beets 在专辑封面写入完成后发送。查看 beets/library/models.py 中 Album.set_art 的实现可以看到,封面被复制/移动到目标位置并更新 artpath 字段后,会执行 plugins.send("art_set", album=self)。也就是说,无论封面是 fetchart 在导入时抓取的,还是后来手动设置的,只要封面发生变化,缩略图都会自动同步更新。
注意 auto 仅控制事件驱动的自动生成;手动运行 thumbnails 命令始终可用,不受该选项影响。
force:跳过“看起来没问题”的缩略图
插件在生成缩略图前会做一次新鲜度检查:如果目标缩略图已存在,且其修改时间晚于封面图的修改时间,则认为现有缩略图足够新、无需重新生成(beetsplug/thumbnails.py):
if (
os.path.exists(syspath(target))
and os.stat(syspath(target)).st_mtime
> os.stat(syspath(artpath)).st_mtime
):
if self.config["force"]:
...
else:
return False
开启 force: yes 后,即使已有足够新的缩略图也会强制重建。命令行 -f/--force 开关可对该选项做单次覆盖(见下文“使用”一节)。测试用例 test/plugins/test_thumbnails.py 验证了这一行为:缩略图更新时 resize 不会被调用,而 force 开启后 resize 必定执行。
dolphin:KDE Dolphin 兼容模式
KDE 的 Dolphin 文件管理器不遵循 freedesktop.org 的缩略图标准,而是通过专辑目录下的 .directory 文件指定图标。dolphin: yes 会为每个专辑目录生成这样一个文件(beetsplug/thumbnails.py):
outfilename = os.path.join(album_path, b".directory")
if os.path.exists(syspath(outfilename)):
return
artfile = os.path.split(artpath)[1]
with open(syspath(outfilename), "w") as f:
f.write("[Desktop Entry]\n")
f.write(f"Icon=./{artfile.decode('utf-8')}")
f.close()
生成的 .directory 文件内容形如:
[Desktop Entry]
Icon=./cover.jpg
Icon 指向专辑目录内的封面文件,Dolphin 便以此作为文件夹图标。测试 test/plugins/test_thumbnails.py 同时验证了一个已知限制:如果 .directory 已存在,插件不会重写它,即使封面文件已经更换——注释中直白地写着 “yup that's a big limitation”。
该功能取代了旧的 freedesktop 插件。查看 beetsplug/freedesktop.py 可以看到,freedesktop 插件现已退化为一个仅打印引导信息的占位命令,提示用户改用 thumbnails --dolphin,对应文档见 docs/plugins/freedesktop.rst。
使用:thumbnails 命令
thumbnails 插件注册了一个同名子命令(beetsplug/thumbnails.py),可为匹配查询条件的专辑批量生成缩略图:
beet thumbnails [QUERY...]
其中 QUERY 使用 beets 标准的查询语法(详见 docs/reference/query.rst),例如:
# 为所有专辑生成缩略图
beet thumbnails
# 只为指定艺术家的专辑生成缩略图
beet thumbnails artist:Radiohead
# 为 2010 年之后发行的专辑生成缩略图
beet thumbnails year:2010..
命令支持两个开关,与配置项一一对应,可临时覆盖配置文件中的默认值:
| 参数 | 作用 |
|---|---|
-f, --force |
强制重新生成那些“看起来没问题”(已存在且足够新)的缩略图 |
--dolphin |
同时生成 Dolphin(KDE)兼容的 .directory 缩略图信息 |
命令执行时,process_query 会先把命令行参数写回插件配置(self.config.set_args(opts)),然后对 lib.albums(args) 查询出的每个专辑依次调用 process_album(beetsplug/thumbnails.py)。测试 test/plugins/test_thumbnails.py 验证了查询结果中的每个专辑都会被逐个处理。
执行流程
单个专辑的处理流程(process_album,beetsplug/thumbnails.py)大致如下:
- 读取
album.artpath;若专辑没有封面,打印警告并跳过; - 若开启
dolphin,先写.directory文件; - 用
ArtResizer.shared.get_size读取封面尺寸;读取失败则跳过; - 若封面较长边 ≥ 256 像素,生成 256×256 的
large缩略图;同时(无论大小)生成 128×128 的normal缩略图。
也就是说,较小的封面只生成 128px 缩略图,较大的封面则 128px 与 256px 各一张。这一分支逻辑由测试用例明确锁定(test/plugins/test_thumbnails.py):200×200 的封面只调用 make_cover_thumbnail(album, artpath, 128, NORMAL_DIR),而 500×500 的封面会同时调用 128 和 256 两次。
底层实现:目录、文件名与元数据
缩略图缓存目录
缩略图遵循 XDG 规范存放在用户缓存目录下,由源码顶部常量定义(beetsplug/thumbnails.py):
BASE_DIR = os.path.join(BaseDirectory.xdg_cache_home, "thumbnails")
NORMAL_DIR = bytestring_path(os.path.join(BASE_DIR, "normal"))
LARGE_DIR = bytestring_path(os.path.join(BASE_DIR, "large"))
即缩略图分别写入 ~/.cache/thumbnails/normal/ 与 ~/.cache/thumbnails/large/,这正是 freedesktop 规范规定的两个标准尺寸目录(normal 为 128px,large 为 256px)。插件初始化时若目录不存在会自动创建(beetsplug/thumbnails.py),测试 test/plugins/test_thumbnails.py 对缺失目录的自动创建做了专门验证。
文件名:URI 的 MD5
缩略图文件名并非随机生成,而是专辑目录 URI 的 MD5 哈希,这正是文件管理器定位缩略图的依据——同一目录在任何程序生成的缩略图都能被复用(beetsplug/thumbnails.py):
def thumbnail_file_name(self, path: bytes) -> bytes:
uri = self.get_uri(path)
hash_ = md5(uri.encode("utf-8")).hexdigest()
return bytestring_path(f"{hash_}.png")
例如测试中 file:///my/uri 的 MD5 对应文件名 9488f5797fbe12ffb316d607dfd93d04.png(test/plugins/test_thumbnails.py)。
URI 的计算有两种途径,插件在 _check_local_ok 中探测并选择(beetsplug/thumbnails.py):
- GIO:优先通过
ctypes直接调用系统 GIO 库(g_file_new_for_path+g_file_get_uri)获取规范 URI,能正确处理非 ASCII 字符的百分号编码(如韩文目录被编码为%EC%8B%B8%EC%9D%B4,见 test/plugins/test_thumbnails.py); - PathlibURI:GIO 不可用时退化为 Python 标准库
pathlib.PurePosixPath.as_uri()。
写入规范要求的元数据
freedesktop 规范要求缩略图 PNG 内嵌两个元数据键,以便文件管理器校验缩略图是否过期(beetsplug/thumbnails.py):
metadata = {
"Thumb::URI": self.get_uri(artpath),
"Thumb::MTime": str(mtime),
}
其中 Thumb::URI 是封面图自身的 URI,Thumb::MTime 是封面图的修改时间戳。写入由 ArtResizer.shared.write_metadata 完成——ImageMagick 后端用 -set 参数、PIL 后端则通过 PngImagePlugin.PngInfo.add_text 写入 PNG 文本块(见 beets/util/artresizer.py 与 beets/util/artresizer.py)。测试 test/plugins/test_thumbnails.py 精确断言了这两个元数据的键值。
正因如此,插件在 _check_local_ok 中还会检查 ArtResizer.shared.can_write_metadata;若缩放后端意外地不能写图片元数据,会直接抛出 RuntimeError(beetsplug/thumbnails.py)。
生成流程收尾时,resize 先输出到临时文件,写入元数据后再用 shutil.move 原子地移动到目标文件名(beetsplug/thumbnails.py),避免写入一半的缩略图被文件管理器读到。
依赖与限制小结
- 平台限制:仅 POSIX;依赖 XDG 缓存目录约定,Windows 不受支持。
- 前置插件:需与
fetchart配合,确保专辑拥有封面。 - 图片依赖:本机必须安装 ImageMagick 或 Pillow 之一;纯远程缩放代理(WEBPROXY)模式下插件拒绝工作。
dolphin模式已知限制:.directory文件一旦生成就不会随封面更换而更新(源码注释与测试均明确此点)。- 更新策略:默认依据“缩略图修改时间晚于封面图”判断是否过期,
force可强制重建;封面每次被设置(art_set事件)时自动触发。
通过以上配置与机制,thumbnails 让 beets 管理的音乐库在主流 Linux 文件管理器中呈现出整齐划一的专辑封面图标,且严格遵循 freedesktop 规范,无需任何手工干预。