Metadata-Version: 2.1
Name: libtakiyasha
Version: 2.1.1.post1
Summary: 多种加密方案的 Python 实现
Author: nukemiko
License: MIT License
        
        Copyright (c) 2023 nukemiko
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/nukemiko/libtakiyasha
Project-URL: Documentation, https://github.com/nukemiko/libtakiyasha/wiki
Project-URL: Bug Tracker, https://github.com/nukemiko/libtakiyasha/issues
Project-URL: Releases, https://github.com/nukemiko/libtakiyasha/releases
Keywords: unlock,music,audio,qmc,ncm,mflac,mgg,netease,163,qqmusic
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE

# LibTakiyasha ![](https://img.shields.io/badge/Python-3.8%2B-blue)

LibTakiyasha 是一个 Python 音频加密/解密工具库（当然也可用于加密非音频数据），支持多种加密文件格式。**LibTakiyasha 不提供任何命令行或图形界面支持。**

## 使用前必读

**本项目是以学习和技术研究的初衷创建的，修改、再分发时请遵循 [License](LICENSE)。**

本项目的设计灵感，以及部分解密方案，来源于<span id='similar-projects'>同类项目</span>：

-   [Unlock Music Project - CLI Edition](https://git.unlock-music.dev/um/cli)
-   [parakeet-rs/libparakeet](https://github.com/parakeet-rs/libparakeet)

**本项目不内置任何密钥，要正常打开/保存任何类型的加密文件，你需要提供正确的对应的密钥。你需要自行寻找解密所需密钥或加密参数，在调用时作为参数传入。**

如果你要解密别人提供的文件，你可以从提供者处索要密钥，或者寻求同类项目和他人的帮助。

**LibTakiyasha 对输出数据的可用性（是否可以识别、播放等）不做任何保证。**

---

## 新变化？

请参阅[变更记录](CHANGELOG.md)。

（如果你是在 PyPI 上浏览本 README，以上链接是无效的；变更记录可能会出现在页面的底部。）

## 特性

-   使用纯 Python 代码编写
    -   **兼容 Python 3.8 及后续版本**，兼容多种 Python 解释器实现
        -   可在[此处](https://github.com/nukemiko/libtakiyasha/wiki/%E6%80%A7%E8%83%BD%E8%A1%A8%E7%8E%B0)查看具体兼容哪些实现
    -   易于阅读，方便 Python 爱好者学习
    -   （包括依赖库）无任何 C/C++ 扩展模块，跨平台性强
-   支持四种加密文件：
    -   网易云音乐加密文件 `.ncm`
    -   QQ 音乐加密文件 QMCv1 `.qmc[0-9]`、`.qmcflac`、`.qmcogg`、`.qmcra` 等
    -   QQ 音乐加密文件 QMCv2 `.mflac[0-9]`、`.mgg[0-9]` 等
    -   酷狗音乐加密文件 KGM/VPR `.kgm`、`.vpr`
        -   不支持创建新加密文件
    -   酷我音乐加密文件 `.kwm`
    -   更多信息，请参见[此处](https://github.com/nukemiko/libtakiyasha/wiki/%E6%94%AF%E6%8C%81%E7%9A%84%E6%A0%BC%E5%BC%8F%E4%BB%A5%E5%8F%8A%E6%89%80%E9%9C%80%E7%9A%84%E5%8F%82%E6%95%B0)

**注意：LibTakiyasha 的所有操作都不是线程安全的。尽量不要尝试在多线程环境下使用 LibTakiyasha 的任何功能。**

### 性能表现

参见[此处](https://github.com/nukemiko/libtakiyasha/wiki/%E6%80%A7%E8%83%BD%E8%A1%A8%E7%8E%B0)。

## 安装

可用的最新版本：2.1.1，[GitHub 发布页面](https://github.com/nukemiko/libtakiyasha/releases/tag/2.1.1)，[PyPI](https://pypi.org/project/libtakiyasha/2.1.1/)

### 安装方式

-   使用 `pip`，通过 PyPI 安装最新版本：`python -m pip install -U libtakiyasha`

如果你要下载其他版本：

-   PyPI：https://pypi.org/project/libtakiyasha/#history ，挑选自己所需的版本，下载安装包，手动安装。
    -   或者使用 pip 安装：`python -m pip install -U libtakiyasha==<你所需的版本>`
-   前往[发布页面](https://github.com/nukemiko/libtakiyasha/releases)挑选自己所需的版本，下载安装包，手动安装。

### 依赖项

LibTakiyasha 依赖以下包，均可从 PyPI 获取：

-   [pyaes](https://pypi.org/project/pyaes/) - 用于加解密 NCM 文件内嵌的主密钥和元数据
-   [mutagen](https://pypi.org/project/mutagen/) - 用于以 `mutagen` 可接受的形式导出 NCM 文件内嵌的元数据

## 如何使用？

在[这里](https://github.com/nukemiko/libtakiyasha/wiki/%E5%A6%82%E4%BD%95%E4%BD%BF%E7%94%A8%E5%8F%8A%E7%A4%BA%E4%BE%8B)可以找到使用方法和示例。

同时，在[本项目的 Wiki 主页](https://github.com/nukemiko/libtakiyasha/wiki)可以找到其他一些可能对你有用的东西。

## 常见问题

> 为什么 2.x 打开文件需要密钥，而 1.x 版本不需要？

这是出于以下考虑：

-   LibTakiyasha 是一个加解密库，当然需要为用户提供自定义密钥的权利
-   为了保护本项目不受美国<ruby>数字千年版权法<rt>Digital Millennium Copyright Act</rt></ruby>（DMCA）影响，避免仓库被误杀
    -   因此，本仓库所有 1.x 及更早版本的提交和发布版本都已删除。

## 变更记录

### 版本 2.1.1.post1

-   修复了 `import libtakiyasha` 时因为缺少数据文件而抛出 `FileNotFoundError`，从而导致 `libtakiyasha` 彻底无法使用的问题
-   将 `libtakiyasha.ncm.CloudmusicIdentifier` 加入顶层 `__init__.py` 的导入内容

在[这里](https://github.com/nukemiko/libtakiyasha/compare/2.1.1...2.1.1.post1)查看更详细的变更记录。

### 版本 2.1.1

-   修复了各个模块的文件探测函数 `probe_*()` 的类型提示，现在 `PyCharm`、`Pylance` 等 IDE 和 LSP 应该会正确识别和显示它们的参数类型和返回类型
-   修改了 `libtakiyasha.__init__` 中导入的内容：不再导入常用模块 `ncm`、`qmc`、`kgmvpr`、`kwm`、`pkgmetadata`，而是直接导入这些模块中的常用函数、方法和类，可以在只导入了 `libtakiyasha` 包后直接使用。
    -   可以在[这里](https://github.com/nukemiko/libtakiyasha/tree/3bf8bef7e3e975c73cfdc410711c224d0ff5adf1)看到 `libtakiyasha.__init__` 中导入的内容。
-   为各个模块都添加了另一个文件探测函数 `probeinfo_*()`，此函数与 `probe_*()` 不同：
    -   `probeinfo_*()` 仅在输入文件是受支持的文件类型时才会返回探测结果（`*FileInfo` 对象），否则为 `None`；
    -   `probe_*()` 始终返回一个 2 元组：
        -   如果输入了文件路径，第一个元素是输入的路径使用 `pathlib.Path` 转换过的路径对象；如果输入了文件对象，第一个元素就是输入的文件对象
        -   如果输入文件是受支持的文件类型，第二个元素是探测结果（`*FileInfo` 对象）；否则为 `None`
-   `libtakiyasha.qmc` 中作为文件探测信息容器的 `QMCv1FileInfo` 和 `QMCv2FileInfo` 已被删除，它们的作用被 `QMCFileInfo` 取代。这意味着不应该再使用内置函数 `isinstance()` 判断 QMC 文件版本，转而通过访问探测结果的 `version` 属性获得。

在[这里](https://github.com/nukemiko/libtakiyasha/compare/2.1.0...2.1.1)查看更详细的变更记录。

### 版本 2.1.0

-   减少了一些重复代码的使用，删除了大量不再使用的代码
-   优化了判断是否为 QMCv1 文件的逻辑、QMCv2 文件的主密钥探测逻辑
-   `libtakiyasha.qmc.QMCv2` 的 `open()` 和 `save()` 现在可接受多个混淆密钥，通过关键字参数 `garble_keys` 在需要时传入。
    -   **因此，上述方法中原来的关键字参数 `garble_key1` 和 `garble_key2` 已经被干掉了，请及时修改你的工具链。**
    -   如果提供此参数，需要提供一个产生至少一个混淆密钥（类字节对象）的可迭代对象（例如列表），且混淆密钥的顺序必须正确。

在[这里](https://github.com/nukemiko/libtakiyasha/compare/2.1.0rc2...2.1.0)查看更详细的变更记录。

### 版本 2.0.1 至 2.1.0rc2

在[这里](https://github.com/nukemiko/libtakiyasha/compare/2.0.1...2.1.0rc2)查看更详细的变更记录。
