kugou-unlock

项目概述

kugou-unlock 是一款酷狗加密音频的本地解密工具，用于把你本人合法持有的酷狗加密文件还原为标准音频。它同时提供 Python 桌面版和原生 Android 版，两端核心处理均离线运行。工具支持 .kgg、.kgm、.kgma 与 .vpr 等加密格式，识别采用「内容优先、文件名回退」的策略，能把结果输出为 FLAC、MP3、OGG、M4A 或 WAV，并可按需补全歌词与封面、写入标签。Python 核心仅使用标准库，可选的歌词与封面功能使用 mutagen。

把本地下载的酷狗加密音频，还原成播放器能直接播放的标准音频。

主要功能

• 多格式解密：支持 .kgg、.kgm、.kgma 与 .vpr 等酷狗加密格式
• 双端版本：Python 桌面版适合批量处理，Android 原生版可在已 root 设备上就地处理
• 内容优先识别：文件头能判断时以内容为准，不足时在复合后缀链中从右向左查找加密后缀
• 容器纠正：按文件头纠正真实的 FLAC、MP3、OGG、M4A 或 WAV 容器
• 歌词与封面补全：把 KRC 歌词转成 UTF-8 BOM 的同名 LRC，并从数据库读取封面 URL 输出为图片
• 标签写入：默认把纯文本歌词和封面嵌入 FLAC、Ogg Vorbis 与 MP3，写入采用临时副本和原子替换
• 断点与并发：自动模式可并发解密所有支持的文件并记录断点进度
• 外置文件模式：可用 --external-only 只生成同名外置文件而不改写音频

适用人群

• 需要把本地下载的酷狗加密音频还原为通用格式的用户
• 希望在已 root 的 Android 设备上直接处理文件的用户
• 需要为本地音乐补全歌词与封面的用户

快速上手

1. 把待处理的加密音频放入 input/music_files/ 目录
2. 若文件为 .kgg，需先从设备导出 mggkey_multi_process 放入 input/key_database/
3. 在命令行运行 python unlock_tool.py，或安装依赖后运行 python unlock_gui.py
4. 从 output/ 目录取得解密后的标准音频
5. 如需歌词与封面，手动导出 KRC 缓存与歌曲数据库后，用 --enrich 参数处理
6. 播放器占用音频导致替换失败时，关闭播放器后重试，或先使用 --external-only

核心优势

• 全程离线：两端核心处理均在本地完成，不上传文件
• 识别稳健：内容优先、文件名回退，复合后缀与错标后缀都能正确识别
• 结果可靠：解密结果必须通过音频文件头校验，不会把乱码冒充音频写出
• 信息完整：不仅能解密，还能补齐歌词、封面与标签，播放器直接可读

系统要求

项目	要求
Python 版	Python 3.10+（推荐 3.11–3.14），GUI 需 PySide6
Android 版	已 root 的 Android 设备
标签写入	需 mutagen，仅生成外置文件时可不装

注意事项

• 本工具仅用于处理你本人合法持有的本地文件，请勿用于其他用途
• .kgg 需要在密钥库中找到对应 hash，出现 EKey not found 时需从播放过该曲的设备重新导出密钥
• 数据库可能含播放记录等个人信息，请勿提交数据库、歌词、密钥或生成的音频
• Android 版不提供、下载、分享或维护任何公共密钥
• 歌词与封面补全要求 KRC 和数据库来自同一客户端数据集，结构不兼容时会明确报错