# kgm_decoder_py

**Repository Path**: DYXMXM/kgm_decoder_py

## Basic Information

- **Project Name**: kgm_decoder_py
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-04-02
- **Last Updated**: 2025-05-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Kugou KGM/VPR 解码器（Python 版本）

[![许可证](https://img.shields.io/badge/license-Anti%20996-blue.svg?style=flat-square)](LICENSE_CN)
[![语言](https://img.shields.io/badge/lang-python-brightgreen?style=flat-square)](https://www.python.org)

## 简介

这是一个用 Python 编写的命令行工具，用于解码酷狗音乐加密/混淆的音乐文件（如 `.kgm`、`.vpr` 或缓存文件）。

这是 Rust 项目 [ghtz08/kuguo-kgm-decoder](https://github.com/ghtz08/kuguo-kgm-decoder) 的 Python 移植版。解码原理基于原项目 README 中记录的发现，主要来自[孤心浪子的博客文章](https://www.cnblogs.com/KMBlog/p/6877752.html)和 [ix64](https://github.com/ix64) 的 [unlock-music 项目](https://github.com/ix64/unlock-music)。

**注意：** 本项目大部分代码逻辑都是借鉴自 [ghtz08/kugou-kgm-decoder](https://github.com/ghtz08/kugou-kgm-decoder)，仅将其移植到 Python 环境。

感谢 [ix64](https://github.com/ix64) 提供的用于解码的公钥。

## 系统要求

* Python 3.3+（使用内置的 `lzma` 和 `argparse`）
* `kugou_key.xz` 文件（必须放置在 `kgm_decoder/assets/` 目录中）

## 安装/设置

1. 克隆此仓库。
2. 确保原始 Rust 项目 `src/assets` 目录中的 `kugou_key.xz` 文件被复制到本 Python 项目的 `kgm_decoder/assets/` 目录中。
3. （可选）创建虚拟环境：
   ```bash
   python -m venv venv
   source venv/bin/activate  # 在 Windows 上使用 `venv\Scripts\activate`
   ```

## 使用方法

您可以直接使用 `main.py` 脚本运行解码器：

```bash
python -m kgm_decoder.main <参数>
```

如果您设置了入口点（例如，使用 `setup.py`），您可能会安装它并将其作为命令运行。

**示例：**

* 解码单个文件：
  ```bash
  python -m kgm_decoder.main /path/to/your/song.kgm
  ```

* 解码目录中的所有文件（非递归）：
  ```bash
  python -m kgm_decoder.main /path/to/your/music_folder/
  ```

* 递归解码目录及其子目录中的所有文件：
  ```bash
  python -m kgm_decoder.main -r /path/to/your/music_folder/
  ```

**命令行选项：**

| 参数           | 简写  | 描述                        |
| :------------- | :---- | :-------------------------- |
| `target`       |       | 要处理的目标文件或文件夹    |
| `--recursive`  | `-r`  | 递归处理文件和目录          |
| `--keep-file`  | `-k`  | 解码后保留原始加密文件      |
| `--help`       | `-h`  | 显示帮助信息并退出          |
| `--version`    |       | 显示程序版本号并退出        |

> **注意：** 解码后的输出文件将具有 `.mp3` 扩展名，但根据原始源，实际的音频格式可能会有所不同（例如，M4A、FLAC 等）。未来的改进可能涉及检测实际格式。

## 许可证

[Anti 996 License Version 1.0](LICENSE_CN)

---

# Kugou KGM/VPR Decoder (Python Version)

[![License](https://img.shields.io/badge/license-Anti%20996-blue.svg?style=flat-square)](LICENSE_CN)
[![Lang](https://img.shields.io/badge/lang-python-brightgreen?style=flat-square)](https://www.python.org)
[![GitHub stars](https://img.shields.io/github/stars/yourusername/kgm-decoder-python?style=flat-square)](https://github.com/yourusername/kgm-decoder-python/stargazers)

## Introduction

A command-line tool, written in Python, to decode encrypted/obfuscated Kugou music files (like `.kgm`, `.vpr`, or cache files).

This is a Python port of the Rust project [ghtz08/kuguo-kgm-decoder](https://github.com/ghtz08/kuguo-kgm-decoder). The decoding principles are based on the findings documented in the original project's README, primarily from [孤心浪子's blog post](https://www.cnblogs.com/KMBlog/p/6877752.html) and the [unlock-music project](https://github.com/ix64/unlock-music) by [ix64](https://github.com/ix64).

**Note:** Most of the code logic in this project is adapted from [ghtz08/kugou-kgm-decoder](https://github.com/ghtz08/kugou-kgm-decoder), ported to Python environment.

Thanks to [ix64](https://github.com/ix64) for the public key used in decoding.

## Requirements

* Python 3.3+ (uses built-in `lzma` and `argparse`)
* The `kugou_key.xz` file (must be placed in `kgm_decoder/assets/`)

## Installation / Setup

1. Clone this repository.
2. Ensure the `kugou_key.xz` file from the original Rust project's `src/assets` directory is copied into the `kgm_decoder/assets/` directory within this Python project.
3. (Optional) Create a virtual environment:
   ```bash
   python -m venv venv
   source venv/bin/activate  # On Windows use `venv\Scripts\activate`
   ```

## Usage

You can run the decoder directly using the `main.py` script:

```bash
python -m kgm_decoder.main <arguments>
```

Or, if you set up entry points (e.g., using `setup.py`), you might install it and run it as a command.

**Examples:**

* Decode a single file:
  ```bash
  python -m kgm_decoder.main /path/to/your/song.kgm
  ```

* Decode all files in a directory (non-recursive):
  ```bash
  python -m kgm_decoder.main /path/to/your/music_folder/
  ```

* Decode all files in a directory and its subdirectories:
  ```bash
  python -m kgm_decoder.main -r /path/to/your/music_folder/
  ```

**Command-line Options:**

| Argument        | Short | Description                                  |
| :-------------- | :---- | :------------------------------------------- |
| `target`        |       | The target file or folder to be processed    |
| `--recursive`   | `-r`  | Process files and directories recursively    |
| `--keep-file`   | `-k`  | Keep the original encrypted file after decoding |
| `--help`        | `-h`  | Show the help message and exit               |
| `--version`     |       | Show program's version number and exit       |

> **Note:** The decoded output file will have a `.mp3` extension, but the actual audio format inside might vary (e.g., M4A, FLAC, etc.) depending on the original source. Future improvements could involve detecting the actual format.

## Contributing

Contributions are welcome! Here are some ways you can contribute:

1. Report bugs or request features by opening issues
2. Submit pull requests to fix issues or add new features
3. Improve documentation
4. Share the project with others who might find it useful

## License

[Anti 996 License Version 1.0](LICENSE_CN)