# Library（曲目库）

> **Platform support:** macOS — supported (developed & verified on this machine) · Windows — unverified (paths are cross-platform in the codebase, but no real-machine testing yet).

本地 SQLite 曲目库：**文件不动只引索**。第 9 个 ShadowRoom 插件。

[中文说明](README.zh-CN.md) · License: [AGPL-3.0-only](LICENSE)

## 工具（MCP，共 13 个）

| 工具 | 输入 | 说明 |
| --- | --- | --- |
| `scan_folder` | `path, recursive?` | 指纹增量入库/更新（指纹 = size + mtime + 首尾 64KB SHA-256） |
| `list_tracks` | `query?, bpm_min/max?, camelot?, tags?, limit?, offset?` | 多条件检索 |
| `track_detail` | `id` | 全字段（标签/BPM/调性/能量/64 桶峰值/crate） |
| `analyze_missing` | `limit?` | 缺 BPM/调性的交给本机 analysis 插件（detect_tempo/detect_key）补全 |
| `crate_create` | `name` | 创建 crate（同名校验，幂等） |
| `crate_list` | — | crate 列表（含每个 crate 的曲数） |
| `crate_add` | `crate_id, track_ids[]` | 按加入顺序追加；重复跳过 |
| `stats` | — | 总数 / 缺失分析数 / crate 数 / 库大小 |
| `import_history` | `source?: rekordbox\|serato\|auto` | **只读**导入 Rekordbox/Serato 的歌单与播放历史 → sets/history |
| `import_rekordbox_xml` | `path` | **只读**解析 Rekordbox `Export Collection in xml`（6.3.0+ 明文）→ sets |
| `learn_preferences` | — | 从 set 学偏好（ΔBPM / Camelot 走法 / 能量步进 / set 形状） |
| `preference_summary` | — | 中文一句话汇报偏好（无足够历史时回冷启动默认） |
| `forget_preferences` | `forget_history?` | 一键清空偏好（可选连 sets/history 一起清） |

## 表结构

- `tracks(id, path UNIQUE, title, artist, album, year, genre, duration_ms, sample_rate, bit_depth, bpm, key, camelot, energy, peaks_json, has_stems, fingerprint, added_at, analyzed_at)`
- `crates(id, name UNIQUE, created_at)`、`crate_tracks(crate_id, track_id, position)`

库文件：`~/Documents/ShadowRoom/_library/library.db`（`SHADOW_LIBRARY_DB` 可覆盖）。

## 只读承诺（重要）

- **不写用户的 Rekordbox / Serato 原库**。`import_history` 只读打开 Rekordbox `master.db`（路径
  由用户指定）；新版 `master.db` 是 SQLCipher 加密的，会立刻报错让用户知道；`import_rekordbox_xml`
  只解析用户导出的明文 XML。Serato 那边只读 `_Serato_/subcrates/` 下的二进制 crate 文件，
  不写任何东西到 Serato 自己的 `database V2`。
- **不挪动用户的音频文件**。`scan_folder` 只读取文件元数据 + 首尾 64KB 算指纹；`path UNIQUE` 是
  引用，文件该在哪还在哪。要搬家 / 删除曲目走文件管理器，不走本插件。
- **库文件 = 新建一份**，与 DJ 软件原库隔离。库文件在 `~/Documents/ShadowRoom/_library/library.db`，
  坏了 / 想重置直接删掉它；用户的 Rekordbox/Serato 不受影响。
- **历史与偏好可一键清空**：`forget_preferences(forget_history=true)` 把 `sets/history` 也清掉，
  回到冷启动默认。

## 设计取舍

见 [docs/internals.md](docs/internals.md)：指纹为什么取首尾 64KB、为什么扫描不解析 ID3、
camelot 换算表、missing 文件为什么不删行。

## 许可证

**AGPL-3.0-only**。