音乐控制/解密

This commit is contained in:
LFeng committed 2026-09-28 00:21:12 +08:00
1 parent 9e6d73e191
commit ff1d5cd517
41 files changed
+10827 -4

No files matched your search

+667
View File
@@ -0,0 +1,667 @@
# 音乐模块 · 本地音乐解密规划(Music Decrypt Plan)
> 状态:**P0 + P1a + P1c 已实施并完成真机端到端验证**(2026-09-27:网易云解密 + QQ音乐离线解密 + 文件夹批量 + musicex 在线取密钥,用真实 192kHz/24bit `.mflac` 样本跑通全链路;Rust 单测 204 项全库通过)
> 定位:音乐模块的「本地解密」子能力,不是独立模块——挂靠 `music` 模块新增「解密」页签,Rust 侧新增 `music/decrypt/` 子模块;`ncm` 与 `qmc` 均为纯 Rust 离线引擎,QQ 按「内嵌 ekey 离线 → musicex 在线取密钥」分层(Frida 降为 P2 兜底)
> 日期:2026-09-27(同日修订:QQ 分层重排、ncm 算法细节补全)
> 关联文档:`AI_DEV_GUIDE.md`(模块注册 / IPC 范式——注意 specta 绑定见 `lib.rs` 的 `export_bindings()`)、`MUSIC_REMOTE_PLAN.md`(规划文档范式)
> 参考项目与**许可分档**:
> - `taurusxin/ncmdump`(<https://github.com/taurusxin/ncmdump>,**MIT**)——§3.1 全部算法细节的对照物,**可逐行对照**。
> - `QQKWKG-TriMusicDecrypt`(QKKDecrypt,<https://github.com/Acooldog/QQKWKG-TriMusicDecrypt>,**GPLv3**)——只取平台矩阵与坑清单。
> - `ownlight6/qmc-decoder`(<https://github.com/ownlight6/qmc-decoder>,**GPLv3**)——只取 QMC/musicex/ekey 的**格式与协议知识**(<https://github.com/ownlight6/qmc-decoder/blob/main/MGG_DECRYPTION_FLOW.md>)。
> - GPLv3 两仓:**只读文档与行为,严禁抄代码**。
---
## 0. 结论先行
1. **范围收敛到两平台**(本轮显式指定):网易云 `.ncm` + QQ音乐 QMC 系列。酷狗/酷我明确出栈,不进任何分期。
2. **两条技术路线,全部纯 Rust,零新增运行时依赖**:
- ncm → **Rust 原生**(`aes 0.8` / `cbc 0.1` / `base64 0.22` 已在依赖;`ecb` crate 不在依赖树,ECB 手写 16 字节块循环,零新增 crate)。
- QQ → **Rust 原生三层路由**(详见 §3.2):① 尾部内嵌 ekey 的文件纯离线可解;② musicex 文件读本机凭据调 `GetEVkey` API;③ 前两层都不成立才用 Frida 注入兜底。
- **本节原有的「Frida 主链」判断已作废**:它把「需要客户端在跑」与「需要 Frida 注入」绑成了一件事。实际只有第③层需要注入,而前两层覆盖绝大多数真实文件。改分层后**不再需要便携 Python、不再需要 `pip install frida`、不再受杀软与 mangled 符号版本漂移影响**。
3. **UI 是音乐模块第 4 个页签「解密」**:`useModuleTabs` 加一项 + `DecryptPanel.vue` + 独立轻量 store,命令与事件挂进现有 music 命令族,完全照抄下载任务的「先回 taskId、进度走事件」范式。
4. **许可边界分三档**:`ncmdump` 是 MIT,**可逐行对照**;QKKDecrypt 与 `qmc-decoder` 是 GPLv3 + FFmpeg GPL,**只沉淀格式/协议知识与坑清单,实现逐行重写**。
5. **工作量**:P0(网易云 + 页签全链路)约 **2 个工作日**;P1a(QQ 离线 + API,纯 Rust)约 **2~3 个工作日**;P1b(Frida 兜底,按需)另计。
```mermaid
flowchart LR
subgraph FE["前端 · 解密页签"]
A["DecryptPanel.vue<br/>文件选择 / 任务列表 / 状态卡"]
S["decryptStore.ts<br/>任务状态 + 事件监听"]
end
subgraph R["Rust · music/decrypt/"]
C["commands.rs<br/>run / cancel"]
N["ncm.rs<br/>网易云离线引擎"]
Q["qq.rs<br/>QMC 三层路由(P1)"]
end
subgraph QQS["QQ 三层(P1)"]
L1["① 尾部内嵌 ekey<br/>纯离线"]
L2["② musicex → 本机凭据<br/>GetEVkey API"]
L3["③ Frida 兜底<br/>(P1b,按需)"]
end
O["savedir/decrypted/"]
A --> S --> C
C --> N --> O
C --> Q --> L1 --> O
Q --> L2 --> O
Q -.-> L3 -.-> O
Q -.->|"music-decrypt-event"| S
N -.-> S
```
---
## 1. 需求解构
| 用户原话 | 解构 | 落点 |
|---|---|---|
| 在音乐模块添加解密 Tabs | 音乐模块第 4 个页签 | §5.2 |
| 解密各平台的加密格式 | 收敛为 QQ音乐 + 网易云(本轮显式指定) | §3 |
| 最小路径实现 | 砍掉:转码、元数据回填、封面提取、拖拽、酷狗酷我、并发调优、历史持久化 | §7 P2 清单 |
| 可参考 QKKDecrypt | 对齐思路与坑,不搬 GPLv3 代码 | §3.3 |
---
## 2. 现状勘察(2026-09-27 从仓库实际读取)
### 2.1 已具备的基建(直接复用)
| 能力 | 现有实现 | 复用方式 |
|---|---|---|
| Tab 体系 | `useModuleTabs`(`MusicModule.vue:78`,alwaysVisible 模式,标题栏浮动切换器自动接管) | 加 `{ value: 'decrypt', label: '解密' }` 一项 |
| 任务 + 事件范式 | `music_download` / `music-download-event`(`commands.rs:187`、`constants.rs:107`) | 解密照抄:先回 taskId,进度推事件 |
| 便携 Python + pip 镜像 | `runtime.rs`(清华源 `PIP_INDEX_URL`,`mod.rs:77`) | QQ sidecar 的 frida 安装、Python 就绪检查 |
| 加密依赖 | `Cargo.toml` 已有 `aes = "0.8"`、`cbc = "0.1"`、`base64 = "0.22"` | ncm 的 AES-128-ECB 手写循环,零新增依赖 |
| specta 绑定 | `lib.rs export_bindings()` 两处 `collect_commands!` | 新命令两处同步登记(`lib.rs:300` 注释明确要求) |
| 文件选择对话框 | `@tauri-apps/plugin-dialog`(`MusicModule.vue:4` 已 import) | 页签内直接用,不加 Rust 命令 |
| 输出目录 | 默认 `savedir`(设置页「本地下载目录」) | 解密默认输出 `savedir/decrypted/` |
| 播放引擎 | symphonia(`Cargo.toml:115`) | 解出的 flac/mp3/ogg 可直接进曲库试听 |
### 2.2 关键缺口(需新增)
| 缺口 | 说明 |
|---|---|
| ncm 解密实现 | 纯算法,约 200 行 + 单测 |
| QQ 运行期 sidecar | Frida 注入 + `EncAndDesMediaFile` 调用序列,按参考思路重写 |
| 解密任务 store | 下载任务在 `musicStore`;解密需独立轻量 store(页签切换会卸载组件,监听器必须挂 store) |
| frida 依赖安装 | `pip install frida`(wheel 带原生扩展,走现有镜像),需一条安装命令 + 进度事件 |
---
## 3. 技术选型
### 3.1 网易云 `.ncm`:Rust 原生离线
**为什么不进 Python**:
- ncm 是纯文件级算法,不需要任何进程配合;塞进 Python 等于把 200 行算法绑上「必须先装运行时」的前置。
- 便携 Python 是按需安装(musicdl 才触发),解密不应被它卡住——Rust 路线开箱即用。
- Rust 侧可直接 `cargo test`,对照样本文件做回归。
**算法要点**(对照 MIT 协议的 `ncmdump`(`src/ncmcrypt.cpp`)逐条独立重写。下面每一条都是**会写错的地方**,不是梗概):
**① 容器结构**
```
0x00 magic 8B "CTENFDAM"(即 43 54 45 4E 46 44 41 4D)
0x08 2B 0x02 0x00 → 跳过
0x0A key_len 4B LE
0x0E key_data key_len B (XOR 0x64 → AES-128-ECB → 得 RC4 密钥盒种子)
... meta_len 4B LE
... meta_data meta_len B (XOR 0x63 → 去 22B 前缀 → base64 → AES-128-ECB → 去 6B 前缀 → JSON)
... 5B 跳过(CRC32 4B + 图片版本 1B)
... cover_len 4B LE
... img_len 4B LE
... img_data img_len B (内嵌封面:PNG 或 JPEG)
... 跳 cover_len - img_len
... audio 剩余全部 (改性 RC4)
```
**② 两个 XOR 常量不同**(原文档误合并成一个 `0x64`)
| 段 | XOR 常量 | 加密方式 | 解密后处理 |
|---|---|---|---|
| key 段 | `0x64` | AES-128-ECB | **跳过前 17 字节**(`neteasecloudmusic`),其余即 RC4 密钥盒种子 |
| meta 段 | `0x63` | AES-128-ECB(先 base64 解码) | 跳过前 6 字节(`music:`),其余为 JSON |
**③ AES-128-ECB 解密**:**key 段与 meta 段用两个不同的 16 字节密钥**——`sCoreKey` = ASCII `neteasecloudmusi`(即 17 字节前缀 `neteasecloudmusic\0` 的前 16 字节)、`sModifyKey` = ASCII `#14ljk_!\]&0U<'(`。**收尾不是"去前缀",而是 PKCS#7 风格 padding**:逐 16 字节块解密,最后一字节即 padding 长度(`> 16` 时视作 0),去掉 padding 后再手动跳前缀。
> 易错点:**「AES 密钥」与「要剥掉的前缀」是两个东西**。`neteasecloudmusic` 既是被剥的 17 字节前缀(含结尾 NUL),其前 16 字节又是 key 段的 AES 密钥;meta 段则两者都不同。混用不报错、只会全解错(实现里分别命名为 `CORE_KEY` / `CORE_AES_KEY` / `MODIFY_KEY`)。
**④ meta 段的两层前缀**:原始数据前 22 字节是字面量 `163 key(Don't modify):`,**先剥掉它**,再对余下部分 base64 解码,才喂给 AES。
**⑤ 音频段是「改性 RC4」**
- 密钥盒用参考实现的 KSA:`swap = keybox[i]`;`c = (swap + last_byte + key[key_offset]) & 0xff`,`key_offset` 触 keyLen 归零循环取 key,`keybox[i] = keybox[c]`、`keybox[c] = swap`、`last_byte = c`。**照抄即可,但注意 `last_byte` 在模 256 下是恒等变形(结果与标准 RC4 逐字节相同),它既不是"关键差异",也不能作为验证手段**——见 §6.25。
- 明文按 `0x8000` 字节一块循环,块内 `j = (i + 1) & 0xff`,`plain[i] = cipher[i] ^ keybox[(keybox[(keybox[j] + j) & 0xff] + keybox[j]) & 0xff]`。块之间不重置密钥盒、也不额外跳字节——`i` 是块内下标。
- **块边界必须由"读满一块"确定**(`read_full`),不能用 `Read::read` 的短读结果,否则相位错位、中途变噪声(§6.24)。
- **不存在"每 0x8000 字节后跳过 5 字节间隔"**(原文档此条有误)。`0x8000` 是块大小,`5` 是 §① 里跳过的 CRC32 + 图片版本。
**⑥ 输出扩展名由音频首帧魔数决定,不是 meta 的 `format` 字段**(原文档此条说反了):首个解密块以 `ID3`(`0x49 0x44 0x33`)开头 → `.mp3`,否则 → `.flac`。meta 的 `format` 只用于另一件事——**判断该不该回填标签/封面时的格式分支**。
**⑦ 顺手可得的元数据**:meta JSON 含 `musicName` / `artist`(二维数组,取每项第 0 个元素并用 `/` 连接)/ `album` / `bitrate` / `duration`,且封面字节已在上面的 `img_data` 里读出。**P0 已实现封面单独落盘**(`<歌名>.cover.png|jpg`,按魔数定扩展名);**写进音频标签**仍留 P2——那需要 `lofty` 且要按 mp3/flac/m4a 分派容器,属于「增强」而非「能播」。
**⑧ 失败处理**:魔数不符 / `key_len <= 0` / 块不足 16 字节 → 返回可读错误(`Err(String)`),**per-file 失败不 panic、不中断整批**。
### 3.2 QQ音乐:Rust 原生三层路由(**本节已重写**)
**原判断作废的理由**:原文把「需要 QQ 客户端在跑」与「需要 Frida 注入」绑成了一件事。二者其实独立——ekey(解密密钥)有三种存储形态,只有第三种才需要注入。前两层覆盖真实曲库的绝大多数文件,且都是纯 Rust。
**QMC 加密本体**(与 ncm 同构:字节流密码 + 可选密钥):
| 方案 | 密钥来源 | 适用 |
|---|---|---|
| QMC1 | 固定种子,**无需密钥** | 旧版 `.qmc0` / `.qmc3` / `.qmcflac` / `.qmcogg` |
| QMC2 | ekey(base64 + TC-TEA 加密),密钥 ≤300B 走 Map XOR,>300B 走改性 RC4 | `.mgg` / `.mflac` 全系 |
**ekey 的三种存储形态 → 三层路由**:
| 层 | 形态 | 需要客户端? | 实现方式 |
|---|---|---|---|
| **①** | **尾部内嵌 ekey**:QTag 格式(ekey + 歌曲 ID + `QTag` 魔术)或 V1 格式(文件末尾 4 字节为 key 长度,key 在其前) | ❌ 不需要 | **纯 Rust 离线**,从文件尾直接提取 |
| **②** | **musicex 尾部**(QQ 客户端 ≥ 19.57 / Win 22.x):尾部 192B 只存 song_id + media_mid + filename,**ekey 不落盘** | ✅ 需运行且已登录 | **纯 Rust**:读凭据 → 调 API 取 ekey |
| **③** | 客户端内部导出(方案原文所选) | ✅ | Python sidecar + Frida attach `QQMusicCommon.dll` |
**第②层的完整链路**(全部可在 Rust 内完成,`windows-sys` 只差一个 feature):
1. 尾部检测:读末 8 字节,为 `"musicex\0"` 即 musicex;再向前读 `footer_size + 8` 解析完整 footer(`0x00` song_id u32LE、`0x0C` media_mid UTF-16LE 60B、`0x48` filename UTF-16LE 68B、`0xC0` footer_size、`0xC8` magic)。
2. 取 `uin`:读 `%APPDATA%\Tencent\QQMusic\QQMusicServiceConfig.ini` 的 `[Account] Uin`(明文 INI)。
3. 取 `authst`:**`authst` 在 Windows 上不落盘**,仅在运行中的 `QQMusic.exe` 进程内存里。用 `CreateToolhelp32Snapshot` + `Process32FirstW/NextW` 定位进程 → `OpenProcess(PROCESS_QUERY_INFORMATION | PROCESS_VM_READ)` → `VirtualQueryEx` 遍历可读区(只需 `MEM_COMMIT`,跳过 `MEM_MAPPED`)→ `ReadProcessMemory` 按 1MB 分块 → 搜 `"authst":"` 取其后 Base64URL 串。实测约 0.5 秒。
4. 调 API:`POST https://u.y.qq.com/cgi-bin/musicu.fcg`,`req_1.module = "music.vkey.GetEVkey"`、`method = "CgiGetEVkey"`;`param.filename` **必须带 `.mgg`/`.mflac` 后缀**、`param.songtype` **必须为 1**(否则返回 `104005`)、`param.platform = "27"`(Windows)。响应取 `req_1.data.midurlinfo[0].ekey`。
> 三处易错点:`MEMORY_BASIC_INFORMATION` 在 Win10 1803+ 有 2 字节 `PartitionId` 插在 `AllocationProtect` 与 `RegionSize` 之间,**漏掉会导致 `state` 读成 `protect`、所有内存区被跳过**;`filename` 不带扩展名返回空 ekey;`authst` 有效期约 22.3 小时会过期。
**前置检查与降级出口**(UI 状态卡据此渲染):QQ 未运行或未登录 → 提示"请启动并登录 QQ 音乐后重试";层①②均失败的文件才落到③;Frida 不可用时报可读错误并给排除指引,**不自动拉起 QQ 客户端**。
**③(P1b,按需)的形态**若将来要做:`qq_decrypt.py` 走 `include_str!` 内置(与 `bridge.rs:17` 的 `BRIDGE_SCRIPT` 同范式),一次进程 attach 一批文件,stdout JSON-Lines 回报进度;导出符号是 mangled name(`?Open@EncAndDesMediaFile@@…`),**按子串 `EncAndDesMediaFile` 模糊匹配,严禁硬编码地址或 RVA**。
**输出扩展名**(不能按输入扩展名机械映射):`.qmc0`→`.mp3`、`.qmc3`→`.mp3`、`.qmc2`→`.ogg`、`.qmcogg`→`.ogg`、`.qmcflac`→`.flac`、`.mgg`/`.mgg0`/`.mgg1`/`.mggl`→`.ogg`、`.mflac`/`.mflac0`/`.mflach`→`.flac`(均以首帧魔数兜底校验)。**`.mmp4` 的产物容器(m4a 还是 mp4)尚未独立证实,实施 P1 时必须用真机样本确认后再定**。
### 3.3 许可边界(必须遵守,三档口径)
- **MIT(可逐行对照)**:`taurusxin/ncmdump`(网易云 ncm 算法本体)。可直接对照 `src/ncmcrypt.cpp` 实现,仅需保留版权声明。
- **GPLv3(只读文档与行为,严禁抄代码)**:`QQKWKG-TriMusicDecrypt`(+ FFmpeg GPL)、`ownlight6/qmc-decoder`。**整段搬代码 = 给本仓库引入 GPL 传染。** 允许的是:阅读其调用序列、常量、格式与协议说明后**独立重写**——本文档 §3.1 / §3.2 沉淀的正是这类非代码知识。
- **合规口径**(UI 底部放一行):仅处理用户本人拥有合法访问权限的本地文件,不用于批量分发或规避付费授权。
---
## 4. 接口契约
### 4.1 Tauri 命令
```rust
// 任务
music_decrypt_run(task_id, files?, folder?, root?, out_dir?, in_place?) -> Result<(), String>
music_decrypt_cancel(task_id: String) -> Result<bool, String>
// 预览与状态
music_decrypt_scan(folder: String, root: Option<String>) -> Result<ScanSummary, String>
music_decrypt_qq_status() -> Result<QqOnlineStatus, String> // 只读本机,不发网络请求
```
`QqOnlineStatus` 字段:`{ running, loggedIn, uin, ready, message, steps }`。
**`authst` 不下发到前端**——它只活在后端内存里用于调接口。
- **注册是 3 处,不是 2 处**(实测仓库现状):
1. `music/mod.rs` 的 `pub use commands::{...}` re-export(约 `mod.rs:48`);
2. `lib.rs` 的 `collect_commands![]`(`export_bindings()` 内,`lib.rs:205`);
3. `lib.rs` 的 `generate_handler![]`(`run()` 内,`lib.rs:348`)。
漏第 2 处 = 运行时能调但 `bindings.ts` 缺类型;漏第 1、3 处 = 编译失败或调用失败。
- 前端沿用本模块既有范式(`musicStore.ts` 全用原生 `invoke` + 手写类型,不用 `commands`),故解密 store 同样用 `invoke`。
### 4.2 事件 `music-decrypt-event`(登记进 `constants.rs` 音乐分组)
```typescript
type MusicDecryptEvent = // 注意:只有 tag 是 kebab-case,**字段名仍是 snake_case**
| { type: 'start'; task_id: string; total: number }
| { type: 'file'; task_id: string; index: number; name: string;
status: 'ok' | 'error' | 'unsupported';
message: string | null; // 失败原因,或成功时的备注(平台 / 密钥形态 / 元数据摘要)
output: string | null; // 主产物
cover: string | null } // 单独落盘的封面(网易云带内嵌封面时才有)
| { type: 'progress'; task_id: string; done: number; total: number;
bytes_done: number; bytes_total: number; name: string }
| { type: 'finished'; task_id: string; ok: number; failed: number; cancelled: number }
```
> **字段名是 snake_case 而非 camelCase**:`DecryptEvent` 上只有 `#[serde(tag = "type", rename_all = "kebab-case")]`
> 作用在 tag 上,变体字段名原样输出。前端 `decryptStore.ts` 的 `RawEvent` 必须照此声明
> ——两边不一致时不会编译报错,只会表现为「任务建好了但进度永不动」。
> Rust 侧有 `event_json_contract` 单测把形状钉死(§6.23)。
>
> 结果态没有 `already`:P0 不做「已解密过则跳过」(同一文件重解会产出 `_1` 后缀的新文件),
> 语义比"猜哪份产物属于哪次输入"更可预测。
> 原先的 `deps-install` 事件随 `music_decrypt_install_deps` 一起取消——三层路由后不再需要 `pip install frida`。
> 注意前端 `musicStore.ts:419` 是**硬编码事件名字符串**、并未引用前端常量表,故解密 store 同样硬编码,仅 Rust 侧登记常量。
### 4.3 文件识别(用户不选平台)
按扩展名路由,魔数校验兜底:
| 扩展名 | 路线 |
|---|---|
| `.ncm` | 网易云离线引擎(按内容魔数识别,不依赖后缀) |
| `.mgg` / `.mgg0` / `.mgg1` / `.mggl` / `.mflac` / `.mflac0` / `.mflach` / `.mmp4` / `.qmc0` / `.qmc2` / `.qmc3` / `.qmcflac` / `.qmcogg` | QQ 引擎(按尾部形态决定是否联网) |
| 其他 | 散选时保留为 `unsupported`;文件夹扫描时直接跳过 |
> 后缀矩阵原文档只列了 3 个,会**静默漏掉用户曲库里的常见文件**,故过滤列表与路由表**一次写全**。
> 实际判定以**内容**为准(§4.5),后缀只用于文件对话框的过滤器。
### 4.3.1 QQ 音乐:是否需要登录?
这是使用者最常问的一点,所以结论放在前面:
| 文件来源 | 扩展名 | 需要 QQ 音乐登录? |
|---|---|---|
| QQ 客户端 **≤ 19.51** 下载 | `.qmc0` `.qmc3` `.qmcflac` `.qmcogg` | **不需要** |
| QQ 客户端较旧版本下载(QTag / V1 尾部) | `.mgg` `.mflac` | **不需要** |
| QQ 客户端 **≥ 19.57** 下载(musicex 尾部) | `.mgg` `.mflac` `.mmp4` | **需要**:客户端运行 + 已登录 |
| 网易云(任何版本) | `.ncm` | **不需要** |
**为什么新版必须登录**:从 19.57 起,QQ 音乐不再把解密密钥(ekey)写进文件,
只在文件末尾留 192 字节元数据;客户端自己也是在播放/下载时拿本机登录态
(`uin` + `authst`)向服务器实时换取密钥。第三方要解开同一个文件,只能复刻这一步。
**这里的实现方式**:只读本机凭据(INI 里的 `uin` + 运行中 `QQMusic.exe` 内存里的 `authst`),
再调官方 `music.vkey.GetEVkey` 接口取密钥——**不注入进程、不改写文件、不做任何反检测**。
**操作步骤**(与 UI 状态卡里的文案一致):
1. 在电脑上启动 QQ 音乐客户端(Windows 版)。
2. 用它登录你的账号,并**保持客户端开着**(`authst` 只存在于运行期内存)。
3. 回到「解密」页点「重新检测」,状态变为「已就绪」即可解密 musicex 文件。
4. 若提示未取到登录令牌:先在客户端里**播放任意一首歌**触发一次网络请求,再重新检测。
5. 仍失败则试过**以管理员身份运行**本应用(读其他进程内存可能需要更高权限)。
6. 登录令牌约 **22.3 小时**过期;过期后重新检测即可,无需重装。
**UI 呈现**:状态卡显示三态(未运行 / 未登录 / 已就绪)+ QQ 号 + 「重新检测」按钮;
未就绪时折叠区里就是上面这 6 条步骤。上方那句"旧版文件与 `.ncm` 本来就不需要登录"
也会一并显示,避免用户误以为自己必须登录才能用这个功能。
### 4.4 输出路径规则
- **就地模式(`in_place = true`,文件夹批量的默认)**:产物与源文件**同目录同名**,
仅按格式改扩展名(`Pop/a.mflac` → `Pop/a.flac`)。符合"就地解出来"的直觉,
也天然不会与其他目录的同名文件冲突。此时 `out_dir` 不参与写盘。
- **指定输出目录(`in_place = false`)**:默认根目录 `savedir/decrypted/`,
并**按 `root` 还原相对目录结构**(`Pop/2026/b.ncm` → `out/Pop/2026/b.flac`)。
散选文件没有相对目录,平铺到根目录。
- **同名去重**:即使还原了目录结构,同一目录内仍可能撞名(如 `.mgg` 与 `.mgg1` 同基名)。
规则:优先用原名,已存在(磁盘上或本批内已占位)则追加 `_1` / `_2`…
- **输入输出相交保护**:非就地模式下,若某输入文件已位于输出目录内则剔除,
避免"解出来再解"无限膨胀;全被剔除时报错并提示可改用「就地解密」。
- 扩展名以**音频首帧魔数**决定(ncm 见 §3.1⑥,QMC 见 §3.2 末),不信任输入扩展名;
魔数认不出时才回退到输入后缀映射。
### 4.5 文件夹批量
命令参数的关系:
| 参数 | 含义 |
|---|---|
| `folder` | **文件夹批量入口**:Rust 侧递归扫描该目录 |
| `root` | 计算相对路径的基准(决定输出目录里还原哪几层) |
| `files` | 散选文件列表(`folder` 为空时使用) |
| `in_place` | 就地解密(默认 `true`,见 §4.4) |
| `music_decrypt_scan` | 只扫描不解密,返回 `{ total, ncm, qmc }` 供 UI 预览 |
**平台判定按内容,不按后缀**(`scan::route`):
1. 读 8 字节魔数,命中 `CTENFDAM` → 网易云;
2. 否则读尾部判 QMC 形态:后缀在 QMC 家族里 → QQ音乐;
3. 后缀不认识时,只有**明确**的尾部形态(QTag / V1 / musicex)才认领——
否则任何末尾凑巧不是 `QTag` 的文件都会被判成"QMC1",噪声太大。
理由:同一曲库里 `.ncm` / `.mflac` / `.qmcflac` / `.mgg` 混放是常态,且 QQ 还有
`.mgg0` / `.mflac0` 等变体,靠后缀枚举必然漏。代价是**认不出的文件会被跳过**,
所以扫描数可能少于用户预期——因此 UI 先调 `music_decrypt_scan` 显示
"找到 N 个 · 网易云 x · QQ音乐 y",让用户在开跑前就能判断是否符合预期。
---
## 5. 架构与模块设计
### 5.1 Rust 侧 `src-tauri/src/music/decrypt/`(已实施的实际结构)
```
decrypt/
mod.rs // 任务表(Mutex<HashMap<taskId, 取消标志>>)、工作线程 + 节流事件转发、事件契约
common.rs // 两引擎公共件:DecryptError、魔数定格式、同名去重、读满一块
ncm.rs // 网易云离线引擎(AES-ECB + RC4 变体 + meta/封面)
qmc.rs // QQ:QMC1 静态密钥 / QMC2 Map / QMC2 RC4 / tc_tea / 尾部形态 + 流密码
qq_footer.rs // musicex 尾部解析(纯,可单测)
qq_credentials.rs // 凭据:INI 解析(纯)+ 进程内存取 authst(平台胶水)
qq_memscan.rs // Windows 专用:ToolHelp 枚举进程 + VirtualQueryEx/ReadProcessMemory(只读)
qq_ekey.rs // GetEVkey 请求组装与响应解析(纯,可单测)
qq_online.rs // 编排:musicex → 凭据 → 取密钥 → 解密;probe_status()
scan.rs // 文件夹递归扫描 + 内容优先的平台路由
commands.rs // run / cancel / scan / qq_status(四条命令)
```
平台判定与密钥来源的**分工**:`scan.rs` 只决定"这文件归哪个引擎";
`qmc.rs` 决定"密钥从哪来"(内嵌 / 静态);只有尾部是 musicex 时,
调度层才把 `KeyRequired` 交给 `qq_online.rs` 转在线路径——这样离线路径保持零网络依赖。
`mod.rs` 挂到 `music/mod.rs` 的子模块列表;事件常量加进 `constants.rs` 音乐分组。
### 5.2 前端
```
src/modules/music/components/DecryptPanel.vue // 页签内容
src/stores/decryptStore.ts // 任务列表 + 事件监听(照 musicUploadStore 范式)
MusicModule.vue // tabs 加一项 + <TabsContent value="decrypt">
index.ts // searchItems 加「音乐解密」(tab: 'decrypt')
```
**P0 / P1a / P1c UI 形态**(已实施):
- 顶部操作行:**选择文件夹** | 选择文件(dialog 多选,按 §4.3 全后缀过滤)| **就地解密开关** | 取消 / 清空记录
- **QQ 音乐在线解密状态卡**:状态点(三态)+ 一句话状态 + QQ 号 + **重新检测** + 折叠的**操作步骤**;
未就绪时折叠区里就是 §4.3.1 那 6 条,并附一句"旧版文件与 `.ncm` 本来就不需要登录"
- 输出目录行:就地模式下置灰并显示"与源文件同目录"
- **文件夹扫描预览条**:显示"找到 N 个 · 网易云 x · QQ音乐 y" + 开始解密按钮
- 中部任务表:任务头(文件夹路径 / 进度条 / `bytes_done/bytes_total` / 打开产物目录)|
文件行(文件名 | 平台徽标 | 状态徽章 | 打开产物目录 | 打开封面 | 备注或失败原因)
- 空态用 `StateBlock variant="empty"`;进度条结构恒定(完成后保留满格,不整块消失)
- 底部一行合规说明
### 5.3 数据流
与下载链路同构:前端 → `music_decrypt_run` → Rust 建 taskId 即回 → 后台执行 → `music-decrypt-event` → `decryptStore` 更新 → 列表刷新。页签切换组件卸载不影响任务(监听在 store)。
---
## 6. 关键实现细节与已知的坑
**ncm**(编号对应 §3.1 的条目号)
1. `aes 0.8` 只有块原语、`ecb` crate 不在依赖树:ECB 手写 16 字节块循环(`cipher::BlockDecrypt::decrypt_block`)。**不要**为此引入 `ecb` crate。
2. **两段 XOR 常量不同**(`0x64` key / `0x63` meta)。照抄成同一个常量 = 必然失败。
3. **PKCS#7 风格 padding**:AES-ECB 收尾取最后一字节为 padding 长度(`> 16` 视作 0),不是“去前缀”。
4. **改性 RC4 KSA 的 `last_byte` 累加**(照抄参考实现即可,但别误解它):
式子 `c = (swap + last_byte + key[key_offset]) & 0xff` 在模 256 下**恰好化简为标准 RC4**,
实测两者密钥盒逐字节相同(256/256)。因此它**不是**"与标准 RC4 的关键差异",
也不能靠与标准 RC4 比对来验证实现——验证只能靠固定向量(见 §6.25)。
`key_offset` 触 keyLen 归零循环取 key 这一点照抄。
5. **音频块之间不跳字节**,`0x8000` 只是块大小;`i` 是块内下标。原文档的"每 0x8000 跳过 5 字节"是错的(那 5 字节在 §① 的头部里,且已单独处理)。**但块边界必须由"读满一块"确定**,不能用 `Read::read` 的短读结果(见 §6.24)。
6. **输出扩展名看音频首帧魔数**(`ID3` → `.mp3`,否则 `.flac`),不看 meta 的 `format`。
实现比这条更宽一点:还识别 `fLaC` / `OggS` / `RIFF..WAVE` / `ftyp` / `wvpk`,
给 P1 的 QQ 产物复用(ncmdump 的兜底同为 flac)。
7. meta 段是**两层前缀**:先剥 22 字节 `163 key(Don't modify):`,再 base64,再 AES,再剥 6 字节 `music:`。
8. **流式处理**:`0x8000` 块逐块读→解→写,禁止整文件读入内存(`.mmp4` 可能很大)。大文件下需按已处理字节数推 `progress`。
9. **单测不依赖真实样本**:真实 FLAC 最小样本进不了仓库。改为对**中间产物**断言——AES-ECB 往返、KSA 密钥盒已知值、padding 剥离、魔数→扩展名判定、以及"自造一个合法 ncm 容器(用同一套算法正向构造)再解回来"的往返测试。真机样本走手动自测。
10. 魔数/解析失败走 per-file `Err`,**不 panic、不中断整批**。
**QQ(P1)**
11. 第①层(QTag / V1)**完全离线**,不要因为"QQ 文件"就先去连客户端——先用尾部分支判形态再决定要不要读凭据。
12. 第②层的 `authst` **只在 `QQMusic.exe` 运行期内存里**,不落盘;`uin` 在 `QQMusicServiceConfig.ini` 可明文读。`MEMORY_BASIC_INFORMATION` 的 2 字节 `PartitionId`(Win10 1803+)**必须包含**,否则 `state` 会读成 `protect`、所有内存区被跳过。
13. API 三处必须:`filename` 带 `.mgg`/`.mflac` 后缀、`songtype = 1`、`module = music.vkey.GetEVkey`(不是 `GetVkey`)。否则 `104005` 或 ekey 为空。
14. `authst` 约 22.3 小时过期:失败文案要给"重新登录 QQ 音乐"的出口,而不是只报网络错误。
15. 第③层(Frida):必须**先启动 QQ 音乐**再 attach,`QQMusicCommon.dll` 打开主界面即加载;导出符号是 mangled name,**按子串 `EncAndDesMediaFile` 模糊匹配,严禁硬编码地址或 RVA**;被杀软拦截只给排除指引,**不做反检测动作**;批量时客户端 UI 可能短暂卡顿,属预期。
16. `path_sensitive_mflac` 变体(同名文件不同目录内容不同)P1 不处理:报错带全路径,遇到再迭代。
17. `.mmp4` 产物容器未证实,P1 先用真机样本确认再定(见 §3.2 末)。
**工程**
18. 新命令登记 **3 处**:`music/mod.rs` re-export、`lib.rs` 的 `collect_commands![]`、`lib.rs` 的 `generate_handler![]`(见 §4.1)。
19. `music-decrypt-event` 常量进 `constants.rs` 音乐分组;前端沿用硬编码字符串(与 `musicStore.ts:419` 一致)。
20. 解密 store 必须独立于组件生命周期:Tabs 非 active 会卸载内容,事件监听挂 store 不挂组件。
21. **输出同名去重 + 输入输出相交保护**(见 §4.4)——原文档缺失,不做会静默覆盖用户文件。
22. 三层路由后**不再需要便携 Python 与 frida**,`music_decrypt_install_deps` 命令取消;QQ 未登录的错误出口走状态卡提示。
**实施中新增确认的坑(2026-09-27 实测)**
23. **事件字段名是 snake_case**(不是 camelCase)。`#[serde(tag = ..., rename_all = "kebab-case")]`
只作用于 tag,变体字段名原样输出。前后端不一致时**不报错**,只表现为进度不动。
Rust 侧 `event_json_contract` 单测钉死 JSON 形状。
24. **音频块边界必须用"读满一块"而非 `Read::read` 的返回值**。`BufReader::read` 会短读,
块边界一漂移,解密式里的「块内偏移 `i`」就与加密侧错位,表现为**文件从中间某处起全是噪声**
(实测首个坏字节落在 32418,仍在第一大块内),前半段却完全正常,极难排查。
已加 `read_full()` 专门处理。
25. **`last_byte` 累加在模 256 下是恒等变形**:`c = swap + last_byte + key` 与标准 RC4 的
`j += s[i] + key` 结果**逐字节相同**(已实测 256/256 一致)。所以:
- 不能靠"与标准 RC4 比对"来验证密钥盒实现;
- 也**不要**以为它是"改性 RC4 的关键差异"而据此改写(本计划早期的 §6.4 表述即由此误导)。
真正的验证手段是**固定向量**(`key_box_matches_reference_vectors` /
`keystream_matches_reference_vector`)。
26. **`MODIFY_KEY` 是 16 字节而非 17**(`aes::Aes128` 的密钥长度就是 16);
`CORE_KEY` 的 17 字节是**解密后要剥掉的前缀**,与 AES 密钥不是同一个东西
(AES 密钥是它的前 16 字节)。两者混用不会编译报错,只会全解错。
27. **合成容器单测的 key 段必须带 `neteasecloudmusic` 前缀**——否则解密端剥前缀后拿到错种子。
这个坑一度被"单循环 KSA"的错误实现掩盖(两边同时错、往返仍然自洽)。
**P1a(QQ 离线)实施中新增确认的坑**
28. **QMC2 Map 密码的 `scramble` 必须用 `wrapping_shl/shr`**(对移位量取模),
不能写成 `u8::rotate_left/rotate_right`——后者会在内部再取一次模,结果**不同**。
被 Apache 参考实现的原向量抓到(若不比对向量,会产出"能跑但全错"的解密)。
29. **tc_tea 不是 TEA-ECB,而是 TEA 变体 + 自定义 CBC**:块与密钥字都是**大端**、
16 轮(非 32)、单轮是 `((v<<4)+k1) ^ (sum+v) ^ ((v>>5)+k2)`,
且明文前置 `1+pad+2` 字节头、尾部 7 字节 0 自校验。照 TEA-ECB 写会解出**部分可读的乱码**
(表现极具迷惑性:能看到明文碎片)。尾部 0 校验正是"密钥对不对"的权威判据。
30. **V1 尾部判定不能只看长度**:任意加密数据末尾都可能凑出 `0<n<=0x400`,
只按长度判会把普通 QMC1 文件误判成 V1 并砍掉一大截音频(实测 32871 字节 → 4096)。
必须追加"前面那一段像不像 base64 ekey"的校验。
31. **`sniff_tail` 的 `audio_len` 必须换算成绝对长度**:它只读了尾部 probe,
`detect_tail` 给出的是**相对 probe 起点**的偏移;QMC1(无尾部)必须回落到**整个文件大小**。
另外**不要在两个地方各写一遍尾部探测**——当初 `decrypt_file` 自己复制了一遍,
修了 `sniff_tail` 却没修它,症状是"探测结果对、实际产物只有 4KB"。
32. **QMC1 的掩码分支是 `pos > 0x7FFF`(严格大于)**,不是 `>=`;写成 `>=` 会在回绕点差一字节。
**P1c(musicex 在线)实施中新增确认的点**
33. **`MEMORY_BASIC_INFORMATION` 的 `PartitionId`(Win10 1803+)**:直接沿用
`windows-sys` 的结构体即可,但**自己手写 `#[repr(C)]` 时千万别漏**——漏了会让
`RegionSize`/`State`/`Protect` 全部读错偏移,`VirtualQueryEx` 返回的 `State`
读成 `Protect`(如 `0x04` 而非 `0x1000`),于是所有内存区被跳过、永远扫不到 token。
34. **`getEVkey` 的三个"必须"**:`filename` 带扩展名、`songtype=1`、
`module=music.vkey.GetEVkey`(不是 `GetVkey`)。任一写错都只是"拿不到 ekey",
不会报错——所以请求体用纯函数组装并单测锁死(`qq_ekey::build_evkey_request`)。
35. **`authst` 会过期(约 22.3 小时)**:失败文案必须给"重新登录 / 重新检测"的出口,
否则用户会以为是网络问题。响应里的 `expiration` 已带进产物备注。
36. **单元测试不要真的发网络请求**:本机一旦登录成功,测试就会去连 QQ 服务器,
导致测试变慢变脆。改为验证"请求体能正确构造"+"`#!Qk` 头守卫"+"尾部能被解析出
`media_mid`/`filename`"三段——真实响应留给真机端到端。
37. **musicex 音频段要校验 `#!Qk` 头**:尾部像 musicex 不代表内容真是 QMC2 密文;
没有这道守卫会把任意文件"解"成垃圾却报告成功。
**真机端到端验证后修正(2026-09-27)**
38. **`#!Qk` 不是 QMC2 密文的通用魔术**(推翻第 37 条的做法):真机 musicex 样本
(Avicii - Heaven,197MB `.mflac`)的密文头是 **`51 74 03 75`**,按"必须以 `#!Qk`
开头"写的守卫会把**完全合法的文件误拒**。
正确做法是**用解密结果判定密钥是否正确**:用取到的密钥解出前 16 字节,
看是否是已知音频魔术(`fLaC` / `OggS` / `ID3` / `ftyp`…)——密钥错时它是随机噪声,
几乎不可能凑巧命中;命中即说明密钥对、文件也对。
这也是"内容优先"原则的又一次应用:**不要用猜测的密文特征做判据,要用能验证的结果。**
39. **文档给的 musicex 字段偏移在真样本上是对的**:`0x0C` media_mid(60B UTF-16LE)、
`0x48` filename(68B UTF-16LE)、`0xC0` footer_size、`0xC8` magic 全部命中,
尾部实测 192 字节、padding 区有 13 个非零字节(所以不能假设 padding 全 0)。
40. **真机样本的规模提醒**:`.mflac` 可达 197MB / 192kHz / 24bit。
`qq_online` 目前把音频段整段读入内存再解密(探针与生产路径都是),
在这个量级下可用,但如果将来遇到多 G 的文件,应改成分块解密 + 流式写盘
(`qmc` 的流密码本身已支持任意偏移)。
---
## 7. 分阶段计划
### P0 — 网易云 + 解密页签全链路(约 2 天)**✅ 已实施(2026-09-27)**
- [x] `useModuleTabs` + `TabsContent` 接「解密」页签;`index.ts` 搜索条目
- [x] `decrypt/ncm.rs`:§3.1 全部要点 + 单测(**18 项通过**)
- [x] `decrypt/mod.rs` + `commands.rs`:run / cancel + 事件发射;**三处**登记;`constants.rs` 事件常量
- [x] `decryptStore.ts` + `DecryptPanel.vue`:选文件 → 批量任务 → 进度 → 打开输出目录
- [x] 输出同名去重 + 输入输出相交保护(§4.4)
- [x] 封面单独落盘(`<歌名>.cover.png|jpg`)——标签回填仍留 P2(`lofty` 需按容器分派)
- [ ] **自测:真实 `.ncm` 样本解出**(需人工用真机样本验证;仓库内样本有版权且体积大,故算法靠 §6.9 的中间产物单测 + 合成容器往返覆盖)
- **验收**:页签选 10 个 ncm 全部解出、失败有原因、切页签不丢任务、播放器直接可播
**已交付文件**:
| 文件 | 内容 |
|---|---|
| `src-tauri/src/music/decrypt/ncm.rs` | 网易云离线引擎(容器解析 / AES-ECB / 密钥盒 / 流式解密 / 魔数定格式 / 封面 / 同名去重)+ 单测 |
| `src-tauri/src/music/decrypt/mod.rs` | 任务表、工作线程 + 节流事件转发、`DecryptEvent` 契约(含 JSON 形状单测) |
| `src-tauri/src/music/decrypt/commands.rs` | `music_decrypt_run` / `music_decrypt_cancel` + 输出目录解析与相交保护 |
| `src/stores/decryptStore.ts` | 任务状态 + 事件监听(挂 store,不随组件卸载) |
| `src/modules/music/components/DecryptPanel.vue` | 页签 UI |
| `music/mod.rs` · `lib.rs` · `constants.rs` | 子模块挂载、`MusicManager.decrypt` 字段、三处命令登记、事件常量 |
### P1a — QQ 离线解密 + 文件夹批量(**✅ 已实施,纯 Rust,无 Python/frida**)
- [x] `decrypt/qmc.rs`:QMC1 静态密钥表 / QMC2 Map 密码 / QMC2 RC4 变体 / tc_tea(TEA 变体 + 自定义 CBC)
- [x] 第①层:QTag 与 V1 尾部 ekey 提取 → **离线解密**
- [x] `decrypt/scan.rs`:递归扫描 + 内容优先的平台路由 + 保留相对目录结构
- [x] **文件夹批量**:`folder` / `root` / `in_place` 三个参数 + `music_decrypt_scan` 预览命令
- [x] `decrypt/common.rs`:两引擎统一的错误类型、魔数定格式、同名去重、读满一块
- [x] 单测 **56 项**(模块合计 174 项全库通过),含参考实现的原始测试向量
- [ ] 第②层 musicex + `GetEVkey` API(**未实施**,见 P1c)
- [ ] 真实 `.mflac/.mgg/.qmcflac` 样本自测(需人工;仓库内不放版权样本)
**已交付文件(P1a 增量)**:
| 文件 | 内容 |
|---|---|
| `src-tauri/src/music/decrypt/qmc.rs` | QMC 全套离线算法 + 尾部形态判定 |
| `src-tauri/src/music/decrypt/scan.rs` | 文件夹递归扫描与平台路由 |
| `src-tauri/src/music/decrypt/common.rs` | 两引擎公共件 |
**算法来源(全部宽松许可,均有原始向量锁行为)**:
| 部分 | 来源 | 许可 |
|---|---|---|
| QMC1 静态密钥表 + 掩码规则 | `jixunmoe/qmc-decode` | MIT |
| QMC2 密钥派生 / Map / RC4 / 尾部形态 | `bczhc/qmc-dec`(`qmc2-crypto`) | Apache-2.0 |
| tc_tea | `tc_tea` crate | MIT/Apache-2.0 |
### P1b — Frida 兜底(按需,不计入本轮)
- [ ] `qq_decrypt.py`(`include_str!`):attach → `EncAndDesMediaFile` 调用序列 → 批量 → JSON-Lines 进度
- [ ] `decrypt/qq_frida.rs`:前置检查、spawn、逐行读转发事件
- **触发条件**:仅当 §3.2 的第③层文件在真实用户场景中被确认存在且前两层无法覆盖时才做
### P1c — musicex 联网取 ekey(**✅ 已实施**)
- [x] `qq_footer.rs`:musicex 尾部解析(song_id / media_mid / filename)
- [x] `qq_credentials.rs`:读 `%APPDATA%\Tencent\QQMusic\QQMusicServiceConfig.ini` 的 `uin` + 扫进程内存取 `authst`
- [x] `qq_memscan.rs`(Windows):`CreateToolhelp32Snapshot` + `OpenProcess` + `VirtualQueryEx` + `ReadProcessMemory`(**只读**)
- [x] `qq_ekey.rs`:`GetEVkey` 请求组装与响应解析(`filename` 带扩展名 / `songtype=1` / `platform="27"`)
- [x] `qq_online.rs`:编排 + `probe_status()` 在线能力探测
- [x] `music_decrypt_qq_status` 命令 + UI 状态卡(含**逐步操作说明**)
- [x] `windows-sys` 增开 `Win32_System_Diagnostics_ToolHelp` 与 `..._Debug`
- [x] **本机实测**:`probe_status()` 返回 `running=true logged_in=true uin=1154027699 ready=true` —— 内存扫描确实取到了 `authst`
- [x] **端到端已用真机样本跑通**(2026-09-27,见下)
#### 真机端到端验证记录(首个 musicex 样本)
样本:`C:\Users\Administrator\Music\Heaven - Avicii_EM.mflac`(197,104,516 字节,
尾部 `musicex\0`,`song_id=233102682`,`media_mid=003iTvi44A6RMs`,
`filename=AIM0002ELI6a1wXJDo.mflac`)
| 环节 | 实测结果 |
|---|---|
| 尾部解析 | song_id / quality1=2 / quality2=11 / media_mid / filename 全部正确 |
| 凭据 | 返回 `running=true logged_in=true uin=1154027699 ready=true` |
| `GetEVkey` | **成功**,拿到 704 字符 ekey;`expiration=80400`(22.3 小时,与文档一致) |
| ekey → 密钥 | 解密出 **512 字节**原始密钥 → 命中 **RC4 变体**(>300 字节)分支 |
| 音频段 | 197,104,324 字节(= 文件大小 − 192 字节尾部,完全吻合) |
| 解密结果 | 首帧 `66 4c 61 43` = **`fLaC`** ✅ |
| 产物校验(`lofty`) | **277.261 秒 · 192000 Hz · 24 bit · 2 声道 · 5686 kbps** —— 192kHz/24bit Hi-Res 无损 |
**验证方式**:`examples/decrypt_musicex_probe.rs` 走真实链路(读内存凭据 → 真实
HTTP 请求 → 解密),再用 `examples/verify_audio.rs` 交给项目同款解析器确认产物合法。
两个 example 都保留,供后续 QQ 改协议时快速定位。
**这次验证推翻了一个错误假设**:样本的密文头是 `51 74 03 75`,**不是**文档里提到的
`#!Qk`。原先按"密文必须以 `#!Qk` 开头"写的守卫会把完全合法的文件误拒——已改为
**用解密结果判定**(解出的前 16 字节是否为已知音频魔术),见 §6.38。
**凭据可用性已知限制**:
| 维度 | 情况 |
|---|---|
| `uin` 来源 | INI 明文,稳定 |
| `authst` 来源 | 仅运行期内存;**QQ 音乐必须开着且已登录** |
| 有效期 | 约 22.3 小时(响应 `expiration` 字段,已带进产物备注) |
| 权限 | 读他人进程内存可能需管理员;失败文案已提示 |
| 是否注入 | **否**,纯只读——这是它与 Frida 兜底的本质区别 |
### P2 — 按需增强(不进本轮)
- **ID3 / FLAC / MP4 标签回填**(用 `lofty`,按容器分派;meta JSON 已在解密时解析出来)
- 解密完成 →「加入本地曲库」/ 上传飞牛(复用 `musicUploadStore`)
- 拖拽文件进页签、解密历史持久化
- 酷狗 / 酷我(除非再次明确要求)
- QQ 变体适配(path_sensitive_mflac)
> **变更**:原计划把「封面提取 / ID3 标签回填」一起从 P2 提前到 P0。**实际只提前了封面提取**——
> 封面字节在解析容器时顺手就读出来了,落盘是十几行,且不做就"能播但难用"。
> 标签回填仍留 P2:它需要 `lofty` 且要按 mp3/flac/m4a 分派容器,属于增强而非可用性门槛。
---
## 8. 风险与开放问题
| 风险 | 影响 | 对策 |
|---|---|---|
| QQ 改 musicex 尾部/API 协议 | 第②层失效 | 协议字段集中在 `qq_footer` / `qq_ekey` 两处;错误文案带原始响应码;关注 qmc-decoder issue |
| `authst` 提取被安全软件拦截 | 第②层失效 | **只读**内存、不注入;失败给"以管理员身份运行"出口 |
| **musicex 端到端** | ~~真实响应字段可能与文档不符~~ **已验证通过**(真机 197MB 样本,产物为合法 192kHz/24bit FLAC) | 保留 `examples/decrypt_musicex_probe.rs` + `verify_audio.rs`,QQ 改协议时可快速定位 |
| `authst` 过期(22.3h) | 第②层短期失效 | 错误文案给"重新登录/重新检测"出口;有效期带进产物备注 |
| QQ 版本升级改 mangled 导出符号 | 仅第③层(Frida)失效 | 子串模糊匹配;第③层不在实施范围,影响面已缩小 |
| 真实样本不足导致算法细节偏差 | 解出错文件 | **已用参考实现的原始测试向量交叉验证**(QMC1 掩码 / Map / RC4 / tc_tea / ekey 端到端) |
| GPLv3 边界被无意破坏 | 许可风险 | 三档口径见 §3.3;QMC 只取 MIT / Apache-2.0 两份来源的**代码与数据** |
| 网易云改 ncm 格式 | 个别文件失败 | per-file error 不中断整批 |
| 同名文件落盘互相覆盖 | **用户文件丢失** | §4.4 同名去重 + 相交保护 |
| 文件夹扫描漏文件(内容认不出) | 用户以为解完了 | UI 先出 `music_decrypt_scan` 预览数量 |
**开放问题**:
1. 解密输出默认就地(文件夹批量)或 `savedir/decrypted/`(散选);独立设置项留 P2。
2. QQ 未运行时是否自动拉起?**离线层与 `.ncm` 完全不需要客户端**;只有 musicex 需要,
当前选择"只提示、不自动拉"(客户端要登录,自动拉起也解决不了登录态)。
3. `.mmp4` 的产物容器(m4a / mp4)待真机样本确认——当前靠首帧 `ftyp` 魔数判定,认不出时按后缀落 `m4a`。
(`.mflac` 已实测确认:产物为 192kHz/24bit 的 `.flac`。)
4. ~~musicex 端到端未验证~~ **已解决**(2026-09-27,真机样本跑通,见 P1c 的验证记录)。
5. `.mflac0` / `.mgg1` 等变体按 QMC2 处理,但**未用真实样本验证**过其尾部形态与 `.mflac` / `.mgg` 一致。
6. 微信登录的 QQ 音乐 (`tmeLoginType=3`):实现上 `authst` 与 QQ 登录通用,
但 `login_type` 目前固定发 `1`(QQ 登录实测可用)——若真机发现微信登录取不到 ekey,需按凭据来源推断。
7. **大文件内存占用**:`qq_online` 目前整段读入内存解密;197MB 实测可用,
但 `.mflac` 可以更大。若遇到多 G 文件,应改流式(`qmc` 的流密码已支持任意偏移)。
---
## 附录 A:参考项目对照(只取思路)
### A.1 QKKDecrypt 实测结论(2026-09-27 深读 `main@938b22d`,来自其源码而非猜测)
**最重要的一条**:该项目 QQ 路径**完全不解析 QMC 加密格式**——它把原始加密文件整包交给 QQ 自己的 DLL 解密,因此不受 static/map cipher 变体影响。**代价是强依赖四项**:QQ 客户端运行 + `QQMusicCommon.dll` 已加载 + **管理员权限**(`cli.py::_require_admin()`,非管理员直接 `return 2` 并打印"已禁止继续使用")+ mangled 名/编译器版本不变。**这四项与它的"回退"一起,正是我们改走 §3.2 分层路由的原因。**
| QKKDecrypt 文件 | 可借鉴 | 不可借鉴 |
|---|---|---|
| `platforms/qq/adapter.py` | `SUPPORTED_SUFFIXES` 仅 `.mflac/.mgg/.mmp4`;前置检查项;ASCII 暂存 |
| `qq/runtime/qqmusic_decrypt.py` | `EncAndDesMediaFile` 的 3 组候选 mangled 名、NativeFunction 全 `thiscall` 签名、调用序(`Memory.alloc(0x28)` → ctor → `allocUtf16String` → `Open(..,1,0)` → `GetSize` → `Read` → dtor) | **硬编码**;整文件读入内存;未校验 `Open`/`Read` 返回值 |
| `qq/runtime/frida_decrypt_gateway.py` | 进程查找用**子串匹配** `"qqmusic"`;**每批次只 attach 一次**并缓存 session | 无 session 重连(QQ 中途重启即失效) |
| `qq/variant_adapter.py` | "路径敏感型 mflac"→**解密前先复制到纯 ASCII 路径**(`pick_safe_tmp_dir`:盘根 `_qqmusic_tmp` → 项目根 → `tempfile.gettempdir()`) | 只实装了这一个变体 |
| `qq/internal_direct.py` / `qq/export_fallback.py` | — | **存在但未接入主流程 = 死代码**,不可当作可用的回退能力承诺 |
| `platforms/netease/adapter.py` | 输出扩展白名单法 | **它没有自研 ncm 算法**——直接 `from ncmdump import NeteaseCloudMusicFile` 委托 PyPI 的 `ncmdump-py`;且 `predicted_extension()` 会**多解密一遍**(性能坑) |
| `Application/decrypt_service.py` | 事件粒度 = **逐文件 `index`/`total`**;`file_finished.result ∈ success/failed/already_decrypted` | 事件种类过多(20+) |
| `cover_art_service.py` | "本地同名图 → 缓存 → 联网"的 local-first 顺序 | **给网易云产物做封面兜底时查的是 QQ 音乐 API** |
| `THIRD_PARTY_LICENSES.md` | 合规口径与风险表述 | 内置 FFmpeg 为 `--enable-gpl --enable-version3` 构建 → 传染面比"仓库 GPLv3"更大 |
**对本文档的两处直接修正**:
1. **"输出扩展名看音频首帧魔数"得到双重印证**——QKKDecrypt 的最终扩展名同样**不取映射表**,而是 `detect_audio_container()` 从实际字节判定(`fLaC`/`OggS`/`RIFF..WAVE`/`ID3`/`0xFF 0xFB|0xF3|0xF2`/偏移 4 处 `ftyp`)。故 §3.2 的输出扩展名表仅作**声明/预期**用,实际以魔数为准。
2. **`.mgg` 解出后它强制归一为 `.m4a`**(`normalize_target_format` 把 `ogg→m4a`)。本项目**不跟**这个行为——`Cargo.toml:112` 已确认 symphonia 默认特性含 `ogg/vorbis`,直接落 `.ogg` 即可播,保持"所见即所得"(§3.1 原口径)。
3. QKKDecrypt 不支持 `.mflac0/.mgg1/.mflac1/.qmc*`——**我们的扩展面比它宽**(§4.3),但格式知识来源是 qmc-decoder 的**文档**(GPLv3,不抄代码)。
### A.2 借鉴到 P0 的一条设计(**最终未采用,附理由**)
QKKDecrypt 的 `file_finished.result` 含 `already_decrypted` 与 `stopped_by_user` 两个态。
**`stopped_by_user` 已采纳**(取消后 `finished.cancelled > 0`,任务落为"已取消")。
**`already_decrypted` 决定不做**:它要判断"某份已存在的产物是否就是本次输入的产物",
在扁平输出目录里只能靠文件名猜,猜错就静默跳过用户的文件——代价大于收益。
P0 改为**永不跳过**:目标名被占用就写 `<名>_1.<ext>`,宁可多一份产物也不丢工作。
(`ncm::unique_output` 同时处理"磁盘上已存在"与"本批次内已占用"两种情况。)