sudravirodhin/dadtool-importer

# dadtool — *Dead as Disco* 的离线节拍同步与歌曲导入工具 这是一个 Windows CLI 工具，能够**离线**分析曲目的节拍，并将同步数据 **直接写入 *Dead as Disco* 的单曲保存元数据中** —— 因此你再也不必使用 游戏内的敲击校准工具。它还可以端到端地导入歌曲（转码 → 自动命名 → 响度标准化 → 节拍同步），让游戏内的导入器变得可有可无。 离线生成的网格比手动敲击精确大约 **2 倍**，并且在一整首歌中都不会出现漂移。 ## 功能说明 - **直接写入节拍同步数据** 到每首歌曲的 `Meta.json` 中 —— 包括节拍、节拍偏移量、 变速段落以及静音修剪 —— 替代手动敲击校准。 - **端到端导入歌曲：** 将任何音频转码为游戏所需的 48 kHz Ogg Vorbis， 构建游戏所需的歌曲文件夹，并写入同步好的 `Meta.json`。 - **准确追踪节拍**，使用 transformer 节拍追踪器（beat_this），包括真正的 强拍、分段的节拍变化，以及自动的半拍偏移校正。 - **为歌曲命名**，基于 AcoustID 音频指纹（通过 MusicBrainz 获取规范标题/艺术家）， 并支持回退到文件标签 + 文件名。 - **响度标准化** 至统一的 −14 LUFS。 - **作为守护进程运行**，可自动导入任何放入指定文件夹的内容。 - **安全第一：** 拒绝在游戏运行时操作，带有时间戳的完整备份、版本/格式 校验门控、通过重新读取进行验证，以及针对任何错误提供的单曲覆盖文件。 ## 环境要求 - **Windows**（使用 Windows 存档路径 + 进程检查）和 **Python 3.12**。 - 为节拍追踪器准备**独立的 conda/Miniforge 环境** —— `beat_this` 需要 PyTorch （仅使用 CPU 即可）。 - 通过 `imageio-ffmpeg` **内置 ffmpeg**；无需在系统中单独安装。 - *可选，用于自动命名：* **AcoustID API key** 和 **Chromaprint `fpcalc`** 可执行文件。 ## 初始设置 ``` # 1. main 环境 python -m venv .venv .\.venv\Scripts\pip install -r requirements.txt # 2. 在隔离的 conda env 中的 beat tracker（CPU torch 即可） conda create -n dad-beat python=3.11 conda activate dad-beat pip install beat_this torch soundfile # 3. config — 复制 example 并填入你的路径 copy dad_config.example.json dad_config.json ``` 然后编辑 `dad_config.json`：`saved_dir`，游戏 exe 路径，`beat_this_python`（即 `dad-beat` 解释器），以及可选的 `acoustid_api_key` 和 `fpcalc_path`。该文件已被 git-ignore（其中包含本机路径 + 你的 API key）。游戏目录**仅**在 `dadtool/paths.py` 中，通过 `dad_config.json` 或 `DAD_SAVED_DIR` 环境变量进行解析。 ## 用法 通过 venv（或内置的 `dad.cmd` / `watch.cmd` 启动器）运行： ``` .\.venv\Scripts\python.exe -m dadtool.cli ``` | 命令 | 功能说明 | |---|---| | `status` | 解析路径、游戏运行状态、当前游戏版本 | | `revalidate` | 在写入前检查游戏构建版本 + 格式金丝雀 | | `analyze ""` | 打印 ImportedSongs 名称或音频文件的分析 JSON | | `preview ""` | 将节拍音轨渲染为 WAV 到 `previews/` 以便试听同步效果 | | `write ""` | 分析 + 写入单首歌曲（`--dry-run`, `--tempo/--offset/--start`） | | `batch` | 分析 + 写入所有已导入的歌曲（`--dry-run`, `--force`, `--limit N`） | | `import-song ` | 从源文件构建完整的 ImportedSongs 条目 | | `list` | 列出所有已导入的歌曲及其索引（即 `remove --index` 的选择器） | | `remove` | 按名称、`--index 2,4,6-9`、`--match '*pattern*'` 或 `--all` 批量删除歌曲 | | `playlist list` | 列出播放列表及其包含的歌曲 | | `playlist create "" ` | 根据歌曲名称匹配创建播放列表 | | `playlist auto` | 为包含 3 首以上歌曲的专辑自动创建播放列表（`--min N`, `--dry-run`） | | `playlist delete ""` | 删除播放列表 | | `challenge plan ""` | 预览程序化的波次/难度规划（不写入） | | `challenge generate ""` | 生成并写入挑战（`--difficulty`, `--boss`/`--no-boss`, `--arena`） | | `challenge sync` | 为整个曲库生成自动挑战（`--purge`, `--dry-run`） | | `watch` | 守护进程：自动导入放入 `audio/pending/` 的音频（`--once`, `--interval N`） | | `normalize` | 将所有 `Audio.ogg` 进行 LUFS 标准化至 −14（`--force`） | | `rename` | 通过 AcoustID 为所有歌曲设置歌曲名称/艺术家（`--dry-run`） | | `relabel` | 将所有歌曲名称重写为 `Artist - Title`，使游戏内列表按艺术家排序（`--dry-run`） | | `restore` | 在游戏补丁清除元数据后重新写入缓存的元数据 | | `collect` / `ingest` | 将源音频归档至 `audio/processed/` | | `snapshot ` / `diff ` | 对存档目录树进行哈希清单记录并进行 diff（用于格式适配工作） | **单曲覆盖** 位于 `overrides.json` 中，以精确的 ImportedSongs 文件夹名称作为键名： 可固定 `tempo`、`beatOffset` (ms)、`startSongOffset`/`endSongOffset` (s)、 `customTempoSections`，或设为 `skip: true`。由 `batch` 和 `write` 应用。 **管理曲库：** `list` 会打印每首歌曲及其索引；`remove` 可以批量清除它们 —— `remove --index 2,4,6-9`、`remove --match '*Sleep Token*'` 或 `remove --all`。 它会预览选中的内容，**首先备份整个存档文件夹**，在游戏运行时拒绝执行，并在下次重启时生效。 添加 `--dry-run` 仅预览，添加 `--yes` 跳过提示，或添加 `--with-source` 同时删除 `audio/processed/` 中的源文件。 **典型流程：** 将文件放入 `audio/pending/` → `watch`（或 `import-song `） 进行转码、分析、写入条目，并将源文件归档至 `audio/processed/` → **重启游戏** 即可看到。 使用 `preview` 试听任何标记过的内容；在 `overrides.json` 中固定修正值。游戏打补丁后：先 `revalidate`，然后再 `restore`。 ## 工作原理

存档格式 —— 我们写入的内容及位置

每首导入的歌曲都是 `%LOCALAPPDATA%\Pagoda\Saved\ImportedSongs\\` 下的一个文件夹， 其中包含 **`Meta.json`**（纯 JSON —— 无校验和或加密）和 **`Audio.ogg`** （48 kHz Ogg Vorbis）。节拍同步数据存在于 `Meta.json` 中，而**不是** GVAS `.sav` 文件中。核心字段： | 字段 | 含义 | |---|---| | `tempo` | BPM (float32；整数存为 `int`，与游戏一致) | | `beatOffset` | 网格锚点，单位为**毫秒** (int) | | `customTempoSections` | `[{tempo, startAbsoluteTime(seconds)}]` —— 随时间变化的节拍 | | `startSongOffset` / `endSongOffset` | 从开头/结尾修剪掉的秒数 | | `uniqueId` / `seed` | uint32 id | | `songName` / `performedBy` | 显示名称 + 鸣谢 | | `originalAudioFileHash` / `originalAudioFilePath` | 源文件的 MD5 + 路径 | 对于纯 ASCII 名称，编码采用 UTF-8；对于非 ASCII 名称，采用 **UTF-16LE + BOM**； 换行符为 CRLF，缩进使用 tab。完整的逆向工程规范见 **[FORMAT.md](FORMAT.md)**。

分析流水线 —— 节拍 → 节拍 → 相位

1. **beat_this** (CPJKU, 2024 —— 一款 SOTA transformer 追踪器) 可生成节拍**及真正的 强拍**，在隔离的 conda 环境（`scripts/beat_this_worker.py`）中作为子进程运行。 进程内回退方案使用 `librosa`。 2. 节拍和相位来自于对节拍序列的**抗间隙线性拟合**： 节拍间隔被四舍五入到整数网格步长，因此追踪器漏掉或多出的节拍不会影响斜率。 这产生了能在整首歌中保持不漂移的节拍和强拍相位（在干净的音轨上残差约为 11–25 ms）。 3. 分析结果包含检测到的/最终的 BPM、节拍乘数、第一个强拍、 节拍段落、由残差计算出的置信度分数，以及供审查的标志。 节拍轨道会根据音频哈希进行缓存，因此重新分析速度非常快。

节拍下限与分段加倍

游戏在 ≥120 BPM 时体验最佳，因此较慢的检测节拍会乘以 达到 120 所需的**最小整数** (90→180, 100→200)。由于是整数倍， 每个原始节拍依然是节拍 —— 网格保持对齐。 对于包含变速段落的歌曲，每个段落**独立**进行下限处理：追踪器在快歌中捕捉到的半拍延展 （例如 175-BPM 歌曲中 87-BPM 的桥段）会被加倍到 ~174，使其不会显得太拖沓，而已经在合适范围内的段落则保持不变。 单一的整曲乘数无法做到这一点 —— 快歌的全局节拍已经 ≥120 (×1)， 因此其慢速段落永远不会被提升。提升可能会将段落推高至 200 BPM 以上； 这是有意为之（偏慢的位移比偏快的更糟）。

段落检测与噪声防护

段落来自于**漂移准则分割**：局部节拍曲线被分段，并且仅当分段网格 将相较于单一节拍的最严重节拍漂移减少了 15 ms 以上时，才会保留分段网格。 孤立的单一区段尖峰会被拒绝。节奏稳定的歌曲保持单一节拍；真正有变化的 歌曲则会获得精确的多段网格（这*减少*了 漂移 —— 这是一个特性，而不是问题）。 **噪声防护：** 如果即使是分段网格仍然严重漂移 (>400 ms) *并且* 相较于单一节拍几乎没有改善 (<20%)，则丢弃这些段落，歌曲回退到稳健的全局节拍。 这种情况意味着追踪器放*错*了节拍位置（例如稀疏打击乐上的密集人声）， 而所谓的“段落”只是在拟合噪声，而不是真正的节拍变化。值得注意的是，仅凭置信度分数**无法**区分好的段落和坏的段落 —— 这是由*改善比例*决定的。

端到端导入与启动缓存问题

游戏通过扫描 `ImportedSongs\` 并在**启动时**读取每个 `Meta.json` 来发现歌曲 —— GVAS 存档中没有任何特定于歌曲的内容。因此该工具会自行 构建整个条目：将源文件转码为 48 kHz Ogg Vorbis（使用内置的 ffmpeg —— 因为在 Windows 上 `librosa`/`soundfile` 解码源 MP3 会发生堆栈溢出）， 生成 `uniqueId`/`seed`，进行分析，并写入 `Meta.json`。 歌曲列表在**启动时被缓存**并在整个会话期间保留（已通过测试确认）： 在会话期间没有任何东西会重新读取该文件夹，“Continue”不会重新加载它， 游戏内的“Add My Music”只会追加它自己的那一首歌曲。因此，外部添加的歌曲和编辑只有在 **完全重启游戏后**才会显示。

命名、响度与安全门控

- **命名：** AcoustID 指纹会通过 MusicBrainz 进行查询，并在指纹记录中进行 **多数投票**（避免虚假的单一匹配），如果失败则回退到嵌入式标签 (`mutagen`)，然后是清洗过的文件名。游戏内的**歌曲名称**会被写入为 `Artist - Title`（艺术家字段留空），这样按名称进行字典排序的菜单 就能按艺术家分组；`relabel` 会将此应用于整个曲库新导入的歌曲会自动应用此规则。 - **响度：** ffmpeg 两遍 `loudnorm` 处理至 −14 LUFS，具有幂等性（它会首先进行测量，并 跳过已经达到目标响度的歌曲）。 - **写入前的安全门控：** 如果游戏正在运行则拒绝操作 (`Pagoda.exe` / `PagodaSteam-Win64-Shipping.exe`)；对整个 Saved 目录进行带时间戳的完整备份； 根据记录的基线进行游戏构建检查（如果发生改变则要求重新验证）； 对已知歌曲进行格式金丝雀测试；并通过重新读取进行验证。

播放列表 (.bjpl)

播放列表位于 `Saved\Playlists\Playlist_.bjpl` —— 这是 Unreal 的**二进制属性 格式**，每个播放列表对应一个文件（已逆向工程并通过完美的字节级往返测试验证； 编解码器位于 `dadtool/playlist.py` 中）。每个文件通过包裹在瞬时对象路径中（其实例编号 在不同会话间是稳定的）的 ImportedSongs 文件夹名称来引用歌曲，并带有一个尾部映射表，将每首歌曲的 **`uniqueId`** （我们已经写入 `Meta.json` 中的值）映射到其顺序。游戏会根据该 uniqueId 表 填充播放列表 —— 只要 id 正确，歌曲就会出现。`playlist auto` 会从嵌入式标签中 读取每首歌曲的**专辑**，并为每张包含 3 首以上歌曲的专辑写入一个播放列表。

程序化挑战

游戏的自定义战斗编辑器将挑战以纯 JSON 形式存储在 `Saved\UserChallenges\\Meta.json` 中（包含嵌入式歌曲同步 + `enemyWaves` + `objectives` + `modAssets` + arena）。`dadtool` 会根据歌曲程序化生成它们： - 光谱**强度分布**决定了每个波次的规模；波次数量有上限（~8.5 秒/波次）， 这样长歌曲会拥有更大的波次，而不是几十个微小的波次，此外还有 2 个波次的结尾缓冲。 - **通关时间模型**（通过试玩校准）：普通敌人 ×1，Bouncer ×2.5，boss ×5， 根据节拍进行缩放。游戏的击倒令牌系统会自动调节屏幕上的压力，因此 慷慨的超量配置依然能保持紧张但公平。 - **基于氛围：** 强度/节拍会选择 **arena**、**modifiers**（例如 DoubleTime、 EnemyIncreasedHealth）以及有多少 **bosses** 叠加在终局 —— 残暴的歌曲会获得 极其夸张的 boss 堆叠，这是有意设计的。 - 目标是 `WinOnSongEnd`（撑过整首歌）。敌人/arena/mod 标签是从 打包的游戏内容中提取到 `challenge_vocab.json` 中的。 `challenge generate` 会写入一个挑战；`challenge sync --purge` 会重新生成整个曲库； 如果在 `dad_config.json` 中设置了 `auto_generate_challenge: true`，每首新导入的歌曲都会自动获得一个挑战。

Windows 坑（来之不易的经验）

- 每次调用 ffmpeg / beat worker 的子进程时都会传入 `encoding="utf-8", errors="replace"` —— 当文件名包含非 ASCII（例如日语）字符时，默认的 cp1252 读取线程在遇到 UTF-8 stderr 时会崩溃，并默默地 不返回任何内容。 - PowerShell 会破坏 `Test-Path`/`Join-Path` 中的 `[括号]` 路径，并会向原生 exe 传递乱码的非 ASCII 参数；该工具通过完全交由 Python 处理来规避这两个问题。 - `Meta.json` 的编码是由**内容**决定的：任何非 ASCII 字符 → UTF-16LE + BOM （游戏自身的惯例）；纯 ASCII → UTF-8。一个以无 BOM 的 UTF-8 保存的非 ASCII 名称 在游戏内会被误读为 ANSI 代码页 (`Don’t` → `Don’t`)。

## 项目布局 ``` dadtool/ the package cli.py command-line entry point paths.py resolves the game dir (the ONLY place the game path lives) tracker.py beat_this subprocess + librosa fallback + beat cache analyzer.py tempo/phase line-fit, sections, tempo floor, noise guard writer.py AnalysisResult -> Meta.json, with the safety gates importer.py transcode + fabricate a full ImportedSongs entry daemon.py the watch loop metadata.py AcoustID + tag naming loudness.py two-pass loudnorm playlist.py .bjpl playlist codec + album auto-grouping challenge.py procedural Challenge generator (spectral -> waves/bosses/mods/arena) lyrics.py synced-lyrics (.lrc) generator for the companion Marquee mod (experimental) meta / snapshot / backup / overrides / sources / gamestate scripts/ beat_this_worker.py beat tracker — runs inside the isolated conda env lrcgen_worker.py lyrics ASR (faster-whisper) — runs inside an isolated venv (experimental) FORMAT.md reverse-engineered save format (source of truth for writes) dad_config.example.json copy to dad_config.json and fill in overrides.json per-song pinned fixes ``` ## 注意事项 - 逆向工程是基于单个抢先体验版本进行的；游戏补丁可能会改变格式。 `revalidate` 会检查这一点，而 `restore` 会在元数据被清除后重新应用同步。 - 节拍追踪器决定了准确度的上限。罕见的追踪错误会被标记出来（低置信度）， 以便使用 `preview` 和单曲覆盖 —— 并非所有事物都有声学信号（例如 “这应该按双倍时间绘制吗？”是一个图谱制作口味问题，而不包含在音频中）。 - 我们评估过 `madmom`，但它没有 Windows wheel / conda-forge 构建；beat_this 更准确 并且可以通过 pip 安装。 ## 许可证 在 **MIT License** 下发布 —— 见 [LICENSE](LICENSE)。*Dead as Disco* 是 Brain Jar Games 的商标；本项目与它们无关，也未受其认可。 ## 鸣谢 [beat_this](https://github.com/CPJKU/beat_this) (CPJKU) · librosa · ffmpeg (via imageio-ffmpeg) · [AcoustID](https://acoustid.org) + Chromaprint · MusicBrainz.