Tagger V1.1.0 本地音乐元数据管理工具

admin

Tagger  V1.1.0 本地音乐元数据管理工具

Tagger 是一个使用 Go 构建的本地音乐元数据管理工具。它把音乐文件当作事实源，在浏览器中读取和编辑 MP3、FLAC、WAV、Ogg Vorbis 和 Ogg Opus 的标签、歌词、封面和技术信息；需要补全时，再通过可插拔的数据源策略查询候选结果，并在逐字段审核后写回文件。

它不是音乐下载器，也不是面向公网的音乐流媒体服务。Tagger 的目标很简单：让个人音乐库的整理工作可解释、可恢复、可审计，并且在一台机器上用一个二进制文件启动。

为什么做 Tagger
音乐元数据整理通常同时面对三个问题：文件格式不统一、在线数据源不稳定、批量写入一旦出错就很难回退。Tagger 围绕这三个问题建立了几条明确的原则：

本地优先：音频文件留在你的音乐目录中，SQLite 只保存可重建的索引、任务和标签级历史。
先审核再写入：候选结果不是授权。标题、艺术家、专辑、歌词和封面都可以逐项选择，低置信度结果不会静默覆盖文件。
安全写入：写入前检查 revision，使用临时副本、写后重读校验和原子替换；每次成功修改都留下差异和历史。
策略隔离：MusicBrainz、LRCLIB、Apple/iTunes、网易云、酷我、酷狗和 LrcApi 都通过统一策略接口接入，单个来源失败不会阻断其他来源。

亮点一览

方向
Tagger 提供的能力

音乐文件
MP3、FLAC、WAV、Ogg Vorbis、Ogg Opus 的常用标签、原始 PropertyMap、时长、码率、采样率、位深、声道和嵌入封面

标签编辑
标题、艺术家、专辑、专辑艺术家、音轨/光盘号、年份、风格、歌词，以及注释、作曲家、指挥、作词家、版权、BPM、ISRC、MusicBrainz/AcoustID 标识

封面管理
读取、预览、上传、删除、远程候选预览；支持 JPEG/PNG/WebP 校验和 500×500 / 1000×1000 居中裁剪

数据补全
全部启用来源并行查询、跨源 Recording/Release 聚类、字段级智能选择、原始候选保留、歌词/封面独立采用和单曲重新匹配

批量任务
扫描、抓取、审核、写入和批量编辑使用 SQLite 持久化队列，支持进度、SSE 更新、取消、失败项重试和服务重启恢复

多曲库
启动时可以不提供音乐目录；设置页可添加、探测、切换多个本地曲库，目录以可折叠树状结构浏览

曲目浏览
服务端过滤/排序与游标分页，首屏默认 100 首，滚动追加；搜索、目录、递归、状态和格式条件不会把整座曲库加载到浏览器

页面恢复
同一 SPA 会话保留已加载页、筛选、跨页选择、当前曲目和滚动位置；整页刷新只恢复轻量筛选与滚动锚点，再按游标请求数据

批量安全
“全选”针对当前服务端结果集，批量补全/编辑/快照默认单次最多 2000 首；可在“设置 → 系统与安全”中调高，超限时提示先缩小范围

使用体验
跨页面全局播放器、浏览器路由、历史记录、主题/字体切换、无效封面默认留白、单用户可选访问令牌

部署
React 生产构建嵌入 Go 服务，运行时不需要 Node.js、FFmpeg 或系统 TagLib

主要界面

曲库：左侧曲库和目录树，顶部搜索/格式/状态/递归过滤，中间曲目列表，右侧 Inspector 查看和编辑元数据。
分页浏览：曲目查询由 Go 服务端执行，首次只取约 100 首；继续滚动会用不透明游标追加下一页，底部显示已加载数量和匹配总数。离开曲库去任务、历史、设置或审核页再返回时，列表和滚动位置会恢复。
审核抓取结果：本地值与“智能选择 / 原始数据源”候选对比，逐字段显示真实来源，支持全选/取消、候选切换、歌词/封面详情预览、封面写入尺寸和连续审核。
任务中心：扫描、抓取、写入和批量编辑的持久化状态；显示处理进度、失败原因、取消和重试入口。
历史：按曲目查看字段 diff、标签快照和封面 blob，先预览再恢复，恢复本身也会产生新的审计记录。
设置：曲库注册与切换、数据源启用/配置/测试、主题字体、历史保留策略、封面占位和安全写入开关。

界面预览

因此，请把 Tagger 当作会修改文件的工具使用，并在首次批量操作前备份音乐目录。安全写入和历史恢复降低了风险，但不能替代文件系统备份。

快速开始
构建要求

Go1.25.7或更高版本
Node.js20+和 npm（仅构建前端时需要）
运行已构建的二进制不需要 Node.js、FFmpeg 或外部 TagLib

构建并启动
make build
./dist/tagger \
  --music-dir /path/to/music \
  --data-dir /path/to/tagger-data
Copy code to clipboard

默认监听127.0.0.1:8080，打开

游客，如果您要查看本帖隐藏内容请回复

build，它会先编译 React，再把frontend/dist复制到web/dist，最后嵌入 Go 二进制。

如果不想在启动时指定音乐目录，也可以直接启动：

./dist/tagger --data-dir ./data
Copy code to clipboard

然后在设置页探测并添加音乐库。配置过的活动曲库会保存在 SQLite 中，后续启动时自动恢复；如果目录已经失效，Tagger 会保留旧索引并明确显示“未配置活动曲库”。

便携版
把 Tagger 的 Web 界面桌面程序利用AI打包成一个绿色免安装的 Portable便携版启动，不再单独使用浏览器打开，双击打开直接可用。

解压即用，双击 Tagger Portable.exe 启动，不写注册表、不安装到系统目录。
启动时不会出现命令提示符窗口。 程序以 GUI 子系统链接，Windows 不会为它分配控制台。
界面运行在程序内置的 WebView2 窗口中；缺少 WebView2 运行时时自动回退到默认浏览器。
所有运行数据（数据库、封面缓存、浏览器配置、日志）都保存在本文件夹的 data 目录中。
内置更新功能：先直连 GitHub，失败时依次使用 hk.gh-proxy.org、ghproxy.net 加速。

目录结构
Tagger Portable/
├── Tagger Portable.exe   主程序（含前端资源与图标）
├── 使用说明.md            本说明
└── data/                 运行时数据，首次启动自动创建
    ├── tagger.db          SQLite 数据库（曲库索引、任务、标签历史）
    ├── artwork-cache/     封面缓存
    ├── webview/           内置窗口的浏览器配置
    ├── logs/              运行日志
    │   └── tagger.log     日志文件（超过 2 MB 自动轮转，保留一份 .1 备份）
    └── tagger.lock        单实例锁
无控制台窗口
可执行文件通过链接器选项 -H windowsgui 链接，其 PE 子系统为

IMAGE_SUBSYSTEM_WINDOWS_GUI（2）而非控制台子系统（3）。这是双击启动时

不弹出命令提示符窗口的根本原因；scripts/build-portable.sh 会在打包前

校验该字段，回归时会直接让构建失败。

GUI 子系统没有附属的控制台，因此标准错误流在从资源管理器启动时不可用。

程序为此做了两处配套处理：

日志落盘：运行日志写入 data/logs/tagger.log。从终端启动时，日志同时

输出到终端与文件。
错误弹窗：导致程序退出的错误会弹出消息框（#32770 窗口类），用户

无需查看日志即可得知失败原因。重复启动同一文件夹时不会报错，而是把焦点

交给已经运行的实例窗口。

作者源码：

游客，如果您要查看本帖隐藏内容请回复

有Bug去此反馈

便携版下载：
Tagger Portable 1.1.0 win-x64.zip

游客，如果您要查看本帖隐藏内容请回复

密码:3yfz

---

下载链接：
GitHub：

游客，如果您要查看本帖隐藏内容请回复

GitHub：

游客，如果您要查看本帖隐藏内容请回复

GitHub：

游客，如果您要查看本帖隐藏内容请回复