Metadata-Version: 2.4
Name: storytag-tool
Version: 0.1.0
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

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

## 安装依赖

```bash
pip install musicbrainzngs mutagen pyreadline
```

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

## 配置

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

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

```bash
# 检查目录，输出到默认 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 表，对 `有专辑=否` 且 `建议专辑名` 有值的目录执行专辑名修改。

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

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

### 模式3：交互模式

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

```bash
# 默认模式（不使用 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` 执行修改

```bash
# 步骤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` 确认无误后再执行实际修改
- 写入前请确认，脚本**不会**自动覆盖已有专辑名的文件（除非用户确认）
