# 网易云音乐下载器

一个基于 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` 排除，不会被提交到仓库。