storytag-tool 0.1.0

音乐专辑信息整理工具 - 批量管理音频文件标签

musictag - 音乐专辑信息整理工具

安装依赖

pip install musicbrainzngs mutagen pyreadline

注意：Windows 上需要 pyreadline，Linux/Mac 不需要。

配置

编辑 musictag.py 顶部的配置区：

MUSIC_DIR = "/path/to/your/music"   # 音乐根目录（可被命令行参数覆盖）
AUDIO_EXTS = {".flac", ".mp3", ".ogg"}  # 支持的文件格式
DIR_ALIAS = {}                  # 可选：目录名别名映射，防止误匹配

命令行参数

musictag.py [-h] [-s] [-c] [-o FILE] [-f FILE] [--dryrun] [dir]

positional arguments:
  dir                   音乐目录路径（支持 SMB 挂载路径）

options:
  -h, --help            显示帮助
  -s, --search          启用 MusicBrainz 元数据搜索（默认关闭）
  -c, --check           检查缺少专辑名的目录，输出 md 表
  -o FILE, --output     -c 时指定 md 表输出路径（默认 result.md）
  -f FILE, --file       从 md 表读取并应用专辑名修改
  --dryrun              不实际执行文件修改，仅显示预期

使用模式

模式1：检查模式（生成 md 表）

扫描目录及其子目录，找出缺少专辑名的目录，输出到 md 表供校对修订。

# 检查目录，输出到默认 result.md
musictag.py -c "Y:/music"

# 指定输出路径
musictag.py -c "Y:/music" -o "Y:/music/albums.md"

输出的 md 表格式：

本目录名	文件数	有专辑	建议专辑名	本目录所在路径
03. 口袋神探 - 第三季	3	是	口袋3	Y:/music/03. 口袋神探 - 第三季
03. 口袋神探 - 第二季	1	否	-	Y:/music/03. 口袋神探 - 第二季

• 有专辑：前2个文件中都有专辑名则显示"是"，否则"否"
• 建议专辑名：取前2个文件中第一个有专辑名的值，用户可手动修改

模式2：应用模式（从 md 表修改）

读取 md 表，对 有专辑=否 且 建议专辑名 有值的目录执行专辑名修改。

# 预览修改（不实际写入）
musictag.py -f "Y:/music/albums.md" --dryrun

# 执行修改
musictag.py -f "Y:/music/albums.md"

模式3：交互模式

逐一处理每个子目录，手动指定或确认专辑名。

# 默认模式（不使用 MusicBrainz）
musictag.py "Y:/music/凯叔讲故事"

# 启用 MusicBrainz 搜索
musictag.py -s "Y:/music/凯叔讲故事"

交互流程：

1. 显示目录信息和当前标签
2. 提示输入专辑名（自动从目录名提取建议值）
3. 用户回车确认或输入新名称
4. 确认后写入标签

音乐文件格式

支持：.flac .mp3 .ogg .opus .m4a

推荐工作流程

1. 先用 -c 检查整个音乐库，生成 md 表
2. 编辑 md 表，修正 建议专辑名 列
3. 用 -f --dryrun 预览修改
4. 确认无误后用 -f 执行修改

# 步骤1：检查
musictag.py -c "Y:/music" -o "Y:/music/albums.md"

# 步骤2：编辑 albums.md，修改建议专辑名

# 步骤3：预览
musictag.py -f "Y:/music/albums.md" --dryrun

# 步骤4：执行
musictag.py -f "Y:/music/albums.md"

注意事项

• MusicBrainz 搜索有 1 秒/请求 rate limit，每分钟约 1 次，大量操作请使用 -c / -f 模式
• -f 模式会跳过 有专辑=是 或 建议专辑名=- 的目录
• 建议先用 --dryrun 确认无误后再执行实际修改
• 写入前请确认，脚本不会自动覆盖已有专辑名的文件（除非用户确认）