水下听歌大救星

水下听歌大救星是一个本地音乐文件处理工具。网页支持网易云 .ncm 与酷狗 .kgm/.kgma/.vpr 转 MP3；CLI 目前支持 .ncm。它的目标很朴素：方便把自己已经拥有或有权使用的歌曲原文件整理出来，放到自己的离线设备里，比如游泳用的运动耳机、车载播放器、随身播放器等。

请勿将本项目用于侵犯版权、规避付费、批量搬运、传播未授权音乐或其他违法用途。

在线示例

• 在线站点：https://ncm.mikeywa.icu
• 作者主页：https://mikeywa.icu
• npm：https://www.npmjs.com/package/ncm-studio-cli
• GitHub 仓库：https://github.com/yanghaoleng/ncm-studio

标题图标使用 Figma 节点 170:984（亮色）和 170:987（暗色）的透明原图，按页面 44px 展示尺寸的 3× 输出为 132×132 透明 WebP：public/favicon-light.webp 与 public/favicon-dark.webp，并随明暗主题切换。浏览器标签固定使用同款红白游泳圈音符的 public/favicon.png，同时提供 public/favicon.ico 兜底和版本号防缓存。标题图标首次加载时先从页面顶部画面外落入，再接轻微上下 Q 弹浮动，点击重播时不重新挂载图片。大标题随语言显示为“水下听歌大救星”“水下聽歌大救星”“Underwater Music Lifesaver”或“水中音楽の救世主”，并按当前语言逐字符柔化入场；固定产品名 NCM Studio 作为极小副标题在标题动画结束后分成 NCM 与 Studio 出现；点击图标或标题可同步重播标题与图标动效。

适合的使用场景

• 你已经有一批本地 .ncm/.kgm/.kgma/.vpr 文件，希望在浏览器里转成 MP3。
• 你想把自己有权使用的音乐文件拷贝到离线设备里，例如游泳运动耳机。
• 你希望文件处理尽量在本地浏览器完成，不把本地音乐文件上传到应用服务器。
• 其他音乐平台推荐使用网易官方歌单导入工具或 CLI快速创建歌单。

功能

• 拖入或选择本地 .ncm/.kgm/.kgma/.vpr 文件。
• 导入入口使用无云朵的上箭头图标，避免误解为会上传到云端。
• 在浏览器本地完成文件解析、酷狗解密和 MP3 转码。
• KGM、KGMA、VPR 可直接转换；不再提供依赖本机密钥库的 KGG 转换。
• 尽可能读取元数据和内嵌封面。
• 为 MP3 写入 ID3 标题、歌手、专辑和 APIC 封面信息。
• 单首下载或把已完成的本地转换结果打包成 ZIP。
• 文件加入后自动转换；转换期间队列顶部仅显示“继续添加”，全部任务结束且至少有一首成功后才显示“打包下载”，文件行不再重复显示 MP3 格式标签。
• 网页转换队列会根据 CPU 核心数、可用内存、文件体积和页面流畅度在 1–3 档内自动调整并发；持续卡顿时降档，稳定后再逐步升档。
• 音乐处理面板随文件数量自然增高，最高不超过视窗剩余高度；超出后文件列表独立滚动，文件行以分割线区分，不使用单行卡片边框。桌面端进度条与百分比同排；移动端隐藏进度条、百分比和文件大小。新任务开始时自动跟随到对应行，转换期间品牌图标循环弹跳，全部结束后汇总显示本轮耗时。
• 大批量 ZIP 打包使用百分比进度；下载成功后按钮变绿，显示对勾与“已下载”，瞬间缩小下沉并立即弹回。绿色状态保持 6 秒，随后变为与“继续添加”一致的普通按钮并显示“再次下载”。进度长时间不变或生成失败时，会提示重试或分批处理。
• 移动端移除底部悬浮操作栏，队列顶部的转换状态、“继续添加”和“打包下载”随页面滚动置顶。
• CLI 支持单文件、目录递归、进度、重名保护和 JSON 机器输出。
• 网页右侧提供默认折叠的 CLI 说明，展开后以与打赏说明一致的正文字号展示批量使用场景、AI 操作方法和 npm 安装链接；打赏栏目展开时自动收起 CLI。
• 英文界面的 CLI 标题使用 “Install CLI for an AI agent”，多行时保持左对齐。
• 网页右侧提供可折叠的作者打赏入口：点击箭头或 ZIP 打包成功后直接展示默认微信的二维码；移动端打包成功后自动滚动，使该板块完整曝光。
• 微信和支付宝二维码使用 WebP 质量 90，在保持可识别的前提下降低静态资源体积。
• 打赏说明支持复制微信号 yanghaoleng，复制成功后显示短暂 Toast。
• 打赏说明固定说明工具永久免费和可随意打赏，中间从 9 条轻松活泼的祝福池随机展示一句，结尾邀请用户提出需求；随机句使用 spring-scale-in 逐词入场。
• 提供简体中文、繁体中文、英文 /en/、日文 /ja/ 四种语言入口，以及 canonical、hreflang、robots.txt、sitemap.xml 和 WebApplication 结构化数据。
• Vercel 将 /en、/en/、/ja、/ja/ 显式映射到对应静态落地页，避免单页应用回退覆盖多语言内容。
• 页脚“网站使用说明”使用无下划线文字入口；弹窗内可原地切换中文、英文和日文说明，不触发页面跳转。
• 页脚“网站使用说明”和“作者主页”统一使用 13px 文字、14px 图标与 6px 图文间距。

CLI 安装

需要 Node.js 20 或更高版本。

npm install -g ncm-studio-cli

也可以不全局安装，直接运行：

npx ncm-studio-cli --help

CLI 用法

# 转换一个目录，会递归查找 .ncm
ncm-studio convert ./music --output ./converted

# 转换单个文件
ncm-studio ./song.ncm -o ./converted

# 完全离线，不请求缺失的网络封面
ncm-studio ./music --no-network

常用选项：

• -o, --output <目录>：输出目录，默认 ./converted。
• --overwrite：覆盖同名输出；默认会添加 (2) 等后缀。
• --no-network：不请求缺失的封面，内嵌封面仍会写入 MP3。
• --json：在 stdout 输出结构化结果，便于 AI 和脚本调用。
• --quiet：不显示人类可读进度。

供 AI 和自动化调用

推荐让 AI Agent 执行带 --json 的命令：

ncm-studio convert ./input --output ./output --json --no-network

stdout 只输出一个 JSON 对象，其中包含 ok、total、succeeded、failed、files 和 errors。全部成功时退出码为 0；参数、输入或部分转换失败时为 1。

CLI 不需要 API 密钥，也不会上传音频文件。默认可能会根据 NCM 元数据请求缺失的封面；自动化环境可使用 --no-network 禁用该请求。KGM、KGMA、VPR 当前仅在网页端支持。

隐私与本地处理

• 本地音乐文件只在浏览器内存中处理，不会上传到应用服务器。
• 应用不需要 AI 密钥，也不会把歌单、元数据或音频发送给应用服务器。

大批量 ZIP 打包

• MP3/FLAC 等音频本身已经压缩，ZIP 显式使用 STORE 模式，不做无效的二次压缩。
• 每首歌转换完成时同步保存 CRC32；打包时直接组装标准 ZIP 文件头和中央目录，不再重读整批音频。
• 音频 Blob 会被原样引用到 ZIP Blob，避免再复制一份整包二进制数据。
• 按文件数量更新 0%-100% 进度；100 首以上会定期让出渲染帧，保持页面可响应。
• 20 秒没有进度变化时显示卡顿提示；异常会进入可重试的失败状态。
• 单个 ZIP 目前限制在 4 GB 以内。总体积过大时，请减少文件数量后分批处理。

合法使用声明

本项目仅用于个人整理、备份和使用自己有权处理的音乐文件。请遵守当地法律法规和音乐平台服务条款。

更详细的使用边界见 使用与合规说明。

不要将本项目用于：

• 下载、传播或分享未经授权的音乐。
• 绕过会员、付费、DRM 或版权限制。
• 批量抓取、搬运或商业化分发音乐资源。
• 任何侵犯版权或违反平台规则的用途。

本地开发

npm install
npm run dev

本地试运行 CLI：

npm run cli -- --help

默认开发服务由 Vite 启动。根据终端输出打开对应本地地址。

构建

npm run build

测试

npm test

自动测试会验证 CLI 契约、酷狗底层解码、MP3 标签和 ZIP 数据一致性；网页入口仅开放 NCM、KGM、KGMA、VPR。

API

当前不包含应用服务端 API。文件解析、转换和打包均在浏览器或 CLI 本地执行。npm 包同时导出 convertNcmFile(file, options)，其中 file 需提供 name 和返回 ArrayBuffer 的 arrayBuffer()。

关键技术架构

• React + Vite 负责单页应用和响应式界面。
• .ncm 与酷狗格式解析、音频转换、ID3 写入和 ZIP 打包均在浏览器本地完成。
• KGM/KGMA/VPR 使用按需加载的 WASM 解码器；网页不再开放依赖密钥库的 KGG 输入。
• src/lib/concurrency.js 管理 1–3 档加权自适应并发；80 MB 以上文件占用更多队列容量，降低多个大文件同时解码时的内存峰值。
• KGM/KGMA/VPR 的 WASM 核心使用独立实例池，不再由单条全局队列串行阻塞。
• 解密结果若不是 MP3，会通过 Web Audio 解码并以 320 kbps 编码为 MP3。
• Node.js CLI 复用 src/lib/ncm.js 转换核心，不维护第二套解析逻辑。
• CLI 将进度写入 stderr，--json 结果写入 stdout，方便 Agent 稳定解析。
• browser-id3-writer 负责写入 MP3 ID3v2.3 文本标签与 APIC 封面帧。
• src/lib/zip.js 封装 CRC32、ZIP STORE 结构、Blob 组合、进度、重名保护和停滞检测。
• FileSaver 触发浏览器下载。
• SEO 架构包含简体/繁体中文应用页、英文和日文静态落地页；基础关键词覆盖网易云/酷狗音乐文件转 MP3、游泳骨传导耳机离线音乐整理等合规场景，后续再依据真实搜索表现调整主次词。

多平台扩展状态

• 酷狗：网页支持无需导入密钥库的 KGM、KGMA、VPR；KGG 不再开放。
• QQ 音乐：QMCv1 和携带密钥的 QMCv2 可本地解码；新版 musicex 文件需要已登录 QQ 音乐的凭据获取 ekey。
• 汽水音乐：加密 MP4/M4A 需要与歌曲对应的 spade_a/AES 密钥；仅有本地加密文件时通常无法独立处理。
• 当前架构是“格式识别 → 平台解码适配器 → 真实音频编码识别 → 必要时转 MP3 → 元数据与封面写入”。解码产物可能是 MP3、FLAC、OGG 或 M4A，不能只修改后缀。

部署

项目可以部署到 Vercel。 当前正式域名为 https://ncm.mikeywa.icu；最新 1–3 档智能并发、首帧暗色防白闪、移动端队列、下载反馈、固定游泳圈音符 favicon 与 800ms 打赏高度展开动效部署为 dpl_Fkzggm4mxjghR1n3gEDMkTncd45t。 Bing 站点所有权通过根路径 /BingSiteAuth.xml 验证；站长平台于 2026-08-10 开始准备搜索表现数据，已安排 2026-08-12 复查并继续 Bing、百度、Google 与海外 SEO。

技术栈

• React
• Vite
• FileSaver
• CryptoJS
• browser-id3-writer
• GSAP
• Lucide React

相关链接和参考

• 网易云音乐：https://music.163.com/
• 网易官方歌单导入工具与 CLI：https://music.163.com/st/ncmcli#setup
• ncmdump：https://github.com/taurusxin/ncmdump
• browser-id3-writer：https://github.com/egoroof/browser-id3-writer
• Project Unlock Music crypto：https://github.com/showhwa/UnlockMusicProject_Archive/tree/main/tmp/lib_um_crypto_rust
• KgmWasm：https://github.com/xhacker-zzz/KgmWasm
• 第三方许可：THIRD_PARTY_NOTICES.md

致谢

本项目的 .ncm 解析和转换思路参考了社区公开格式知识，尤其是 taurusxin/ncmdump。请尊重原项目许可和贡献者。

免责声明

本项目不提供、存储或分发任何音乐文件。使用者需要自行确保拥有相关音乐文件或使用行为的合法授权。