50 KiB
音乐模块 · 本地音乐解密规划(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. 结论先行
- 范围收敛到两平台(本轮显式指定):网易云
.ncm+ QQ音乐 QMC 系列。酷狗/酷我明确出栈,不进任何分期。 - 两条技术路线,全部纯 Rust,零新增运行时依赖:
- ncm → Rust 原生(
aes 0.8/cbc 0.1/base64 0.22已在依赖;ecbcrate 不在依赖树,ECB 手写 16 字节块循环,零新增 crate)。 - QQ → Rust 原生三层路由(详见 §3.2):① 尾部内嵌 ekey 的文件纯离线可解;② musicex 文件读本机凭据调
GetEVkeyAPI;③ 前两层都不成立才用 Frida 注入兜底。 - 本节原有的「Frida 主链」判断已作废:它把「需要客户端在跑」与「需要 Frida 注入」绑成了一件事。实际只有第③层需要注入,而前两层覆盖绝大多数真实文件。改分层后不再需要便携 Python、不再需要
pip install frida、不再受杀软与 mangled 符号版本漂移影响。
- ncm → Rust 原生(
- UI 是音乐模块第 4 个页签「解密」:
useModuleTabs加一项 +DecryptPanel.vue+ 独立轻量 store,命令与事件挂进现有 music 命令族,完全照抄下载任务的「先回 taskId、进度走事件」范式。 - 许可边界分三档:
ncmdump是 MIT,可逐行对照;QKKDecrypt 与qmc-decoder是 GPLv3 + FFmpeg GPL,只沉淀格式/协议知识与坑清单,实现逐行重写。 - 工作量:P0(网易云 + 页签全链路)约 2 个工作日;P1a(QQ 离线 + API,纯 Rust)约 2~3 个工作日;P1b(Frida 兜底,按需)另计。
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):
- 尾部检测:读末 8 字节,为
"musicex\0"即 musicex;再向前读footer_size + 8解析完整 footer(0x00song_id u32LE、0x0Cmedia_mid UTF-16LE 60B、0x48filename UTF-16LE 68B、0xC0footer_size、0xC8magic)。 - 取
uin:读%APPDATA%\Tencent\QQMusic\QQMusicServiceConfig.ini的[Account] Uin(明文 INI)。 - 取
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 秒。 - 调 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 命令
// 任务
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 处(实测仓库现状):
music/mod.rs的pub use commands::{...}re-export(约mod.rs:48);lib.rs的collect_commands内,lib.rs:205);lib.rs的generate_handler内,lib.rs:348)。 漏第 2 处 = 运行时能调但bindings.ts缺类型;漏第 1、3 处 = 编译失败或调用失败。
- 前端沿用本模块既有范式(
musicStore.ts全用原生invoke+ 手写类型,不用commands),故解密 store 同样用invoke。
4.2 事件 music-decrypt-event(登记进 constants.rs 音乐分组)
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 状态卡里的文案一致):
- 在电脑上启动 QQ 音乐客户端(Windows 版)。
- 用它登录你的账号,并保持客户端开着(
authst只存在于运行期内存)。 - 回到「解密」页点「重新检测」,状态变为「已就绪」即可解密 musicex 文件。
- 若提示未取到登录令牌:先在客户端里播放任意一首歌触发一次网络请求,再重新检测。
- 仍失败则试过以管理员身份运行本应用(读其他进程内存可能需要更高权限)。
- 登录令牌约 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):
- 读 8 字节魔数,命中
CTENFDAM→ 网易云; - 否则读尾部判 QMC 形态:后缀在 QMC 家族里 → QQ音乐;
- 后缀不认识时,只有明确的尾部形态(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 的条目号)
aes 0.8只有块原语、ecbcrate 不在依赖树:ECB 手写 16 字节块循环(cipher::BlockDecrypt::decrypt_block)。不要为此引入ecbcrate。- 两段 XOR 常量不同(
0x64key /0x63meta)。照抄成同一个常量 = 必然失败。 - PKCS#7 风格 padding:AES-ECB 收尾取最后一字节为 padding 长度(
> 16视作 0),不是“去前缀”。 - 改性 RC4 KSA 的
last_byte累加(照抄参考实现即可,但别误解它): 式子c = (swap + last_byte + key[key_offset]) & 0xff在模 256 下恰好化简为标准 RC4, 实测两者密钥盒逐字节相同(256/256)。因此它不是"与标准 RC4 的关键差异", 也不能靠与标准 RC4 比对来验证实现——验证只能靠固定向量(见 §6.25)。key_offset触 keyLen 归零循环取 key 这一点照抄。 - 音频块之间不跳字节,
0x8000只是块大小;i是块内下标。原文档的"每 0x8000 跳过 5 字节"是错的(那 5 字节在 §① 的头部里,且已单独处理)。但块边界必须由"读满一块"确定,不能用Read::read的短读结果(见 §6.24)。 - 输出扩展名看音频首帧魔数(
ID3→.mp3,否则.flac),不看 meta 的format。 实现比这条更宽一点:还识别fLaC/OggS/RIFF..WAVE/ftyp/wvpk, 给 P1 的 QQ 产物复用(ncmdump 的兜底同为 flac)。 - meta 段是两层前缀:先剥 22 字节
163 key(Don't modify):,再 base64,再 AES,再剥 6 字节music:。 - 流式处理:
0x8000块逐块读→解→写,禁止整文件读入内存(.mmp4可能很大)。大文件下需按已处理字节数推progress。 - 单测不依赖真实样本:真实 FLAC 最小样本进不了仓库。改为对中间产物断言——AES-ECB 往返、KSA 密钥盒已知值、padding 剥离、魔数→扩展名判定、以及"自造一个合法 ncm 容器(用同一套算法正向构造)再解回来"的往返测试。真机样本走手动自测。
- 魔数/解析失败走 per-file
Err,不 panic、不中断整批。
QQ(P1)
- 第①层(QTag / V1)完全离线,不要因为"QQ 文件"就先去连客户端——先用尾部分支判形态再决定要不要读凭据。
- 第②层的
authst只在QQMusic.exe运行期内存里,不落盘;uin在QQMusicServiceConfig.ini可明文读。MEMORY_BASIC_INFORMATION的 2 字节PartitionId(Win10 1803+)必须包含,否则state会读成protect、所有内存区被跳过。 - API 三处必须:
filename带.mgg/.mflac后缀、songtype = 1、module = music.vkey.GetEVkey(不是GetVkey)。否则104005或 ekey 为空。 authst约 22.3 小时过期:失败文案要给"重新登录 QQ 音乐"的出口,而不是只报网络错误。- 第③层(Frida):必须先启动 QQ 音乐再 attach,
QQMusicCommon.dll打开主界面即加载;导出符号是 mangled name,按子串EncAndDesMediaFile模糊匹配,严禁硬编码地址或 RVA;被杀软拦截只给排除指引,不做反检测动作;批量时客户端 UI 可能短暂卡顿,属预期。 path_sensitive_mflac变体(同名文件不同目录内容不同)P1 不处理:报错带全路径,遇到再迭代。.mmp4产物容器未证实,P1 先用真机样本确认再定(见 §3.2 末)。
工程
- 新命令登记 3 处:
music/mod.rsre-export、lib.rs的collect_commands![]、lib.rs的generate_handler。 music-decrypt-event常量进constants.rs音乐分组;前端沿用硬编码字符串(与musicStore.ts:419一致)。- 解密 store 必须独立于组件生命周期:Tabs 非 active 会卸载内容,事件监听挂 store 不挂组件。
- 输出同名去重 + 输入输出相交保护(见 §4.4)——原文档缺失,不做会静默覆盖用户文件。
- 三层路由后不再需要便携 Python 与 frida,
music_decrypt_install_deps命令取消;QQ 未登录的错误出口走状态卡提示。
实施中新增确认的坑(2026-09-27 实测)
- 事件字段名是 snake_case(不是 camelCase)。
#[serde(tag = ..., rename_all = "kebab-case")]只作用于 tag,变体字段名原样输出。前后端不一致时不报错,只表现为进度不动。 Rust 侧event_json_contract单测钉死 JSON 形状。 - 音频块边界必须用"读满一块"而非
Read::read的返回值。BufReader::read会短读, 块边界一漂移,解密式里的「块内偏移i」就与加密侧错位,表现为文件从中间某处起全是噪声 (实测首个坏字节落在 32418,仍在第一大块内),前半段却完全正常,极难排查。 已加read_full()专门处理。 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)。
MODIFY_KEY是 16 字节而非 17(aes::Aes128的密钥长度就是 16);CORE_KEY的 17 字节是解密后要剥掉的前缀,与 AES 密钥不是同一个东西 (AES 密钥是它的前 16 字节)。两者混用不会编译报错,只会全解错。- 合成容器单测的 key 段必须带
neteasecloudmusic前缀——否则解密端剥前缀后拿到错种子。 这个坑一度被"单循环 KSA"的错误实现掩盖(两边同时错、往返仍然自洽)。
P1a(QQ 离线)实施中新增确认的坑
- QMC2 Map 密码的
scramble必须用wrapping_shl/shr(对移位量取模), 不能写成u8::rotate_left/rotate_right——后者会在内部再取一次模,结果不同。 被 Apache 参考实现的原向量抓到(若不比对向量,会产出"能跑但全错"的解密)。 - tc_tea 不是 TEA-ECB,而是 TEA 变体 + 自定义 CBC:块与密钥字都是大端、
16 轮(非 32)、单轮是
((v<<4)+k1) ^ (sum+v) ^ ((v>>5)+k2), 且明文前置1+pad+2字节头、尾部 7 字节 0 自校验。照 TEA-ECB 写会解出部分可读的乱码 (表现极具迷惑性:能看到明文碎片)。尾部 0 校验正是"密钥对不对"的权威判据。 - V1 尾部判定不能只看长度:任意加密数据末尾都可能凑出
0<n<=0x400, 只按长度判会把普通 QMC1 文件误判成 V1 并砍掉一大截音频(实测 32871 字节 → 4096)。 必须追加"前面那一段像不像 base64 ekey"的校验。 sniff_tail的audio_len必须换算成绝对长度:它只读了尾部 probe,detect_tail给出的是相对 probe 起点的偏移;QMC1(无尾部)必须回落到整个文件大小。 另外不要在两个地方各写一遍尾部探测——当初decrypt_file自己复制了一遍, 修了sniff_tail却没修它,症状是"探测结果对、实际产物只有 4KB"。- QMC1 的掩码分支是
pos > 0x7FFF(严格大于),不是>=;写成>=会在回绕点差一字节。
P1c(musicex 在线)实施中新增确认的点
MEMORY_BASIC_INFORMATION的PartitionId(Win10 1803+):直接沿用windows-sys的结构体即可,但自己手写#[repr(C)]时千万别漏——漏了会让RegionSize/State/Protect全部读错偏移,VirtualQueryEx返回的State读成Protect(如0x04而非0x1000),于是所有内存区被跳过、永远扫不到 token。getEVkey的三个"必须":filename带扩展名、songtype=1、module=music.vkey.GetEVkey(不是GetVkey)。任一写错都只是"拿不到 ekey", 不会报错——所以请求体用纯函数组装并单测锁死(qq_ekey::build_evkey_request)。authst会过期(约 22.3 小时):失败文案必须给"重新登录 / 重新检测"的出口, 否则用户会以为是网络问题。响应里的expiration已带进产物备注。- 单元测试不要真的发网络请求:本机一旦登录成功,测试就会去连 QQ 服务器,
导致测试变慢变脆。改为验证"请求体能正确构造"+"
#!Qk头守卫"+"尾部能被解析出media_mid/filename"三段——真实响应留给真机端到端。 - musicex 音频段要校验
#!Qk头:尾部像 musicex 不代表内容真是 QMC2 密文; 没有这道守卫会把任意文件"解"成垃圾却报告成功。
真机端到端验证后修正(2026-09-27)
#!Qk不是 QMC2 密文的通用魔术(推翻第 37 条的做法):真机 musicex 样本 (Avicii - Heaven,197MB.mflac)的密文头是51 74 03 75,按"必须以#!Qk开头"写的守卫会把完全合法的文件误拒。 正确做法是用解密结果判定密钥是否正确:用取到的密钥解出前 16 字节, 看是否是已知音频魔术(fLaC/OggS/ID3/ftyp…)——密钥错时它是随机噪声, 几乎不可能凑巧命中;命中即说明密钥对、文件也对。 这也是"内容优先"原则的又一次应用:不要用猜测的密文特征做判据,要用能验证的结果。- 文档给的 musicex 字段偏移在真样本上是对的:
0x0Cmedia_mid(60B UTF-16LE)、0x48filename(68B UTF-16LE)、0xC0footer_size、0xC8magic 全部命中, 尾部实测 192 字节、padding 区有 13 个非零字节(所以不能假设 padding 全 0)。 - 真机样本的规模提醒:
.mflac可达 197MB / 192kHz / 24bit。qq_online目前把音频段整段读入内存再解密(探针与生产路径都是), 在这个量级下可用,但如果将来遇到多 G 的文件,应改成分块解密 + 流式写盘 (qmc的流密码本身已支持任意偏移)。
7. 分阶段计划
P0 — 网易云 + 解密页签全链路(约 2 天)✅ 已实施(2026-09-27)
useModuleTabs+TabsContent接「解密」页签;index.ts搜索条目decrypt/ncm.rs:§3.1 全部要点 + 单测(18 项通过)decrypt/mod.rs+commands.rs:run / cancel + 事件发射;三处登记;constants.rs事件常量decryptStore.ts+DecryptPanel.vue:选文件 → 批量任务 → 进度 → 打开输出目录- 输出同名去重 + 输入输出相交保护(§4.4)
- 封面单独落盘(
<歌名>.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)
decrypt/qmc.rs:QMC1 静态密钥表 / QMC2 Map 密码 / QMC2 RC4 变体 / tc_tea(TEA 变体 + 自定义 CBC)- 第①层:QTag 与 V1 尾部 ekey 提取 → 离线解密
decrypt/scan.rs:递归扫描 + 内容优先的平台路由 + 保留相对目录结构- 文件夹批量:
folder/root/in_place三个参数 +music_decrypt_scan预览命令 decrypt/common.rs:两引擎统一的错误类型、魔数定格式、同名去重、读满一块- 单测 56 项(模块合计 174 项全库通过),含参考实现的原始测试向量
- 第②层 musicex +
GetEVkeyAPI(未实施,见 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(✅ 已实施)
qq_footer.rs:musicex 尾部解析(song_id / media_mid / filename)qq_credentials.rs:读%APPDATA%\Tencent\QQMusic\QQMusicServiceConfig.ini的uin+ 扫进程内存取authstqq_memscan.rs(Windows):CreateToolhelp32Snapshot+OpenProcess+VirtualQueryEx+ReadProcessMemory(只读)qq_ekey.rs:GetEVkey请求组装与响应解析(filename带扩展名 /songtype=1/platform="27")qq_online.rs:编排 +probe_status()在线能力探测music_decrypt_qq_status命令 + UI 状态卡(含逐步操作说明)windows-sys增开Win32_System_Diagnostics_ToolHelp与..._Debug- 本机实测:
probe_status()返回running=true logged_in=true uin=1154027699 ready=true—— 内存扫描确实取到了authst - 端到端已用真机样本跑通(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 端到端 | 保留 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 预览数量 |
开放问题:
- 解密输出默认就地(文件夹批量)或
savedir/decrypted/(散选);独立设置项留 P2。 - QQ 未运行时是否自动拉起?离线层与
.ncm完全不需要客户端;只有 musicex 需要, 当前选择"只提示、不自动拉"(客户端要登录,自动拉起也解决不了登录态)。 .mmp4的产物容器(m4a / mp4)待真机样本确认——当前靠首帧ftyp魔数判定,认不出时按后缀落m4a。 (.mflac已实测确认:产物为 192kHz/24bit 的.flac。)musicex 端到端未验证已解决(2026-09-27,真机样本跑通,见 P1c 的验证记录)。.mflac0/.mgg1等变体按 QMC2 处理,但未用真实样本验证过其尾部形态与.mflac/.mgg一致。- 微信登录的 QQ 音乐 (
tmeLoginType=3):实现上authst与 QQ 登录通用, 但login_type目前固定发1(QQ 登录实测可用)——若真机发现微信登录取不到 ekey,需按凭据来源推断。 - 大文件内存占用:
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"更大 |
对本文档的两处直接修正:
- "输出扩展名看音频首帧魔数"得到双重印证——QKKDecrypt 的最终扩展名同样不取映射表,而是
detect_audio_container()从实际字节判定(fLaC/OggS/RIFF..WAVE/ID3/0xFF 0xFB|0xF3|0xF2/偏移 4 处ftyp)。故 §3.2 的输出扩展名表仅作声明/预期用,实际以魔数为准。 .mgg解出后它强制归一为.m4a(normalize_target_format把ogg→m4a)。本项目不跟这个行为——Cargo.toml:112已确认 symphonia 默认特性含ogg/vorbis,直接落.ogg即可播,保持"所见即所得"(§3.1 原口径)。- 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 同时处理"磁盘上已存在"与"本批次内已占用"两种情况。)