dumpSiren

塞壬唱片（Monster Siren）本地曲库工具：把 monster-siren.hypergryph.com 的全量音乐元数据镜像进本地 SQLite，支持全文检索、apt 风格的按需下载，以及一个内嵌的网页控制台。

特性

• 全量镜像 — sync 把全部歌曲 / 专辑元数据（含音频 URL）拉进本地 SQLite，每次全量刷新，CDN URL 轮换、改名、专辑重排自动修正；完成后报告变化（+12/-3 songs · +2 albums）
• 双语全文检索 — FTS5 trigram 索引，中文按子串搜（"大决战" 命中 "毛茸茸大决战！"），按相关性排序
• apt 风格下载 — 目标可以是 CID、通配符（Sparkling*）或模糊名称；命中专辑自动展开整专；下载前打印合并去重的计划并确认
• FLAC 优先封装 — 有 ffmpeg 时转 FLAC 并写入标题 / 艺人 / 专辑 / 曲目号 / 歌词元数据和内嵌封面；没有 ffmpeg 时保存原始 wav + sidecar 元数据（JSON / .lrc / cover.jpg）
• 断点续传 — 下载中的 <file>.part + 控制文件，中断后自动 Range 续传，原子落盘
• 持久化默认值 — dumpsiren config 把 ffmpeg 路径 / 下载目录 / 数据库位置存进 ~/.config/dumpsiren/config.json，之后不用每次敲
• 短命令别名 — 每个命令都有别名：s sync、se search、dl download、st status、v verify、d dump、sv serve、c config
• 网页控制台 — 浏览全库（按专辑分组折叠）、搜索、一键 sync（实时进度）、在线播放（可拖进度条）、逐首下载、一键下载全部未下载、三格式导出
• 多格式导出 — 整个曲库可 dump 为 JSON / CSV / XML

安装

npx @gggxbbb/dumpsiren --help        # 免安装直接跑
# 或
npm install -g @gggxbbb/dumpsiren

要求 Node.js ≥ 20。FLAC 转换需要系统里有 ffmpeg（--ffmpeg <path> 显式指定或 PATH 自动检测）；没有也能用，自动回退到 wav + sidecar。

使用

# 同步元数据（全量刷新 ~900 首歌，约 20–30 秒，视网络而定），完成后显示新增/移除摘要
dumpsiren sync

# 检索（se 是 search 的别名，全部命令都有短别名：s/se/dl/st/v/d/sv/c）
dumpsiren search 大决战
dumpsiren se "Sparkling" --json --limit 10

# 下载（CID / 多个目标 / 通配符 / 模糊名 / 整专）
dumpsiren download 125029                    # 单曲 CID
dumpsiren dl 9371                            # 专辑 CID → 整专
dumpsiren dl "Sparkling*" "大决战"            # 通配符 + 模糊，合并计划
dumpsiren dl "大决战" -y                      # 跳过确认
dumpsiren dl "OST" --album --ffmpeg /usr/bin/ffmpeg
dumpsiren dl --all                           # 下载所有未下载的歌

# 记住默认值（之后 --dir / --ffmpeg / --db 都可以省略）
dumpsiren config set ffmpeg /usr/bin/ffmpeg
dumpsiren config set dir ~/Music/Siren
dumpsiren config get
dumpsiren config unset dir

# 网页控制台（默认 127.0.0.1:7878，--open 自动打开浏览器）
dumpsiren serve
dumpsiren sv --open

# 导出
dumpsiren dump --format json > library.json
dumpsiren d --format csv --album 8928 --out ost.csv

下载的文件布局：

siren-library/
├── 奇象巡展OST/
│   ├── 01 - Sparkling Days.flac   # 或 .wav + .json/.lrc sidecar
│   └── cover.jpg
└── _singles/                      # 无专辑的歌

开发

pnpm install
pnpm build        # tsc → dist/
pnpm test         # vitest（221 个测试）
pnpm typecheck

设计文档：

• CONTEXT.md — 领域词汇表（CID / Song / Album / Target）
• docs/adr/ — 架构决策记录（0001 SQLite、0002 全量刷新 sync、0003 无构建前端、0004 FLAC 优先、0005 CLI 表现层、0006 不实现 MV——上游 mvUrl 字段从未填充）
• .scratch/dumpsiren/spec.md — 完整规格（33 条 user story）
• .scratch/usability/spec.md — v0.4.0 易用性批次规格

License

MIT