把新版 QQ 音乐下载的 musicex 文件，在本机解出可播放的音频。
macOS 实测界面：解密队列、MP3 转换、封面、歌词、实验性同步歌词与输出目录。
QM Unlock 是一个本地运行的 Rust + Tauri 桌面工具，用于处理带 musicex V1 footer 的 QQ 音乐下载文件。它支持批量拖放、自动或手动 ekey、原格式输出与 MP3 转换，也能为 MP3 补齐封面、歌词和基础音乐标签。QQ 音乐直接下载的未加密 .ogg 等普通音频也能放进同一个队列，自动跳过解密，直接转换并补全信息。
仅处理你有权访问的本地文件。项目不提供音乐下载、帐号登录或付费内容绕过功能。
- 从 Releases 下载适合自己电脑的安装包，将 macOS App 拖进「应用程序」文件夹后再打开。
- 在 QQ 音乐中登录，并下载你有权访问的
.mgg、.mflac或.mmp4文件；未加密的.ogg、.flac、.m4a、.mp3也可以一起处理。 - 将文件或整个下载文件夹拖进 QM Unlock；也可点「选择文件」或「文件夹」。加密与未加密文件不用分开，应用会按内容自动识别。
- 选择保留原格式，或转换为 MP3；按需要开启封面和歌词。
- 点击开始。完成后，文件会写到所选目录（未选时与源文件同目录）。
建议先用一首歌确认流程，再处理整个文件夹。
QM Unlock 会读取 QQ 音乐的本地登录信息来自动获取 ekey。macOS 保护这部分数据，因此第一次可能显示「需要完全磁盘访问权限」。
系统设置会自动打开，但 QM Unlock 不会自动出现在列表里。请按下面的步骤手动添加一次：
- 在「系统设置 → 隐私与安全性 → 完全磁盘访问权限」页，点击左下角 +。
- 选择「应用程序」中的 QM Unlock.app。
- 在列表里打开 QM Unlock 右侧的开关。
- 回到 QM Unlock；窗口重新获得焦点时会自动检测登录状态。
若列表中找不到它，请确认你已把 App 从 DMG 拖进「应用程序」文件夹，而不是直接在 DMG 内运行。
发布包使用 ad-hoc 签名，每个版本的签名都不同。macOS 会把旧授权绑定在旧签名上，所以更新后列表里的开关虽然还是打开的，实际已经失效，应用会继续提示需要权限或读不到登录信息。每次更新后请：
- 打开「系统设置 → 隐私与安全性 → 完全磁盘访问权限」。
- 在列表中选中旧的 QM Unlock，点击左下角 − 删除。
- 点击 +，重新选择「应用程序」中的 QM Unlock.app，并打开右侧开关。
- 退出并重新打开 QM Unlock。
macOS 不允许普通应用自行把自己加入「完全磁盘访问权限」列表或替用户打开开关；这一步必须由用户确认。
| 功能 | 说明 |
|---|---|
| 批量处理 | 支持拖入多个文件或整个文件夹，队列会显示逐文件状态与整批进度。 |
| 自动 / 手动 ekey | 默认尝试读取当前 QQ 音乐登录状态；失败时可直接粘贴你自己取得的 ekey。 |
| 原格式或 MP3 | .mgg、.mflac、.mmp4 可分别输出 OGG、FLAC、M4A，也可选择转为 MP3。 |
| 未加密音频增强 | .flac、.mp3、.m4a、.ogg、.opus、.wav 可直接补充封面和歌词，无需解密。 |
| 自动识别流程 | 加密和未加密文件放在同一个队列，共用「原格式 / MP3」选项。应用按文件内容自动处理：未加密的直接转换并补封面、歌词，加密的先解密再做同样的事。 |
| 未加密音频转 MP3 | 选择 MP3 时，未加密的 .ogg、.flac、.m4a（例如 QQ 音乐直接下载的 .ogg）会转成 MP3，并为新文件写入封面、歌词和标签。 |
| 封面与标签 | MP3 会写入歌名、歌手、专辑、专辑艺人（数据可用时）、年份、曲序、碟号及正面封面。 |
| 歌词 | 可生成同名 .lrc；「嵌入同步歌词（实验性）」会额外写入 MP3 的 SYLT 标签，默认关闭。 |
| 安全的未加密音频写入 | 保留原格式时可选原地更新或生成副本；副本和转出的 MP3 都不会覆盖源文件或同名已有文件。 |
| 下载目录监听 | 新文件稳定后自动加入转换队列，支持停止监听；仅扫描浅层目录，误选大目录会被拒绝。 |
| 跳过已转换文件 | 默认按处理记录和输出存在性跳过重复文件，可关闭以重新处理。 |
| 输出命名模板 | 内置 5 种预设，也可自定义：点按钮插入标签，实时预览，写错即时提示。 |
| 打开输出目录 | 输出卡片中的按钮，直接在文件管理器里打开输出位置。 |
| 深浅主题 | 自动跟随系统偏好，也可在右上角切换；旁边的 GitHub 图标会使用系统默认浏览器打开项目主页。 |
空队列可点「监听文件夹」。选择 QQ 音乐下载目录后，应用每 2 秒在后台检查一次；新增或修改的非空音频连续两次大小及修改时间不变、格式就绪后自动加入队列。开启监听时已有的文件不会自动重跑，可用「文件夹」手动导入。应用必须保持运行；重启后保留目录偏好，但需重新开启监听。
监听范围限制： 为避免误选大目录导致卡死，监听最多扫描 2 层子目录、2000 个条目；以 . 开头的目录及 Library、node_modules、*.app 等系统/应用目录会被跳过，磁盘根目录和用户主目录会被直接拒绝。超限时提示「目录过大」并自动停止监听，请改选具体的下载文件夹（如 QQ 音乐的 VipSongsDownload）。
监听期间输出使用独立目录或子目录；未指定独立目录时默认使用下载目录下的「QM Unlock 输出」。该输出目录及历史产物不会再次触发自动转换。正在转换时暂停轮询，之后继续发现新文件；批次串行执行。不可读或已消失的子目录会跳过，根目录暂时不可用时继续重试。文件成功扫描并入队后才确认交付；扫描或确认失败会重试，确认重试不会重复入队。缺少凭据的加密文件会留在待处理队列，登录 QQ 音乐或填写手动 ekey 后继续；全为加密文件的手动批次也会在开始前检查凭据。加密文件没有有效 musicex footer 时继续等待，不因下载暂停而提前显示失败；扩展名是 QQ 格式、内容为普通音频的文件按音频头识别。普通音频仍采用稳定性启发式，下载长时间暂停可能提前尝试，失败后可手动重试，源文件变化后也会重新检测。
「跳过已转换文件」默认开启。应用在本机保存成功处理记录，源文件大小和修改时间未变、输出选项相同且输出仍存在并非空时，结果显示「已跳过」。源文件变化、输出删除或选项改变会重新处理；递归导入中的已知产物也会跳过。对于没有处理记录的旧文件，保留源文件名时还会识别同名且格式有效的已有输出。记录不保存 ekey 或登录令牌。关闭跳过可强制处理；同名碰撞会加编号，不覆盖已有音频。
处理记录包含输入、输出的完整路径和大小/修改时间等信息，保存在 Tauri 应用数据目录中的 processing-history.json。运行中使用内存索引，批次结束时统一写入一次；载入和批次结束时清理输出已删除的记录，最多保留 10,000 条，超限淘汰最早的记录。侧栏中的「清除处理记录」会删除历史文件及缓存，音乐文件保留；目录偏好仍在 WebView localStorage 中。清除记录后，同名的已有输出仍可能被旧输出识别规则跳过，需要强制重做时关闭「跳过已转换文件」。
命名模板不带扩展名，扩展名由实际输出格式决定：
| 模板 | 示例 |
|---|---|
{artist} - {title} |
歌手 - 歌名.flac |
{album}/{track} {title} |
专辑/01 歌名.mp3 |
{albumartist}/{year} - {album}/{track} {title} |
专辑艺人/2003 - 专辑/03 歌名.flac |
{filename} |
源文件名.ogg |
选择「自定义…」后可直接编辑模板，下方按钮可一键插入标签，并显示示例预览；模板无效时无法开始处理。可用标签：
| 标签 | 含义 | 缺失时 |
|---|---|---|
{artist} |
歌手 | 未知歌手 |
{title} |
歌名 | 源文件名 |
{album} |
专辑 | 未知专辑 |
{albumartist} |
专辑艺人 | 回退为歌手 |
{year} |
发行年份（4 位） | 未知年份 |
{disc} |
碟号（从 1 起） | 1 |
{track} |
曲序（至少两位） | 00 |
{filename} |
源文件名（不含扩展名） | — |
/ |
分隔子目录 | — |
使用 / 创建子目录。元数据优先使用已匹配的 QQ 音乐曲目信息，其次是文件自带标签。缺失时的回退值见上表。文件名非法字符会替换，每个模板路径段按 UTF-8 字节截到最多 200 字节，并预留扩展名及碰撞编号空间；截断不会切断 Unicode 字符。绝对路径、.. 和未知占位符会报错。启用命名或自动监听时，普通音频也生成副本，保留源文件；歌词按最终音频文件名生成。
- 封面和歌词来自 QQ 音乐公开曲目信息的匹配结果；匹配不到时会跳过，不会强行写入疑似错误的信息。
- 开启「歌词」后，同名带时间轴的
.lrc会保留在音频旁（或你选定的歌词目录）。这是车机和多数第三方播放器最实用的方案。 SYLT是 ID3 同步歌词标准，但并非所有播放器支持；Apple Music 对本地文件的滚动歌词支持尤其不稳定，所以它是实验性开关，不默认写入。- 给 MP3 补封面和文字标签只改写标签区域，不会重新编码 MP3 音频。
- 未加密音频输出 MP3 会重新编码（LAME VBR
-q:a 2），结果写到输出目录（未选择时为源文件目录），同名文件已存在时自动命名为歌名 (1).mp3，原文件保持不变。.mp3源文件不会重复转码；.opus、.wav暂不支持转 MP3（内置的精简 FFmpeg 不含其解码器），可改选「原格式」只做增强。 - 扩展名是
.mgg、.mflac但没有 musicex footer、内容本身就是普通音频的文件，会被识别为未加密，按真实格式另存（例如歌名.ogg）后再处理。
Windows 的自动获取会读取正在运行的 QQ 音乐进程，因此 QM Unlock 必须与 QQ 音乐以同一权限级别启动：
- QQ 音乐用普通权限启动时，QM Unlock 也用普通权限启动。
- QQ 音乐若“以管理员身份运行”，QM Unlock 也需要“以管理员身份运行”。
- 权限不一致时，会提示已发现 QQ 音乐但读取不到登录信息；请统一权限后重试，或改用手动 ekey。
QQ 音乐客户端的内部存储会变化；下表记录各平台最后一次实际验证的版本，不代表对所有历史版本的承诺。
| 平台 | 最后实测日期 | 已验证 QQ 音乐版本 | 已验证范围 |
|---|---|---|---|
| macOS（Apple Silicon） | 2026-09-26 |
11.10.0（73282） |
.mgg / .mflac / .mmp4（musicex V1）的自动 ekey、解密、MP3 转换，以及封面、歌词和 MP3 标签写入。 |
| Windows x64 | 2026-10-11 |
22.7.1 |
.mgg / .mflac / .mmp4（musicex V1）的解密与转换；自动读取依赖 QQ 音乐进程，且需与 QQ 音乐以同级别权限启动。 |
当前开发分支已在 macOS Apple Silicon、macOS Intel 和 Windows x64 上完成构建验证。QQ 音乐更新后若自动获取失败，优先重新登录客户端并刷新状态；仍不行时改用手动 ekey。
| 范围 | 说明 |
|---|---|
| 支持的加密输入 | 带 musicex V1 footer 的 .mgg、.mflac、.mmp4。 |
| 支持的未加密音频 | .flac、.mp3、.m4a、.ogg、.opus、.wav，用于封面和歌词增强；其中 .ogg、.flac、.m4a 可转 MP3。 |
| 不支持 | 旧 QMC 体系：.qmc*、.bkcmp3、QTag、STag，以及任何不带 musicex V1 footer 的文件。 |
文件扩展名不是唯一依据；应用会读取文件实际 footer。下载未完成、文件损坏，或 ekey 与资源不匹配时，无法得到可用的输出。
macOS 里提示需要完全磁盘访问权限，但设置列表没有 QM Unlock
这是正常情况。点击 +，从「应用程序」选择 QM Unlock.app，再打开它右侧的开关。不要直接在 DMG 中运行 App；先拖进「应用程序」文件夹。
重新登录 QQ 音乐后，还是无法自动获取 ekey
回到 QM Unlock 后它会自动刷新状态；确认 QQ 音乐仍保持登录。若提示仍存在，直接切换到手动 ekey 模式，粘贴与当前文件匹配的 ekey。
Windows 找到 QQ 音乐但读取不到登录信息
确认 QQ 音乐正在运行且已登录；如果 QQ 音乐以管理员身份运行，QM Unlock 也需要以相同权限级别运行。客户端内部实现可能随版本变化，手动 ekey 是稳定的后备方案。
Apple Music 没有显示新封面或没有滚动歌词
Apple Music 可能缓存了旧文件信息。删除资料库中的旧条目时选择「保留文件」，然后通过「文件 → 导入」重新导入处理后的文件。它可读取普通内嵌歌词，但本地文件的滚动歌词不保证支持；车机和其他播放器优先使用同名 .lrc。
macOS 提示无法验证开发者，或 Windows 显示未知发布者
当前开发包使用 macOS ad-hoc 签名，Windows 包未使用 Authenticode 签名。请只从本仓库下载；确认来源后按系统提示继续打开。面向正式分发时仍建议使用 Developer ID 公证和 Authenticode 签名。
- 解密、转码和标签写入均在本机进行。
- 联网不限于获取 ekey：普通音频曲库匹配、命名模板所需的歌曲元数据、封面和歌词会请求 QQ 音乐服务，封面还可能请求图片服务；命名模板即使未开启封面和歌词，也可能检索曲库。服务请求会包含歌曲 MID、文件名或文件标签生成的检索词，音频文件本身不会上传。
- 自动 ekey 仅为当前任务读取 QQ 音乐本地登录状态；手动 ekey 只保留在当前运行内存，不写入任务历史、日志或配置文件。
processing-history.json保存本地文件的完整输入/输出路径、处理选项和结果，目录偏好保存在 WebView localStorage；这些路径可能包含用户名或歌曲名。可用侧栏中的「清除处理记录」删除处理历史，路径偏好仍保留。历史不保存 ekey、登录令牌或音频内容。- 不要在 Issue、PR、截图或日志中提交 ekey、
authst、QQ 号、数据库、plist、进程内存或真实音乐文件。 - 请阅读 免责声明 与 安全说明。
前置条件：Node.js 20+、Rust stable，以及对应平台的 Tauri 系统依赖。
cd desktop
npm ci
npm run tauri devcd desktop
npm run build
cargo fmt --manifest-path src-tauri/Cargo.toml --check
cargo clippy --manifest-path src-tauri/Cargo.toml --all-targets -- -D warnings
cargo test --manifest-path src-tauri/Cargo.toml发布与 CI 说明见 docs/RELEASING.md，历史变更见 CHANGELOG.md。欢迎贡献兼容性、体验和测试改进；提交前请阅读 CONTRIBUTING.md。
项目代码采用 MIT License。随包 FFmpeg / libmp3lame 按其自身 LGPL 条款分发，许可和源码说明位于 desktop/src-tauri/resources/ffmpeg。