storytag-tool 0.1.6

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

storytag-tool - 音乐专辑信息整理工具

安装

pip install storytag-tool

命令行参数

storytag [-h] [-s] [-c] [-o FILE] [-f FILE] [--dryrun] [--onebyone] [dir]

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

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

默认行为：不传任何参数时显示帮助信息。

使用模式

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

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

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

# 输出 CSV 格式
storytag -c "Y:/music" -o "Y:/music/albums.csv"

# 输出 MD 格式
storytag -c "Y:/music" -o "Y:/music/albums.md"

输出的 md 表格式：

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

CSV 格式：

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

• 有专辑：前2个文件中都有专辑名则显示"是"，否则"否"
• 建议专辑名：取前2个文件中第一个有专辑名的值，用户可手动修改
• 排除目录：自动跳过以 @eaDir 或 @ 开头的特殊目录（Synology NAS 索引目录）

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

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

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

# 执行修改
storytag -f "Y:/music/albums.csv"

模式3：交互模式

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

# 启用交互模式
storytag --onebyone "Y:/music/讲故事"

# 启用 MusicBrainz 搜索
storytag --onebyone -s "Y:/music/讲故事"

交互流程：

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

音乐文件格式

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

推荐工作流程

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

# 步骤1：检查
storytag -c "Y:/music" -o "Y:/music/albums.csv"

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

# 步骤3：预览
storytag -f "Y:/music/albums.csv" --dryrun

# 步骤4：执行
storytag -f "Y:/music/albums.csv"

注意事项

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