um-react/README.MD

Unlock Music 音乐解锁 (React)

• 在浏览器中解锁加密的音乐文件。 Unlock encrypted music file in the browser.
• Unlock Music 项目是以学习和技术研究的初衷创建的，修改、再分发时请遵循授权协议。
• Unlock Music 的 CLI 版本可以在 unlock-music/cli 找到，大批量转换建议使用 CLI 版本。
• 我们新建了 Telegram 群组 @unlock_music_chat ，欢迎加入！
• CI 自动构建已经部署，可以在 UM-Packages 下载 目前还没有自动构建

支持的格式

• QQ 音乐 QMCv1 (.qmc0/.qmc2/.qmc3/.qmcflac/.qmcogg/.tkm)
• QQ 音乐 QMCv2 PC 端 (.mflac/.mgg/.mflac0/.mgg1/.mggl)
• 网易云音乐 (.ncm)
• 虾米音乐 (.xm)
• 酷我音乐 (.kwm)
• 酷狗音乐 (.kgm/.vpr)
• 喜马拉雅 Android 端 (.x2m/.x3m)
• 咪咕音乐格式 (.mg3d)
• QQ 音乐海外版JOOX Music (.ofl_en)

开发相关

安装依赖

• 安装 Node v16.17 或更高，推荐当前最新的 Node LTS 版本。
• 安装/激活 pnpm：corepack prepare pnpm@latest --activate ¹
• 安装软件依赖：pnpm i --frozen-lockfile

本地运行

⚠️ 先完成安装依赖部分，然后继续。

pnpm start

然后根据提示打开项目所在页面即可。

构建生产版本

⚠️ 先完成安装依赖部分，然后继续。

pnpm build

如果需要预览构建版本，运行 pnpm preview 然后打开项目所在页面即可。

架构

• 浏览器主线程: 渲染界面，处理 UI 更新
• Web Worker: 负责计算方面的内容，如内容解密。

数据传输: 生成 blob url (URL.createObjectURL) 然后透过 postMessage 传递给线程，线程利用 fetch API 来获取文件信息。

基于 libparakeet SDK 开发

libparakeet-js 编译目前需要 Linux 环境，请参考仓库说明。

该文档将假设这两个项目被放置在同级的目录下：

~/Projects/um-projects
    /um-react
    /libparakeet-js

若为不同目录，你需要调整 LIB_PARAKEET_JS_DIR 环境变量到仓库目录，然后再启动 vite 项目。

初次构建

• 进入上层目录 cd ..
• 克隆 libparakeet-js 仓库 (目前需要 Linux 环境, Windows 下推荐使用 WSL2)
  • git clone --recurse-submodules https://github.com/parakeet-rs/libparakeet-js.git
• 进入目录 cd libparakeet-js
• 如果需要更新 submodule:
  • git submodule update --init --recursive
• 运行 ./build.sh -j 4 进行编译
• 编译 js-sdk:
  • 进入 npm 目录: cd npm
  • 安装依赖: pnpm i --frozen-lockfile
  • 构建: pnpm build

做出更改

做出更改后，参考上面的内容进行重新编译

应用 SDK 更改

将构建好的 SDK 直接嵌入到当前前端项目：

pnpm link ../libparakeet-js/npm

※ 建立 PR 时，请先提交 SDK PR 并确保你的更改已合并。

贡献代码

欢迎贡献代码。请确保：

• 单元测试的覆盖率不低于主分支的覆盖率；
• 提交前请使用 Prettier 对代码进行格式化；
• 提交前请确保 ESLint 不会报告 warning / error；

满足上述条件后发起 Pull Request，仓库管理员审阅后将合并到主分支。

TODO

• #6 文件拖放 (利用 react-dropzone?)
• 各类算法 追踪 crypto 标签
• #7 简易元数据编辑器
• ~#8 添加单元测试~ 框架加上了，以后慢慢添加更多测试即可。
• ~#2 解密内容探测 (解密过程)~

---

1. 参考 pnpm 说明 https://pnpm.io/zh/installation#使用-corepack-安装 ↩︎