am-downloader/README.md

AM Music Deduper

轻量级家庭 NAS 音乐库去重服务，面向 AllMusic/{username}/ 场景。

设计目标

• 本地 SQLite 元数据库
• L1 极速候选：文件大小 + 头/尾 64 KiB hash
• Exact Duplicate 最终使用完整 SHA-256 确认
• L2 使用 Chromaprint 做音频相似度候选
• duration 预过滤，降低 CPU/I/O
• 同一版本才允许自动择优
• loser 进入 .dedupe/trash/，默认保留 30 天
• 不使用软链接；物理去重使用 hard link
• inotify 增量处理 + 低优先级全量 reconcile
• 任何不确定或异常默认保留原文件

当前阶段

第一阶段先完成安全的扫描、SQLite 索引、L1/Exact 去重、trash/quarantine 和测试。 L2 Chromaprint 比对与生产 NAS 监听在后续阶段接入。

安全原则

1. 不修改正在写入的文件。
2. L1 命中必须再做完整 SHA-256 才能判定 exact duplicate。
3. 不根据歌名/歌手/专辑单独判重。
4. 不同格式或音频规格不会因为 metadata 相似而直接合并。
5. 自动处理前保留可恢复路径；失败不删除原文件。
6. 数据库只是索引，文件系统才是最终事实。

CLI 预期

am-deduper scan /music/AllMusic
am-deduper dedupe /music/AllMusic
am-deduper reconcile /music/AllMusic
am-deduper trash-prune /music/AllMusic --days 30