Jocay
254 lines
12 KiB
Markdown
Executable File
254 lines
12 KiB
Markdown
Executable File
---
|
||
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 语法；脚本读取失败会回退到内置默认配置并显示警告。
|