Qqmusic Decrypt

---
name: qqmusic-decrypt
description: 解密 QQ音乐 QMC 加密歌曲（.mflac/.mflac0/.mgg/.qmcflac/.qmcogg/.tkm 等）的完整方法与提醒清单。当用户要求"解密/解析/解锁某首歌"、提供了加密音乐文件、或询问为什么某首歌解不了时，立即使用本技能。触发词：解密、解析、解锁歌曲、mflac、qmcflac、player_process_db。
---

# QQ音乐 QMC 解密

## 安装
把本技能目录复制到 `~/.claude/skills/qqmusic-decrypt/`，即可被 Claude Code 自动加载。

## 工具位置
解密工具在**独立仓库**：[github.com/mzj3920/qqmusic-decrypt](https://github.com/mzj3920/qqmusic-decrypt)（纯 Python 零依赖）。
**免安装 exe（v2.0.0，已内置 Frida 兜底与双主题界面）**：从 [Releases](https://github.com/mzj3920/qqmusic-decrypt/releases) 下载，双击即用。
本技能仓库（`qqmusic-decrypt/`）已内置拉密钥库所需的 adb / abe.jar（见 `tools/`），免下载。

```bash
# 命令行（推荐配合密钥库）
python qmc_decrypt.py --ekey-db <player_process_db路径> <歌曲文件>

# 图形界面（拖拽/选目录/进度条）
python qmc_decrypt_gui.py      # Windows 也可双击 run_gui.bat

# 自检
python qmc_decrypt.py --self-test
```

### 工具（已内置本技能，无需下载）
```text
tools\platform-tools\adb.exe   # adb（Windows，含依赖 DLL）
tools\abe.jar                  # Android Backup Extractor（Apache-2.0，非 root adb backup 解包用）
```
root 手机建议直接 `tools\platform-tools\adb.exe shell su -c ...`（见下方"从手机获取密钥库"）。
第三方组件许可证见仓库 `THIRD_PARTY_LICENSES.md`。

## 核心事实
1. **现代 QQ 音乐加密文件不带密钥**（PC 端 MusicEx / 安卓端 STag），密钥在服务器，播放时按账号实时获取。
2. **安卓端 `player_process_db` 是当前唯一可靠的密钥来源**，它缓存了歌曲密钥。
3. 数据库里两张关键表：
   - `audio_file_ekey_table`(file_path → ekey)：安卓下载的文件
   - `p2p_cache_info_table`(file_id → ekey)：**PC 下载文件的缓存密钥**，file_id 形如 `AIM0000<mid>.mflac`、`RSM1000<mid>.mflac`（不同音质前缀不同）
4. 密钥按歌曲 MID 绑定、与文件名无关；工具按文件名/MID 匹配，也能"试解全部密钥"。

## 解密流程
1. 确认加密文件在文件夹里，解析 footer：
   - `PcV1Legacy` / Android `QTag`（含内嵌 ekey）→ 直接解密
   - `PcV2MusicEx` / `STag`（无内嵌 ekey）→ 需要密钥或 Frida 兜底
2. 用 `--ekey-db <数据库> <文件>` 解密；GUI 里在"密钥库"栏选择数据库。
3. 文件名/MID 匹配不到时加 `--try-all-keys`（会试库中全部密钥）。
4. **无密钥时（Windows 优先走 Frida 兜底，无需手机/密钥库）**：
   - **GUI**：勾选「Frida 借壳兜底(需启动QQ音乐)」再开始执行（勾选框默认不勾，必须手动勾选才会走兜底）；
   - **CLI**：`python qmc_decrypt.py --frida-fallback <文件>`（不加该参数不会走兜底）；
   - 前提：QQ 音乐客户端已启动并登录（无需播放歌曲）。
   - 思路来源 yllhwa/decrypt-mflac-frida、ericjuice/music-decryptor（工具仓库 README 有致谢）；独立批量版 `frida_mode\decrypt_frida.py`。

## 从手机获取密钥库（adb）
root 手机是**最稳路径**（Magisk / KernelSU 均可）：

0. **adb 用本技能内置的**：`tools\platform-tools\adb.exe`（以下命令用 `adb` 简写，执行时替换为完整路径，或把该目录加入 PATH）。
1. 手机连电脑，开 USB 调试并授权。`adb devices` 应显示 `device`（非 `unauthorized`/空）。多设备时用 `-s <serial>` 指定。
2. 手机 QQ 音乐（**同账号**）播放目标歌曲几秒 → **强制停止** App（确保数据库写入）。
3. 用 root 拉库（su 直接 cat 到 /sdcard 再 pull，避免 Windows 下二进制经管道被 CRLF 破坏）：
   ```bash
   adb shell "su -c 'cp /data/data/com.tencent.qqmusic/databases/player_process_db /sdcard/player_process_db'"
   adb pull /sdcard/player_process_db <保存路径>/player_process_db
   adb shell rm /sdcard/player_process_db
   ```
4. **Windows Git Bash 坑**：`/sdcard/...` 会被 MSYS 改写成 `C:/Program Files/Git/...` → 命令前加 `MSYS_NO_PATHCONV=1`。
5. 验证拉取成功：`python qmc_decrypt.py --list-ekey-db <db> --find <file_id或MID>`。

### 非 root 手机（备选，常失败）
- `adb backup -f qqmusic.ab com.tencent.qqmusic`（手机点"备份我的数据"，**不勾密码**）→ `java -jar abe.jar unpack qqmusic.ab qqmusic.tar` → 抽出 `apps/com.tencent.qqmusic/db/player_process_db`。
- **已知失败点**：Android 12+ / 小米 HyperOS 会产出 **47 字节空备份**；`run-as` 报 `package not debuggable`；`/data/data/` 直接访问 `Permission denied`。遇到就改用 root 手机或 root 模拟器。
- root 模拟器（雷电/MuMu）同样适用：`adb root` 后直接 `adb pull`，无需 su。

## ⚠️ 必须提醒用户的 Checklist（按顺序）
当某首歌密钥库里没有、解不了时，按顺序做：

1. **Windows 且 QQ 音乐客户端运行中 → 优先走 Frida 兜底**（无需手机、无需密钥库）：
   GUI 勾选「Frida 借壳兜底」重试，或 CLI 加 `--frida-fallback`。
2. 兜底不可用/失败（客户端未启动、注入被拦截、客户端版本不兼容报"缺方法"）时，再走手机路线：
   a. **确认用的是最新的数据库**——文件夹里可能有多个 `player_process_db`，用修改时间最新的（例如 `player_process_db(1)`）。
   b. **在手机 QQ 音乐 App（同一账号）播放一次目标歌曲**，几秒即可——手机从服务器取密钥并缓存。
   c. **强制停止 QQ 音乐** App（设置→应用→强行停止），确保数据库写入。
   d. **重新导出 `player_process_db`** → 按上方"从手机获取密钥库（adb）"一节操作（root 手机拉库 / 非 root 备选）。
3. 把新数据库给工具，重新 `--ekey-db` 试解。

## 合并多个密钥库（避免丢 key）
不同来源（多手机/模拟器）的库可能各有对方没有的 key。以最新库为基础，用 sqlite3 把其他库的
`p2p_cache_info_table(file_id, ekey)` 和 `audio_file_ekey_table(file_path, ekey)` **INSERT OR IGNORE** 合并，
最后覆盖成默认库（旧库改名备份）。工具的 `--list-ekey-db` 只能查看、不能合并。

## 已知坑
- PC 客户端（19.57+）自身**不存明文密钥**、数据库加密（`qmlist64.db` 等是"not a database"），**无法直接从 PC 挖密钥**；只能靠手机缓存路径。
- 远古 `.qmc0/.qmc3`（2017 前，0x77 静态密钥 + 头部偏移）不被支持，会报"未识别"。
- 已解过的歌不再需要密钥，直接告诉用户去 `decrypted\` 目录取。
- 输出冲突会自动加序号（`song (1).flac`），不会覆盖。
- ⚠️ 只解密你自己合法下载、有权使用的音频文件。