MusicUnlock 多平台加密音乐格式转换工具

基于 Kotlin + Compose Multiplatform 的桌面工具，将网易云/QQ音乐/酷狗/酷我等平台的加密音乐格式转换为标准音频格式（mp3/flac/ogg/m4a 等），带现代桌面 GUI 与命令行批量转换。WAV、FLAC、APE、MP3 等常见原始音频也能直接作为输入转码。

仅供学习与技术交流，请勿用于商业用途，请在合法范围内使用。

界面预览

纯净白 · 精密工具风格：近白底、白色卡片、发丝线分隔，品牌橙单点强调；格式徽章按平台家族着色，状态一眼可读。

浅色 · 转换工作区	深色 · 转换工作区

网易云下载 · 登录	QQ 音乐下载 · 登录

功能特性

• 覆盖网易云 / QQ音乐 / 酷狗 / 酷我四家主流平台的加密格式
• 自动识别解密后的真实音频格式（MP3/FLAC/OGG/M4A/WAV 等），保留内嵌标签与封面；NCM 额外写回歌名/歌手/专辑/封面
• WAV、FLAC、APE、MP3 等常见原始音频无需解密即可作为输入，与加密格式共用同一条转码管线：套用输出格式、码率、命名模板与内容去重
• 随应用分发当前平台的 ffmpeg 运行库，MP3 转码开箱即用，无需额外安装
• 深/浅双主题一键切换
• 拖拽或点击添加文件/文件夹，队列内逐文件显示格式、大小与状态
• 队列支持逐首勾选（全选 / 清空），只转换勾选的文件
• 默认跳过输出目录中已存在的同名同格式文件，也可切换为强制重新转换
• 输出格式支持原始格式、MP3、FLAC、M4A、OGG、Opus 与 WAV，并可为本地转换设置命名模板和跳过/另存/覆盖策略
• 按解密后音频内容做 SHA-256 去重（保留不带 (N) 后缀的文件）
• 设置自动保存到 ~/.musicunlock/config：输出目录、整理规则、下载策略、歌单追更和窗口大小都会在重启后继续使用；登录 Cookie 单独保存在系统凭据库
• 网易云下载：扫码 / 短信验证码 / 浏览器三种方式登录 → 查看并多选歌单 → 加入下载队列并按设置保留原始音质或转 MP3（写回完整标签与封面）
• QQ 音乐下载：扫码 / 浏览器两种方式登录（浏览器不可用时可直接粘贴 Cookie）→ 查看并多选歌单 → 加入下载队列并按设置保留原始音质或转 MP3（写回完整标签与封面）
• 酷狗下载：扫码 / 浏览器登录（支持手动粘贴 Cookie）→ 查看并多选收藏与创建的歌单 → 加入下载队列
• 酷我下载：浏览器登录（支持手动粘贴 Cookie）→ 查看并多选收藏与创建的歌单 → 加入下载队列
• 歌单导入：粘贴网易云、QQ、酷狗或酷我的歌曲/歌单/专辑/歌手链接，自动勾选队列中命中的本地文件，未命中的曲目逐条列出
• 启动时检查 GitHub Releases 的正式版本，发现更新时在内容区顶部提示，可直接跳转下载页
• 下载任务中心：歌曲级并发队列，支持暂停、继续、取消、失败重试、断点续传、实时速度与剩余时间，应用重启后自动恢复未完成任务
• 本地与在线统一任务中心：本地转换同样支持持久化、暂停、继续、取消、失败重试和重启恢复，并自动登记到曲库索引
• 下载预检：加入队列前检查播放地址、音质、版权限制、预计体积和输出磁盘空间
• 下载输出策略：跳过、覆盖、另存或升级同名文件，可配置并发数、重试次数、限速、代理和超时
• 文件组织模板：支持 {artist}、{album}、{title}、{track:02}、{disc}、{year}、{genre}、{platform}、{quality}、{bitrate} 等变量
• 完整标签与歌词：写入音轨/碟号、年份、流派、作曲、ISRC、封面和 LRC，可嵌入音频、生成同名 .lrc，并可选生成 cover 与 M3U8
• 曲库整理：扫描本地曲库，检测重复、损坏、缺封面、缺歌词和缺标签；重复文件先生成清理计划，可区分精确/疑似重复并移入可撤销回收站
• 重复文件审阅：逐组并列保留与移除版本，展示格式、码率、体积、封面和歌词差异，确认后再移入回收站
• 曲库浏览与导出：支持搜索、单曲标签编辑、批量重命名，并导出 M3U8 / CSV
• 批量标签工作台：勾选多首后可按字段批量写入标题/歌手/专辑/歌词/封面等标签，只覆盖勾选的字段，未勾选的内容保持不变，并支持一键撤销
• 歌单追更：保存歌单同步计划，周期检查远端变化并只下载本地缺失歌曲
• 搜索与链接：四平台统一搜索，粘贴单曲、歌单、专辑、歌手分享链接即可加入队列；可按 ISRC、歌名、歌手与时长寻找跨平台版本
• 内置播放器：搜索结果可直接试听，支持全局播放队列、上一首/下一首、暂停、停止、进度跳转和音量控制
• 搜索结果一键下载 MP3：正常解析并下载平台音频后，自动走内置 ffmpeg 转为 MP3 并写入标签、封面和歌词
• 跨平台源回退：主平台因版权、登录或服务异常失败时，自动匹配其他平台并转入新的下载任务
• 自动收件箱：监听指定文件夹，新出现的加密歌曲自动转换
• 自动化规则：按监听目录、扩展名、文件大小匹配规则，分别设置输出目录、格式、码率和命名模板，并可安全回收已转换源文件
• 无窗口守护进程：--daemon 可长期运行收件箱监听、歌单追更和本机自动化 API
• 本机 API：仅在 127.0.0.1 暴露健康检查、任务查询、扫描、追更和批量转换接口，并使用 Token 鉴权
• 后台与启动：支持开机启动、托盘常驻、歌单追更结果通知和错过周期后的补同步
• 桌面集成：系统托盘、下载完成通知、下载期间防止休眠，并自动跟随系统代理
• 登录安全：Cookie 优先写入 macOS Keychain、Linux Secret Service 或 Windows DPAPI，普通配置文件不再保存明文登录票据
• Provider 插件：将实现统一 Provider 接口的 JAR 放入 ~/.musicunlock/plugins 即可扩展平台
• 平台健康检查：检查四平台登录状态、接口可用性、延迟和能力矩阵
• 音频质量体检：检测损坏、异常码率、伪无损、空音轨和 PCM 削波
• 设置、备份与迁移：独立设置页统一管理输出、下载、网络和桌面选项；完整备份可包含设置、曲库与任务状态，并支持曲库路径重新关联
• WebDAV 同步：可把完整备份上传到 Nextcloud、坚果云或 NAS，并在其他设备恢复
• 更新：启动检查正式版本，可下载当前平台安装包并校验 SHA256SUMS.txt 后交给系统安装
• 诊断与迁移：持久化滚动日志，导出已脱敏诊断信息，配置导出/导入自动排除账号 Cookie 和代理凭据
• 命令行支持在线搜索、收藏歌单、链接下载、音质策略、命名模板、限速、代理和 JSON 进度输出
• 命令行支持输出格式、dry-run、任务查看与恢复、曲库扫描和曲库导出
• SQLite 曲库：全文搜索、增量索引、播放历史、播放/跳过次数、收藏、评分和本地歌单
• 智能播放列表：最近新增、最近播放、常听、收藏、无损和待整理列表
• 本地曲库播放器：与搜索试听共用播放队列，支持队列排序、随机播放、列表/单曲循环、倍速、播放历史与持久化恢复
• 播放器界面：底部播放条、正在播放页、迷你播放器窗口和队列面板，歌词可微调偏移并导入 LRC
• 播放器音频处理：响度归一化、低频/高频增益、淡入淡出与曲间淡化，调整后即时生效
• 质量升级建议：按质量评分给出保持当前版本、搜索更高码率或重新获取真无损的可执行建议
• 声学指纹：使用频谱峰值为同一录音建立指纹，辅助识别不同格式、码率与标签下的重复文件
• 频谱质量分析：检测频谱截止异常、疑似伪无损、削波、空音轨、低动态范围和有效码率
• 完整标签工作台：编辑标题、歌手、专辑歌手、音轨/碟号、年份、流派、作曲、ISRC、歌词、封面、评分和收藏
• 设备/本地目录同步：增量复制、转码、镜像删除、双向恢复和较新/本地/远端/双份冲突策略，可按通配符排除指定文件并查看冲突与错误明细
• 媒体服务器集成：触发 Plex、Jellyfin、Navidrome 和 Subsonic 重新扫描曲库，可先测试连接再触发
• 自动化 2.0：目录、扩展名、大小、文件名通配符/正则、优先级、时间窗口、星期、Webhook 和转换完成后置命令；规则可先试跑匹配，执行结果保留最近 200 条历史
• 开放接口：OpenAPI 描述、MCP JSON-RPC、任务/曲库/质量/同步/媒体服务器接口，仅监听本机并使用 Token
• 命令行批量转换与桌面 GUI 两用

支持格式

加密格式（解密后输出标准音频）

平台	扩展名
网易云音乐	ncm
QQ音乐	qmc0 qmc2 qmc3 qmc4 qmc6 qmc8 qmcflac qmcogg tkm mflac mflac0 mflac1 mflac2 mgg mgg0 mgg1 mgg2 mggl mmp4 bkcmp3 bkcm4a bkcflac bkcwav bkcape bkcogg bkcwma
酷狗音乐	kgm kgma vpr
酷我音乐	kwm

原始音频（无需解密，直接转码）

类型	扩展名
无损 / 未压缩	wav wave flac ape alac aif aiff au wv dff
有损	mp3 m4a aac ogg oga opus wma

原始音频走同一条转换管线：可套用输出格式与码率、命名模板、跳过/另存/覆盖策略和内容去重，输出格式为「原始格式」时按文件真实格式原样输出。

快速开始

需要 JDK 17+：

./gradlew run              # 启动桌面 GUI
./gradlew run --args="-h"  # 命令行帮助
./gradlew test             # 运行测试（含 unlock-music 真实样本向量）

图形界面使用说明

1. 添加文件

• 直接把音乐文件或文件夹拖进虚线区域，或点击「添加文件 / 添加文件夹」选择。加密格式与常见原始音频都可以添加。
• 队列会列出每个文件：左侧为格式徽章（NCM 橙 / QMC 靛蓝 / KGM 青绿 / KWM 紫，原始音频为中性灰），中间为文件名与大小，右侧为状态。

2. 勾选文件与歌单导入

• 队列中每个文件左侧都有勾选框，只有勾选的文件会参与转换；标题旁显示「已选 X / Y 首」，右上角提供「全选 / 清空」。
• 点队列右上角「歌单导入」，粘贴网易云、QQ、酷狗或酷我的歌曲/歌单/专辑/歌手链接，或直接粘贴网易云歌单 ID，然后点「读取歌单」。
• 应用按歌名 / 歌手把歌单曲目与队列文件匹配，列出「已命中 / 未命中」明细；点「仅勾选命中的 N 首」后，队列中只有命中的文件被勾选。
• 命中项会显示对应的本地文件名；未命中的曲目说明队列里还没有对应文件，可先添加后再导入。

3. 设置输出与转码

• 右侧「输出目录」显示默认位置 ~/Music/MusicUnlock（用户主目录下，打包版会自动创建）。
• 点「浏览…」更换目录，点「打开」在系统文件管理器中查看。
• 「跳过已完成」默认开启：输出目录中已有同名同格式结果时直接跳过；关闭后会强制重新转换并覆盖。
• 「输出格式」可沿用解密后的原始格式，也可选择 MP3、FLAC、M4A、OGG、Opus、WAV；有损格式可设置 128k / 192k / 320k 码率，转码使用随应用分发的内置 ffmpeg。
• 「本地命名模板」支持 {title}、{artist}、{album}、{track:02}、{year}、{platform} 等变量，并可选择跳过、另存或覆盖同名文件。

4. 选择是否去重

• 打开「按解密后音频内容去重」开关后，转换时会对解密后的音频做 SHA-256：内容相同的歌曲只保留一个，优先保留不带 (N) 后缀的文件（例如同时存在 晴天.ncm 与 晴天 (1).ncm 时保留前者），其余标记为「重复」。

5. 开始转换

• 点右下角「开始转换」，按勾选的文件逐首进行：状态会从「等待中 → 转换中（行内进度条）→ 已完成 / 已跳过 / 失败」。
• 转换过程中队列锁定（不能移除文件或修改输出目录/去重开关），完成后即可在输出目录找到结果。

6. 状态说明

状态	含义
等待中	排队中，尚未开始
转换中	正在处理，行内有橙色渐变进度条
已完成	转换成功，已写入输出目录
已跳过	输出目录中已有同名同格式结果
失败	文件损坏或不支持，行内会显示具体原因
重复	与队列中其他文件解密后内容相同，被去重跳过

7. 新版本提示

• 每次启动检查一次 GitHub Releases 的最新正式版本，只有存在更高版本时才会在内容区顶部出现橙色提示条。
• 点「前往下载」在系统浏览器打开对应 Release 页面，点「忽略」收起提示。
• 检查超时、离线或接口异常时静默跳过，不影响启动与转换。
• 当前版本与项目链接可从左侧导航底部的「关于」入口查看，卡片内可直接跳转 GitHub 项目页。

网易云下载

从左侧「音乐服务」切到「网易云下载」，可把网易云歌单歌曲下载为 MP3。

1. 登录

登录页提供三种方式，登录态会保存到本机配置文件；成功后界面展示账号昵称与头像，点「退出登录」即清除保存的会话。

• 扫码登录：点击「获取二维码」，用网易云 App「扫一扫」完成登录。部分账号会触发网易云服务端的安全验证（返回 8821），此时扫码无法完成，请改用浏览器登录。
• 验证码登录：输入网易云绑定手机号，点击「发送验证码」后填入验证码登录。若当前网络触发安全验证，会提示改用浏览器登录。
• 浏览器登录（推荐）：自动打开本机 Chrome/Edge 进入网易云官方登录页，你在浏览器内完成登录后自动读取登录态并回到 App，无需复制粘贴。

2. 选择歌单

• 登录后自动列出全部歌单（含收藏），显示封面、名称与歌曲数。
• 支持勾选多个歌单，提供「全选 / 清空 / 刷新」。

3. 加入下载队列

• 点「加入下载队列」把选中歌单的歌曲加入下载任务中心，完成后写入右侧输出目录（默认 ~/Music/MusicUnlock）。
• 按音质策略获取音频，高码率或无损优先、不可用时自动降级；默认保留源格式，也可在设置中转为 MP3，并写回完整标签与封面。
• 官方返回 FLAC 等非 MP3 格式时，自动调用内置 ffmpeg 转码为 MP3。
• 会员歌曲：登录的账号有会员权限即可下载（请求携带登录态，自动取会员高码率）；非会员账号官方只返回试听片段，会明确提示「仅可获取试听片段」并跳过，不会静默下载试听版。
• 灰色歌曲（无版权 / 已下架）：网易云在你所在地区没有该歌曲版权，官方接口不返回任何播放地址，即使登录会员也无法下载，会提示「灰色歌曲：无版权或已下架」。

QQ 音乐下载

从左侧「音乐服务」切到「QQ 音乐下载」，登录 QQ 音乐账号后即可把歌单歌曲下载为 MP3。

1. 登录

登录页提供两种方式，登录态与票据会保存到本机配置文件；成功后界面展示账号昵称与头像，点「退出登录」即清除保存的会话。

• 扫码登录：点击「刷新二维码」后用手机 QQ「扫一扫」完成登录，并在手机上确认。登录会按 QQ 音乐网页版流程换取播放票据，账号内可播放的歌曲即可下载。
• 浏览器登录（推荐）：自动打开本机 Chrome/Edge 进入 QQ 音乐官方登录页，在浏览器内完成登录后自动读取登录态并回到 App，无需复制粘贴。浏览器不可用时，可在同一页面手动粘贴完整 Cookie（需包含 uin 与播放票据 qm_keyst / qqmusic_key）登录。

2. 选择歌单

• 登录后自动列出账号下的歌单（含「我喜欢的音乐」，若官方接口返回），显示封面、名称与歌曲数。
• 支持勾选多个歌单，提供「全选 / 清空 / 刷新」。

3. 加入下载队列

• 点「加入下载队列」把选中歌单的歌曲加入下载任务中心，完成后写入右侧输出目录（默认 ~/Music/MusicUnlock）。
• 按音质策略获取音频，320k 或无损优先、不可用时自动降级；默认保留源格式，也可在设置中转为 MP3，并写回完整标签与封面。
• 官方返回 FLAC / M4A 等非 MP3 格式时，自动调用内置 ffmpeg 转码为 MP3。
• VIP 专属歌曲：需要账号具备对应会员权限；无权限时官方不返回播放地址，会明确提示「VIP 专享歌曲」并跳过。
• 数字专辑 / 需单独购买：部分歌曲需在 QQ 音乐内购买后才能下载，会明确提示并跳过。
• 无版权 / 已下架歌曲：官方接口不返回播放地址，会明确提示并跳过，不会静默下载试听片段。

酷狗下载

从左侧「音乐服务」切到「酷狗下载」，登录酷狗账号后即可下载收藏与创建的歌单。

1. 登录

• 扫码登录：使用酷狗音乐客户端扫码并确认。
• 浏览器登录：自动打开本机 Chrome/Edge 进入酷狗登录页，登录后自动读取包含 token、userid 的登录态。
• 浏览器不可用时，可在同一页面粘贴完整 Cookie。

2. 选择歌单

• 登录后自动加载账号下的收藏与创建歌单。
• 支持多选、全选、清空和刷新。

3. 加入下载队列

• 点「加入下载队列」将选中歌单下载到输出目录。
• 优先请求无损或 320k，权限不足时自动降级；默认保留源格式，也可在设置中转为 MP3，并写回完整标签与封面。
• 付费、无版权或下架歌曲会给出明确失败原因并继续后续歌曲。

酷我下载

从左侧「音乐服务」切到「酷我下载」，登录酷我账号后即可下载「我喜欢听」和创建的歌单。

1. 登录

• 浏览器登录：自动打开本机 Chrome/Edge 进入酷我登录页，登录后自动读取 userid、sid 等登录态。
• 浏览器不可用时，可在同一页面粘贴完整 Cookie。

2. 选择歌单

• 登录后自动加载「我喜欢听」、默认列表及创建的歌单。
• 支持多选、全选、清空和刷新。

3. 加入下载队列

• 点「加入下载队列」将选中歌单下载到输出目录。
• 优先请求无损或 320k，不可用时依次降级到 192k、128k；默认保留源格式，也可在设置中转为 MP3，并写回完整标签与封面。
• 付费或版权受限歌曲会给出接口返回的原因并跳过。

下载任务中心

本地转换和在线歌曲下载都会进入统一的「任务中心」页面：

• 可同时处理本地转换与在线下载，逐首显示进度、速度、剩余时间和当前阶段。
• 支持暂停、继续、取消、单条重试、批量重试和按状态筛选。
• 网络中断或应用退出后，未完成任务可继续下载，已完成的分片不会被重复写入。
• 登录失效、版权受限、服务器异常、磁盘不可写等错误会分类展示。
• 在线同名文件可按设置跳过、覆盖、另存或仅在音质更高时升级；失败下载可直接切换 320k / 128k 重试。
• 可在「曲库整理」右侧设置并发数、重试次数、限速、代理、超时和同名文件策略。

曲库整理与歌单追更

「曲库整理」页面用于维护已经下载的音乐：

• 扫描输出目录，统计重复文件、无法解析的音频、缺封面、缺歌词和缺标签的文件。
• 按模板批量重命名，并同步移动同名 LRC 文件。
• 修复标签与封面：优先使用歌曲平台 ID 在线获取元数据，失败时保留本地标签。
• 重复清理先生成计划，精确重复可以自动处理，疑似重复必须显式确认；删除改为移入应用回收站，并支持一键撤销。
• 点「详细审阅」可逐组对比保留与移除的版本，直接看到各自的格式、码率、体积、封面与歌词情况，确认后再移入回收站。
• 勾选多首后可批量写入标签：只覆盖勾选的字段，未勾选的内容保持不变，写入后可一键撤销。
• 点「质量升级分析」会按质量评分从低到高列出建议，指出哪些曲目值得搜索更高码率或重新获取真无损。
• 曲库浏览支持搜索，可编辑单曲标签，并导出 M3U8 / CSV。
• 在任意平台勾选歌单后点击「追更选中歌单」，即可按周期同步。再次同步只下载本地曲库缺失的歌曲，并持续更新曲目数量与上次同步时间。
• 支持导出/导入不含 Cookie 和账号快照的配置，以及导出已脱敏的诊断日志。

搜索与链接

「搜索与链接」页面可统一检索网易云、QQ 音乐、酷狗和酷我：

• 输入歌名、歌手或专辑名即可聚合四个平台的搜索结果。
• 可直接粘贴单曲、歌单、专辑或歌手分享链接，自动识别平台并加载曲目。
• 单曲显示“已下载”状态，并可检测当前账号可获取的音质和版权状态。
• 歌单、专辑与歌手结果可直接加入下载队列。
• 单曲支持跨平台匹配；匹配成功后可下载另一个平台的可用版本。
• 单曲结果可直接点击「播放」加入全局播放队列，底部播放器支持进度、音量和上一首/下一首。
• 单曲结果可点击「下载 MP3」直接进入任务中心；下载完成后按 128k / 192k / 320k 设置转码。

本地播放器

底部播放条常驻在内容区下方，点击左侧的封面与曲名可展开「正在播放」页：

• 播放条提供随机播放、上一首/下一首、播放/暂停、列表循环与单曲循环、进度跳转和音量控制；右侧可收藏、打开正在播放、打开队列和弹出迷你播放器窗口。
• 迷你播放器是一个独立的置顶小窗口，可在浏览其他页面时保持控制。
• 队列面板分「当前队列」和「播放历史」两页：当前队列可点击任意曲目直接跳播、清空待播，也可整体保存为本地歌单；播放历史可把听过的曲目重新加入队列。
• 正在播放页展示封面、歌词和播放进度，歌词面板随播放自动滚动，可用偏移微调修正时间轴，也可导入同名 .lrc 歌词。
• 播放位置、队列、随机与循环模式会持久化保存，重启应用后继续上次的进度。
• 「设置」页可调整响度归一化、低频/高频增益、淡入淡出与曲间淡化、倍速，改动会立即作用于当前曲目。

自动收件箱与桌面集成

• 在「曲库整理」的桌面设置中添加监听文件夹；功能开启后，新出现的加密音乐会自动转换到输出目录。
• 可开启下载完成通知、系统托盘和下载期间防止系统休眠。
• 默认跟随系统代理，也可在设置中填写固定 HTTP 代理。
• 独立「设置」页统一管理输出格式、命名模板、下载策略、网络、备份、更新与开机启动。
• 自动化规则可先「测试规则」用本地文件试跑，确认匹配结果后再启用；「执行历史」保留最近 200 条执行记录。
• 同步方案支持填写通配符排除规则（如 *Live*、*.mp3），同步后可直接查看冲突与错误明细。
• 媒体服务器可先「测试」连接，确认地址与凭据可用后再触发重新扫描。
• 完整备份包含设置、曲库索引和两类任务文件；导入后即时热加载，无需重启应用。

命令行

./gradlew run --args="-c ~/Music/网易云 -o ~/Music/转换结果 -d"

参数	说明
-c, --convert [path] ...	转换路径下的所有受支持音频文件（加密格式与常见原始格式，支持文件或文件夹，可多个）
-o, --output [dir]	自定义输出目录（默认 ./output）
-d, --dedup	按解密后音频内容去重，优先保留不带 (N) 后缀的文件
-f, --force	强制重新转换并覆盖已有输出（默认跳过已完成文件）
--format [original|mp3|flac|m4a|ogg|opus|wav]	设置本地或在线输出格式
--dry-run	只列出转换计划，不写入文件
--tasks	以 JSON 查看持久化的转换与下载任务
--resume	恢复未完成的本地转换和在线下载任务
--library-scan	扫描输出目录并更新曲库索引
--library-export [csv|m3u8]	导出当前曲库索引
--inspect [path]	检查音频格式、码率、损坏、静音和削波
--provider-health	检查平台登录状态、接口延迟和能力
--deep-scan [dir]	SQLite 深度扫描并生成声学指纹和质量分析
--smart [kind]	导出智能播放列表（recently_added / favorites / lossless 等）
--sync-profile [id]	执行设备或 WebDAV 曲库同步方案
--media-refresh [id]	触发 Plex、Jellyfin、Navidrome 或 Subsonic 重新扫描
--openapi	输出本机 API 的 OpenAPI 文档
--webdav-backup	将完整备份上传到已配置的 WebDAV
--webdav-restore	从已配置的 WebDAV 恢复完整备份
--daemon, --serve	启动无窗口守护进程和本机自动化 API
-v, --view	打开图形界面（不带参数时默认打开）
-h, --help	帮助
-u, --url [link]	下载单曲、歌单、专辑或歌手分享链接
--playlist [id]	下载指定歌单 ID
--search [keyword]	搜索歌曲、歌单、专辑与歌手
--search [keyword] --download	搜索并下载歌曲结果
--platform [netease|qq|kugou|kuwo]	将在线操作限制到指定平台
--favorites	下载收藏/喜欢歌单
--quality [highest|lossless|320|balanced|smallest]	设置音质策略
--template [pattern]	设置输出文件与目录模板
--json	以 JSON 输出搜索结果与下载进度
--retries [n]	设置失败重试次数
--rate-limit [KB/s]	设置单任务下载限速，0 表示不限速
--timeout [seconds]	设置请求超时
--proxy [url]	使用指定 HTTP 代理
--cookie [header]	配合 --platform 使用一次性登录 Cookie
--mp3	将在线下载结果转为 MP3；默认保留平台原始格式

常用示例

# 转换单个文件
./gradlew run --args="-c ~/Music/晴天.ncm -o ~/Music/转换结果"

# 批量转换多个文件夹并去重
./gradlew run --args="-c ~/Music/网易云 ~/Music/QQ音乐 -o ~/Music/转换结果 -d"

# 查看帮助
./gradlew run --args="-h"

# 搜索四个平台，不下载
./gradlew run --args="--search 周杰伦"

# 搜索并下载前 20 首歌曲结果
./gradlew run --args="--search 周杰伦 --download --limit 20 -o ~/Music/MusicUnlock"

# 从 QQ 音乐分享链接下载，使用无损优先和命名模板
./gradlew run --args="-u 'https://y.qq.com/n/ryqq/songDetail/xxxx' --quality lossless --template '{artist}/{album}/{track:02} - {title}'"

# JSON 进度输出，便于脚本集成
./gradlew run --args="--url 'https://music.163.com/#/playlist?id=123456' --json"

注意：去重是对解密后音频做 SHA-256，而不是对加密文件做哈希——同名歌曲即使加密文件不同（元数据/歌曲 ID 不同），解密后音频相同也能正确去重。

常见问题

• 转换后文件在哪？ GUI 默认输出到 ~/Music/MusicUnlock，可在右侧「输出目录」查看或更改；命令行默认 ./output，用 -o 指定。
• 转换失败怎么办？ 队列行内会显示具体原因（如文件已损坏、格式不支持）。解密算法基于公开格式规范，仅适用于合法获取的文件。
• 为什么会显示「已跳过」？ 输出目录已存在同名同格式结果；如需重新生成，关闭「跳过已完成」或在命令行添加 -f/--force。
• 为什么会显示「重复」？ 开启了去重且该文件解密后的音频与队列中其他文件相同，属正常跳过。
• 登录 Cookie 和服务器密钥保存在哪里？ 优先写入操作系统凭据库：macOS Keychain、Linux Secret Service、Windows DPAPI；无法使用系统凭据库时才回退到权限受限的本地凭据文件。导出的配置不会包含 Cookie、账号快照、WebDAV 密码或媒体服务器 Token。
• 下载失败后需要重新开始吗？ 不需要。任务会保留已写入的分片并尝试断点续传，可在「下载任务」页面继续或重试。
• 为什么任务中心显示“已跳过”？ 本地曲库索引已经存在该歌曲，且设置选择了“跳过”；如需重新下载，可在「曲库整理」中更改同名文件策略。
• 打包版双击后如何打开？ macOS 打开 .dmg 后把 MusicUnlock 拖入「应用程序」即可启动；Windows 直接双击单文件 MusicUnlock.exe（内嵌 JRE，首次启动自动解压到临时目录运行，退出后自动清理），无参数默认进入图形界面。

原生打包（需在对应操作系统上执行）

./gradlew packageDmg              # macOS .dmg
./gradlew createDistributable     # Windows exe + 自带 JRE 的应用目录

• macOS 发布物为 .dmg。
• Windows 发布物为单文件 MusicUnlock-<版本>-windows.exe：由 7-Zip SFX 封装，内嵌 JRE，无外部资源文件，双击自动解压到临时目录运行、退出后自动清理。
• Linux 发布物为 .deb 与 .rpm。
• 跨平台一键打包见 .github/workflows/build.yml（GitHub Actions 矩阵：macOS + Windows + Linux），Release 同时生成 SHA256SUMS.txt。

项目结构

src/main/kotlin/musicunlock/
  core/           多格式解密核心（纯 Kotlin）
    NcmDecoder.kt / NcmCipher.kt / NcmMetadata.kt   网易云 NCM
    QmcDecoder.kt / QmcKey.kt / QmcCipher.kt / TeaCipher.kt   QQ音乐 QMC
    KgmDecoder.kt  酷狗 KGM/KGMA/VPR
    KwmDecoder.kt  酷我 KWM
    AudioSniffer.kt / Formats.kt / MusicDecoder.kt
  online/         在线音乐公共层
    OnlineMusic.kt            统一账号 / 歌单 / 歌曲 / 平台接口
    OnlineMp3Downloader.kt    下载、转码、标签写回
    BrowserCookieLogin.kt     Chrome/Edge 浏览器登录与 Cookie 读取
  ncm/            网易云下载、登录与接口适配
  qq/             QQ 音乐下载、登录与接口适配
  kugou/          酷狗下载、二维码登录、签名与接口适配
  kuwo/           酷我下载、浏览器登录、Secret 与接口适配
  playlist/       四平台链接识别、歌单导入与本地文件匹配
  library/        SQLite 曲库、声学指纹、质量分析、标签修复与清理
  sync/           歌单追更、跨平台匹配、设备/WebDAV 同步与媒体服务器
  watch/          收件箱文件夹监听与自动转换
  automation/     自动化 2.0 规则、Webhook/命令动作与本机 API/MCP
  player/         本地/在线播放、持久队列、歌词、音频处理与播放历史
  desktop/        系统托盘、桌面通知与防休眠
  backup/         设置、曲库与任务完整备份恢复
  diagnostics/    脱敏日志与诊断快照
  service/        MusicConverter、ConversionTaskManager、AudioTranscoder、TagWriter
  update/         版本检查、安装包下载校验与安装启动
  cli/            MainCli（命令行）与 OnlineCliRunner（在线下载）
  ui/             转换、下载任务、曲库整理、搜索、播放器与各平台登录页面

更新日志

各版本的更新内容见 CHANGELOG.md。

算法来源与致谢

• NCM 解密：基于公开的 .ncm 容器格式规范实现，算法与 unlock-music（MIT）一致
• QMC 系列（密钥派生、TEA、Static/Map/RC4 流密码）：unlock-music（MIT）
• KGM/VPR： MyKgmWasm（MIT）与 unlock-music（MIT）
• KWM：unlock-music（MIT）
• 酷狗请求签名与设备注册：KuGouMusicApi（MIT）

测试向量来自 unlock-music 项目的 testdata/（MIT）。

许可证（License）

本项目采用 MIT License。 第三方算法与依赖声明见 THIRD_PARTY_NOTICES.md。

免责声明

本项目仅用于学习密码学与文件格式分析，请勿用于任何商业用途或侵犯他人权益。