Jocay
158 lines
5.4 KiB
Markdown
Executable File
158 lines
5.4 KiB
Markdown
Executable File
# 网易云音乐下载器
|
||
|
||
一个基于 Node.js 的网易云音乐命令行下载工具，支持单曲、歌单、专辑及批量下载，并可同步保存歌词、封面和歌曲标签。
|
||
|
||
项目采用 CommonJS 模块化结构，核心功能仅依赖 Node.js 内置模块。`node-id3`、`ffmpeg` 和本地音频播放器均为可选依赖。
|
||
|
||
## 功能特性
|
||
|
||
- 按关键词、歌曲 ID、歌手、歌单或专辑下载音乐
|
||
- 支持多个歌曲 ID 及文件列表批量下载
|
||
- 支持标准、极高、无损、Hi-Res、超清母带、空间音频和高清臻品音质
|
||
- 下载原文歌词，并按时间轴合并翻译歌词
|
||
- 下载封面，写入歌曲信息、歌词和封面标签
|
||
- 查看歌曲详情、歌词、歌单内容和本地下载列表
|
||
- 试听歌曲，导出下载历史，生成 M3U 播放列表
|
||
- 自动识别文件名并补全已有音频文件的标签
|
||
- 支持失败重试、下载暂停、历史统计、缓存清理和回收站
|
||
|
||
## 环境要求
|
||
|
||
- Node.js（建议使用当前维护中的 LTS 版本）
|
||
- 可访问脚本所配置的音乐接口和网易云音乐
|
||
|
||
可选依赖：
|
||
|
||
- [`node-id3`](https://www.npmjs.com/package/node-id3)：为 MP3 写入封面、歌词和 ID3 标签
|
||
- [`ffmpeg`](https://ffmpeg.org/)：为 FLAC 等格式写入封面和标签，也可作为 MP3 标签写入的后备方案
|
||
- `mpv`、`ffplay`、`play`、`cvlc` 或 `aplay`：用于试听歌曲
|
||
|
||
安装可选的 MP3 标签依赖：
|
||
|
||
```bash
|
||
npm install node-id3
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
克隆仓库后进入项目目录：
|
||
|
||
```bash
|
||
git clone https://git.draws.qzz.io/jocay/163-music-dl.git
|
||
cd 163-music-dl
|
||
node 163_music_downloader.js
|
||
```
|
||
|
||
不带参数运行时会进入中文交互菜单，可搜索、下载和管理歌曲。
|
||
|
||
## 项目结构
|
||
|
||
```text
|
||
163_music_downloader.js # 命令行入口与交互菜单
|
||
lib/
|
||
catalog.js # 搜索与歌单接口
|
||
config.js # 应用配置、路径和默认值
|
||
downloader.js # 单曲下载主流程与重试
|
||
history.js # 下载历史读写
|
||
lyrics.js # 歌词获取、合并和制作信息解析
|
||
metadata.js # 网易云歌曲/专辑元数据与专辑目录
|
||
network.js # HTTP 请求和文件下载
|
||
pause.js # 批量任务暂停状态
|
||
quality.js # 音质解析与交互选择
|
||
tagging.js # 封面及音频标签写入
|
||
utils.js # 文件名、目录大小等通用工具
|
||
```
|
||
|
||
## 命令行模式
|
||
|
||
直接下载一个或多个歌曲 ID：
|
||
|
||
```bash
|
||
node 163_music_downloader.js 347230 1859245776
|
||
```
|
||
|
||
下载完整歌单或专辑：
|
||
|
||
```bash
|
||
node 163_music_downloader.js --playlist=歌单ID
|
||
node 163_music_downloader.js --album=专辑ID
|
||
```
|
||
|
||
可选参数：
|
||
|
||
| 参数 | 说明 |
|
||
| --- | --- |
|
||
| `--level=<音质>` | 指定下载音质 |
|
||
| `--retries=<次数>` | 指定失败重试次数，默认 `3` |
|
||
| `--no-lyric` | 不下载歌词文件 |
|
||
| `--no-cover` | 不下载封面，也不执行封面和标签嵌入 |
|
||
|
||
示例：
|
||
|
||
```bash
|
||
node 163_music_downloader.js --playlist=歌单ID --level=lossless --retries=5
|
||
node 163_music_downloader.js 347230 --level=hires --no-cover
|
||
```
|
||
|
||
## 音质等级
|
||
|
||
| 参数值 | 音质 |
|
||
| --- | --- |
|
||
| `standard` | 标准 |
|
||
| `exhigh` | 极高 |
|
||
| `lossless` | 无损 |
|
||
| `hires` | Hi-Res |
|
||
| `jymaster` | 超清母带（默认） |
|
||
| `sky` | 空间音频 |
|
||
| `jyeffect` | 高清臻品 |
|
||
|
||
实际可用音质取决于接口返回结果，接口可能返回低于请求等级的音源。
|
||
|
||
## 配置
|
||
|
||
程序启动时读取项目根目录的 `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
|
||
}
|
||
}
|
||
```
|
||
|
||
相对路径以脚本所在目录为基准，绝对路径会直接使用。仓库中的 `config.json` 可能配置了特定运行环境的下载路径，首次运行前请按本机环境调整 `paths.downloadDir`。
|
||
|
||
## 输出文件
|
||
|
||
- 音频和 `.lrc` 歌词保存在 `paths.downloadDir` 指定的目录
|
||
- 下载专辑时，专辑图片会保存为对应专辑目录下的 `cover.jpg`
|
||
- 下载历史保存在 `paths.historyFile` 指定的 JSON 文件中，默认最多保留 500 条
|
||
- 交互菜单修改的音质设置保存在 `paths.runtimeConfigFile` 指定的文件中
|
||
- 删除操作会先将文件移动到 `paths.trashDir`，而不是永久删除
|
||
- ZIP 打包过程使用 `paths.tempZipDir` 作为临时目录
|
||
|
||
下载文件名采用 `歌手 - 歌名` 格式，并自动移除文件系统不允许的字符。
|
||
|
||
## 注意事项
|
||
|
||
- 下载能力依赖第三方 `api.chksz.top` 接口，其可用性、音源和返回质量不由本项目保证。
|
||
- 歌曲详情和专辑元数据会直接请求网易云音乐。
|
||
- 请遵守当地法律法规、平台条款和音乐版权要求，仅将本工具用于合法用途。
|
||
- 音频文件和压缩包已通过 `.gitignore` 排除，不会被提交到仓库。
|