add project files

2026-07-22 16:37:23 +08:00
parent 0086727073
commit 7fc8fdaa8f
8 changed files with 3384 additions and 0 deletions
@@ -0,0 +1,253 @@
+---
+name: musicdl
+description: Use and configure the musicdl NetEase Cloud Music command-line downloader. Use when Codex needs to explain or operate song, playlist, artist, album, lyric, cover, metadata, history, M3U, archive, cleanup, rename, preview, or batch-download features in `163_music_downloader.js`, including `config.json`, interactive menu choices, command-line flags, quality selection, Linux and Windows paths, output naming, optional tools, and troubleshooting.
+---
+
+# 使用 Musicdl
+
+## 快速开始
+
+在 `163_music_downloader.js` 所在目录运行 Node.js：
+
+```bash
+# 打开中文交互菜单
+node 163_music_downloader.js
+
+# 下载一首或多首歌曲
+node 163_music_downloader.js 歌曲ID
+node 163_music_downloader.js 歌曲ID1 歌曲ID2 歌曲ID3
+
+# 下载整个歌单或专辑
+node 163_music_downloader.js --playlist=歌单ID
+node 163_music_downloader.js --album=专辑ID
+```
+
+从网易云歌曲、歌单或专辑网页地址中取得对应数字 ID。需要精确下载完整专辑时优先使用专辑 ID；按名称搜索只能覆盖接口返回的搜索结果。
+
+## 准备运行环境
+
+必须准备：
+
+- Node.js；脚本只使用内置模块，不要求项目存在 `package.json`。
+- 可访问 `config.json` 中音乐接口及网易云接口的网络环境。
+- 下载目录的创建和写入权限。
+
+按需准备：
+
+- 安装可被当前脚本解析到的 `node-id3`，为 MP3 写入封面、歌词和 ID3 标签。
+- 将 `ffmpeg` 加入 `PATH`，为 FLAC 等非 MP3 文件写入封面和标签，并作为 MP3 的后备工具。
+- 将 `mpv`、`ffplay`、`play`、`cvlc` 或 `aplay` 加入 `PATH`，使用试听和本地播放功能。
+- 在 Windows 上注意播放器检测使用 `which`，即使已经安装播放器也可能检测不到；此时直接复制显示的音频 URL 到播放器。
+- 准备系统 `zip` 命令以输出 ZIP；缺少 `zip` 时脚本尝试使用 `tar` 输出 `.tar.gz`。
+
+缺少可选工具不会阻止音频下载；相关封面嵌入、标签或播放能力会降级。
+
+## 配置 `config.json`
+
+在脚本同目录编辑 `config.json`：
+
+```json
+{
+  "api": {
+    "music": "https://api.chksz.top/api/163_music",
+    "lyric": "https://api.chksz.top/api/163_lyric",
+    "search": "https://api.chksz.top/api/163_search",
+    "playlist": "https://api.chksz.top/api/163_playlist",
+    "neteaseBaseUrl": "https://music.163.com"
+  },
+  "paths": {
+    "downloadDir": "downloads",
+    "historyFile": "download_history.json",
+    "runtimeConfigFile": "downloader_config.json",
+    "trashDir": ".trash",
+    "tempZipDir": ".tmp_zip"
+  },
+  "defaults": {
+    "quality": "jymaster",
+    "retries": 3,
+    "historyLimit": 500
+  }
+}
+```
+
+按以下规则设置：
+
+- 使用 `api.music` 获取音频地址和基础歌曲信息。
+- 使用 `api.lyric` 获取原文和翻译歌词。
+- 使用 `api.search` 搜索歌曲、歌手和专辑。
+- 使用 `api.playlist` 获取歌单曲目。
+- 使用 `api.neteaseBaseUrl` 获取歌曲、专辑、发行时间和曲序等详细元数据。
+- 使用 `paths.downloadDir` 设置音频和歌词根目录。
+- 使用 `paths.historyFile` 设置下载历史 JSON。
+- 使用 `paths.runtimeConfigFile` 保存交互菜单选择的音质；不要把它与静态 `config.json` 设为同一文件。
+- 使用 `paths.trashDir` 设置软删除目录。
+- 使用 `paths.tempZipDir` 设置歌单打包临时目录。
+- 使用 `defaults.quality` 设置初始音质。
+- 使用 `defaults.retries` 设置单曲默认尝试次数。
+- 使用 `defaults.historyLimit` 设置历史记录上限。
+
+使用相对路径时，以脚本所在目录为基准。也可直接使用绝对路径：
+
+```json
+{
+  "paths": {
+    "downloadDir": "/mnt/storage/music"
+  }
+}
+```
+
+Linux 使用 `/home/user/Music`、`/mnt/storage/music` 等绝对路径；Windows 在 JSON 中将反斜杠写成双反斜杠，例如 `D:\\Music\\Downloads`。目录不存在时由脚本递归创建。配置缺失、无法解析或字段无效时使用脚本内置默认值。
+
+## 选择音质
+
+使用以下音质标识：
+
+- `standard`：标准音质。
+- `exhigh`：极高音质。
+- `lossless`：无损音质。
+- `hires`：Hi-Res。
+- `jymaster`：超清母带，默认值。
+- `sky`：空间音频。
+- `jyeffect`：高清臻品。
+
+接口可能按歌曲实际可用资源返回低于请求值的音质。交互模式使用菜单 `0` 保存常用音质；命令行使用 `--level=<音质>` 临时覆盖。
+
+## 使用命令行批处理
+
+命令行只要出现歌曲 ID、`--playlist` 或 `--album`，就直接进入批处理模式并跳过菜单：
+
+```bash
+# 单曲和多首歌曲
+node 163_music_downloader.js 123456
+node 163_music_downloader.js 123456 234567 345678
+
+# 歌单
+node 163_music_downloader.js --playlist=123456789
+
+# 完整专辑
+node 163_music_downloader.js --album=123456
+
+# 组合选项
+node 163_music_downloader.js --album=123456 --level=lossless --retries=5
+node 163_music_downloader.js 123456 --no-lyric --no-cover
+```
+
+可用参数：
+
+- `--playlist=<ID>`：下载歌单全部曲目。
+- `--album=<ID>`：从网易云专辑接口读取并下载全部曲目。
+- `--level=<音质>`：覆盖本次批处理音质。
+- `--retries=<次数>`：覆盖单曲失败尝试次数。
+- `--no-lyric`：不下载 `.lrc` 文件。
+- `--no-cover`：不嵌入封面和标签。
+
+允许在一次命令中同时提供专辑、歌单和单曲 ID；脚本依次处理。批量曲目之间保留约 500ms 间隔。
+
+## 使用交互菜单
+
+运行 `node 163_music_downloader.js` 后输入菜单键。
+
+### 搜索与下载
+
+- `1` 搜索歌曲并下载：输入关键词，查看歌曲、歌手和专辑，选择一个或多个结果后选择音质下载。
+- `2` 按歌曲 ID 下载：输入单个 ID，或用逗号分隔多个 ID。
+- `3` 下载整个歌单：输入歌单 ID，确认曲目数量和音质后逐首下载。
+- `4` 查看歌单并选择下载：列出歌单曲目；输入 `a` 下载全部，或输入 `1,3,5`、`5-10` 等序号组合。
+- `6` 按歌手批量下载：输入歌手名和搜索数量；下载全部匹配结果或指定序号、序号范围。
+- `s` 按歌名搜索：列出搜索结果；输入序号下载，输入 `a` 下载全部，输入 `v3` 试听第 3 首，输入 `d3` 查看第 3 首详情。
+- `a` 下载专辑：输入专辑 ID 可获取完整曲目；也可输入专辑名，从有限搜索结果中选择一个或多个专辑分组。
+- `b` 批量 ID 下载：连续输入逗号、空格或换行分隔的 ID，输入空行结束；自动去重、统计成功与失败，并可重试失败项目。
+- `f` 从文件批量下载：读取每行一个歌曲 ID 或 `歌手 - 歌名` 的文本文件；名称条目先搜索匹配，再统一确认下载。
+
+### 歌词、试听与详情
+
+- `5` 查看歌词：输入歌曲 ID，显示去除时间标签后的歌词；按提示保存原文 `.lrc` 和合并翻译歌词。
+- `7` 试听歌曲：输入歌曲 ID，取得标准音质地址并调用本地播放器；未检测到播放器时显示 URL。
+- `8` 查看歌曲详情：显示歌曲 ID、歌手、专辑、时长、别名、曲号、碟号、热度、发行日期、发行公司、专辑歌手、流派、不同音质信息和部分专辑简介。
+
+### 本地文件与标签
+
+- `l` 查看已下载歌曲：按修改时间列出下载根目录中的音频文件和大小；输入 `p+序号` 播放，输入 `d+序号` 软删除，输入 `da` 移动全部文件到回收站。当前列表只扫描下载根目录，不递归展示专辑子目录。
+- `n` 从文件名识别并补全标签：识别 `歌手 - 歌名.mp3`、`歌手-歌名.flac` 等名称；选择文件后搜索最佳歌曲，补全标签和歌词，并按标准名称重命名。
+- `g` 自动补全标签：扫描下载根目录中符合 `歌手 - 歌名` 且缺少歌词的音频，搜索匹配项并补全封面、标签、歌词和历史记录。
+- `w` 重命名歌曲：输入序号，分别确认歌手和歌名；同时重命名关联 `.lrc` 文件。此功能存在于脚本中，但当前主菜单没有显示 `w` 提示，可直接输入使用。
+
+`l`、`n`、`g`、`w` 目前只扫描 `downloadDir` 顶层，不递归处理按歌手/专辑存放的专辑文件。
+
+### 历史、列表与统计
+
+- `9` 查看下载历史：显示最近 30 条和总数；输入 `d` 删除指定记录，输入 `c` 清空全部记录。删除历史不会删除音频文件。
+- `e` 导出历史：选择 CSV、JSON 或 TXT；结果保存到脚本目录并带时间戳。
+- `t` 查看统计：显示累计歌曲数、总大小、音质分布、下载最多的歌手和最近 7 天下载量。
+- `m` 保存歌单为 M3U：优先写入已存在的本地歌曲路径，未下载歌曲使用配置的音乐 API 作为网络备用地址；M3U 保存到脚本目录。
+
+### 打包、清理与设置
+
+- `z` 下载歌单并打包：把歌单歌曲下载到临时目录，优先生成 ZIP，缺少 `zip` 时尝试生成 `.tar.gz`；成功或失败后清理本次临时目录。此流程只打包音频，不执行标准歌词和标签下载流程。
+- `c` 清理缓存：删除配置的临时打包目录和孤立的 `.cover.jpg`、`.tmp.*` 文件；清空回收站前再次询问。
+- `0` 设置音质：输入序号或音质名称，并写入运行时配置文件。
+- `p` 暂停或恢复批量下载：只在交互模式且终端支持 TTY 按键事件时可靠工作；正在执行的单首网络下载不会立即中断，下一次暂停检查点才会生效。
+- `r` 重置设置：删除运行时配置并恢复 `config.json` 指定的默认音质；随后选择是否保留下载历史。不会删除静态 `config.json` 或已下载音频。
+- `h` 显示内置帮助。
+- `q` 退出程序；也可以输入 `exit` 或 `quit`。
+
+## 理解输出文件
+
+普通单曲、歌单和歌手批量下载默认保存为：
+
+```text
+downloadDir/
+├── 歌手 - 歌名.flac
+├── 歌手 - 歌名.lrc
+└── 歌手 - 歌名.合并翻译.lrc
+```
+
+专辑下载保存为：
+
+```text
+downloadDir/
+└── 专辑歌手/
+    └── 专辑名/
+        ├── 01. 歌曲名.flac
+        ├── 01. 歌曲名.lrc
+        ├── 01. 歌曲名.合并翻译.lrc
+        ├── 02. 歌曲名.flac
+        └── ...
+```
+
+按接口返回的专辑曲目顺序编号，至少补齐两位；曲目超过 99 首时使用三位编号。根据实际下载 URL 决定 `.mp3`、`.flac`、`.m4a`、`.wav` 或 `.aac` 扩展名，不强制转换格式。自动清理歌手、专辑和歌曲名中的非法路径字符。
+
+歌词处理规则：
+
+- 将原文保存为同名 `.lrc`。
+- 存在翻译时，按时间戳交错合并原文和译文，另存 `.合并翻译.lrc`。
+- 嵌入标签时使用原文歌词，并尝试从歌词头提取作词、作曲、编曲和制作人信息。
+
+封面和标签规则：
+
+- MP3 优先使用 `node-id3`。
+- FLAC 等格式或缺少 `node-id3` 时尝试使用 `ffmpeg`。
+- 尝试写入标题、歌手、专辑、专辑歌手、曲号、碟号、发行年份、完整日期、流派、发行公司、歌词和封面。
+- 在处理结束后清理临时 `.cover.jpg`。
+
+## 理解重复下载与历史
+
+下载前检查目标文件名：
+
+- 已有文件与接口文件大小差异低于 1% 时跳过音频下载，并尝试补齐缺少的歌词或封面标签。
+- 大小差异明显时直接覆盖同名音频。
+- 每次完成流程后将记录写入历史文件，最新记录位于最前，并按 `historyLimit` 截断。
+- 专辑历史中的 `file` 字段保存相对于 `downloadDir` 的歌手、专辑和文件路径。
+
+删除本地文件时优先使用菜单 `l` 的软删除功能，将音频和关联歌词移动到 `trashDir`。菜单中“删除全部”的提示文字较强，但实现仍是移动到回收站；使用 `c` 清空回收站后才不可恢复。
+
+## 处理常见问题
+
+- 出现接口错误或无搜索结果时，检查 `config.json` 接口地址和网络连通性，再确认 ID 类型是否正确。
+- 请求高音质却得到较低音质时，以接口返回的实际音质为准；歌曲可能没有对应资源。
+- 没有封面或标签时，确认 `node-id3` 可被 Node.js 解析，或确认 `ffmpeg` 在 `PATH` 中。
+- 无法试听时，确认播放器在 `PATH` 中；Windows 可直接使用脚本显示的音频 URL。
+- Linux 绝对下载目录无法写入时，检查运行脚本用户对目标目录及其父目录的权限。
+- 专辑名称搜索缺歌时，改用准确的专辑 ID 和 `--album=<ID>`。
+- 本地文件列表看不到专辑歌曲时，直接查看 `downloadDir/歌手/专辑`；当前管理菜单不递归扫描。
+- 配置文件损坏时，修复 JSON 语法；脚本读取失败会回退到内置默认配置并显示警告。