kugou-unlock

Project Overview

kugou-unlock is a local decryption tool for Kugou encrypted audio, restoring encrypted files you lawfully own into standard audio. It offers both a Python desktop version and a native Android version, with core processing running offline on both. It supports .kgg, .kgm, .kgma, and .vpr, identifies formats with a content-first, filename-fallback strategy, and outputs FLAC, MP3, OGG, M4A, or WAV, optionally enriching lyrics and covers and writing tags. The Python core uses only the standard library, while the optional lyric and cover features use mutagen.

Turn locally downloaded Kugou encrypted audio back into standard audio your player can play.

Key Features

• Multi-format decryption: supports .kgg, .kgm, .kgma, and .vpr encrypted formats
• Two versions: a Python desktop version for batch processing and a native Android version that works in place on rooted devices
• Content-first detection: trusts the file header when conclusive, otherwise scans the compound suffix chain right to left for encryption markers
• Container correction: corrects the real FLAC, MP3, OGG, M4A, or WAV container from the file header
• Lyric and cover enrichment: converts KRC lyrics into UTF-8 BOM LRC files and outputs covers from database URLs as images
• Tag writing: embeds plain-text lyrics and covers into FLAC, Ogg Vorbis, and MP3 by default, using temp copies and atomic replacement
• Resume and concurrency: the auto mode decrypts all supported files concurrently and records resume progress
• External-file mode: use --external-only to generate only sidecar files without rewriting the audio

Target Audience

• Users who need to restore locally downloaded Kugou encrypted audio to a common format
• Users who want to process files in place on a rooted Android device
• Users who need to enrich local music with lyrics and covers

Quick Start

1. Put the encrypted audio to process into input/music_files/
2. For .kgg files, first export mggkey_multi_process from the device into input/key_database/
3. Run python unlock_tool.py from the command line, or install dependencies and run python unlock_gui.py
4. Take the decrypted standard audio from the output/ folder
5. For lyrics and covers, manually export the KRC cache and song database, then process with --enrich
6. If a player holds the audio and replacement fails, close the player and retry, or use --external-only first

Core Advantages

• Fully offline: both versions process everything locally and never upload files
• Robust detection: content-first with filename fallback handles compound and mislabeled suffixes
• Reliable output: decrypted results must pass an audio header check, so garbage is never written out as audio
• Complete info: beyond decryption it fills in lyrics, covers, and tags, ready for players

System Requirements

Item	Requirement
Python version	Python 3.10+ (3.11–3.14 recommended), PySide6 for the GUI
Android version	A rooted Android device
Tag writing	Requires mutagen; skip it when only generating sidecar files

Notes

• Use this tool only on local files you lawfully own, and not for any other purpose
• .kgg files must be found in the key database; an EKey not found error means you must re-export the key from a device that has played the song
• The database may contain personal information such as play records, so do not commit databases, lyrics, keys, or the generated audio
• The Android version does not provide, download, share, or maintain any public keys
• Lyric and cover enrichment requires KRC and the database to come from the same client dataset; incompatible structures raise clear errors