Metadata-Version: 2.4
Name: storytag-tool
Version: 0.1.6
Summary: 音乐专辑信息整理工具 - 批量管理音频文件标签
Author-email: musictag <sulegis@qq.com>
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: musicbrainzngs
Requires-Dist: mutagen
Provides-Extra: dev
Requires-Dist: hatch; extra == 'dev'
Description-Content-Type: text/markdown

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

## 安装

```bash
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 表供校对修订。

```bash
# 检查目录，输出到默认 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 格式：
```csv
本目录名,文件数,有专辑,建议专辑名,本目录所在路径
03. 神探 - 第三季,3,是,口袋3,Y:/music/03. 神探 - 第三季
03. 神探 - 第二季,1,否,-,Y:/music/03. 神探 - 第二季
```

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

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

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

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

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

### 模式3：交互模式

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

```bash
# 启用交互模式
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` 执行修改

```bash
# 步骤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` 和 `@` 开头的特殊索引目录
