add project files
This commit is contained in:
吴璨
@@ -0,0 +1,14 @@
|
||||
{
|
||||
"permissions": {
|
||||
"allow": [
|
||||
"Bash(node --check 163_music_downloader.js)",
|
||||
"Bash(ffmpeg -version)",
|
||||
"Bash(ffprobe -version)",
|
||||
"PowerShell($c = Get-Command ffmpeg -ErrorAction SilentlyContinue; if \\($c\\) { Write-Output $c.Source; & ffmpeg -version | Select-Object -First 1 } else { Write-Output \"ffmpeg NOT FOUND\" })",
|
||||
"PowerShell($paths = @\\(\"C:\\\\ffmpeg\",\"C:\\\\Program Files\\\\ffmpeg\",\"$env:LOCALAPPDATA\\\\Microsoft\\\\WinGet\",\"$env:USERPROFILE\\\\scoop\\\\apps\\\\ffmpeg\"\\); Get-ChildItem -Path C:\\\\ -Filter ffmpeg.exe -Recurse -ErrorAction SilentlyContinue -Depth 4 2>$null | Select-Object -First 5 -ExpandProperty FullName)",
|
||||
"Bash(node *)",
|
||||
"Bash(echo \"exit: $?\")",
|
||||
"Bash(ffprobe *)"
|
||||
]
|
||||
}
|
||||
}
|
||||
+18
@@ -0,0 +1,18 @@
|
||||
# Downloaded audio files
|
||||
*.mp3
|
||||
*.flac
|
||||
*.wav
|
||||
*.m4a
|
||||
*.aac
|
||||
*.ogg
|
||||
*.wma
|
||||
*.ape
|
||||
*.opus
|
||||
|
||||
# Archives
|
||||
*.zip
|
||||
*.rar
|
||||
*.7z
|
||||
*.tar
|
||||
*.tar.gz
|
||||
*.tgz
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,57 @@
|
||||
# AGENTS.md
|
||||
|
||||
This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.
|
||||
|
||||
## Overview
|
||||
|
||||
A single-file Node.js CLI for downloading music from NetEase Cloud Music (网易云音乐), with lyrics, cover art, and ID3 tag embedding. All logic lives in `163_music_downloader.js` (~2600 lines). There is no `package.json` — the script runs on Node built-ins only (`https`, `http`, `fs`, `path`, `readline`, `child_process`). The UI, comments, and console output are entirely in Chinese.
|
||||
|
||||
## Running
|
||||
|
||||
```bash
|
||||
# Interactive menu (TTY required for pause hotkey)
|
||||
node 163_music_downloader.js
|
||||
|
||||
# Command-line batch mode (bypasses the menu entirely)
|
||||
node 163_music_downloader.js <songId> <songId> ...
|
||||
node 163_music_downloader.js --playlist=<playlistId>
|
||||
|
||||
# Flags (batch mode only)
|
||||
--level=lossless # override quality; see QUALITY_LEVELS
|
||||
--retries=5 # download retry count (default 3)
|
||||
--no-lyric # skip .lrc download
|
||||
--no-cover # skip cover/tag embedding
|
||||
```
|
||||
|
||||
There are no tests, linter, or build step. Verify changes by running the script.
|
||||
|
||||
## External dependencies (all optional / runtime-detected)
|
||||
|
||||
- **`api.chksz.top`** — third-party API (`API` object at top of file) for song URLs, search, lyrics, and playlists. This is the core download source.
|
||||
- **`music.163.com`** — queried directly (`fetchNeteaseSongDetail`, `fetchNeteaseAlbumDetail`) for rich metadata (album, publish date, popularity). Requires `Cookie: os=pc` header.
|
||||
- **`node-id3`** (npm) — preferred for MP3 tag/lyric/cover embedding. `require`d lazily via `hasNodeID3()`; absent by default.
|
||||
- **`ffmpeg`** (system) — fallback embedder for non-MP3 (FLAC etc.) and when node-id3 is missing. Detected via `hasFFmpeg()`.
|
||||
- **Audio players** (`mpv`, `ffplay`, `play`, `cvlc`, `aplay`) — for the preview/play features, detected via `which`. Note: `which` is Unix-only, so preview won't find players on Windows even if installed.
|
||||
|
||||
If a dependency is missing the relevant feature degrades gracefully (skips embedding, prints the URL, etc.).
|
||||
|
||||
## Architecture
|
||||
|
||||
Everything is one flat module — functions defined top-to-bottom, then a `main()` at the bottom drives either batch mode or an infinite interactive menu loop (`while (true)` + `switch` on single-char menu choices). Key layers:
|
||||
|
||||
- **Network helpers** — `fetchJSON`, `downloadFile` (streams with a live progress bar, follows redirects), `downloadBuffer`, all Promise-wrapped around `https.get`.
|
||||
- **`downloadSong` → `_downloadSong`** — the core pipeline: `downloadSong` wraps `_downloadSong` with retry/backoff; `_downloadSong` resolves the URL, skips/overwrites based on existing-file size comparison (1% tolerance), writes audio, then lyrics, then embeds cover+tags, then records history.
|
||||
- **Lyrics** — `fetchLyric` returns `{ lrc, tlyric, ... }`; `mergeLrc` interleaves original + translation by matching `[mm:ss.xx]` timestamps into a `.合并翻译.lrc` file.
|
||||
- **Cover/tags** — `embedCover` downloads the image to a temp `.cover.jpg`, tries node-id3 (MP3) then ffmpeg (`-map` audio+cover, `-c copy`), always cleans up the temp file in `finally`.
|
||||
- **Persistence** (all JSON in the script's `__dirname`, not the download dir):
|
||||
- `download_history.json` — capped at 500 entries, newest-first (`addHistory`).
|
||||
- `downloader_config.json` — key/value config, currently only the `level` quality setting (`getConfig`/`setConfig`).
|
||||
- **Output layout** — audio + `.lrc` files go to `downloads/`. Deletes move files to `.trash/` (not permanent). ZIP packaging uses `.tmp_zip/`. The `c` menu option cleans these up.
|
||||
|
||||
## Conventions & gotchas
|
||||
|
||||
- **Quality levels** — `QUALITY_LEVELS` array is the source of truth; `DEFAULT_LEVEL = 'jymaster'`. The chksz API may return a lower `actualLevel` than requested.
|
||||
- **Filenames** — always `sanitize(`${artist} - ${name}`)` (strips `/\:*?"<>|`). Lyric/rename logic depends on this exact `"artist - name"` shape when parsing filenames back out.
|
||||
- **Menu dispatch** — adding a feature means adding a `case` in the `main()` switch AND a line in both `printMenu()` and the `h` help text. Note the switch currently has a duplicated `case 'p'/'P'` block (the second is unreachable) and the keypress listener is registered twice — mirror the existing style rather than assuming it's clean.
|
||||
- **Pause** — global `isPaused`/`waitIfPaused()` gate batch loops; toggled by the `p` hotkey (only wired up in interactive mode with a TTY).
|
||||
- Batch loops sleep ~300–500ms between songs to avoid hammering the API — preserve this when editing download loops.
|
||||
@@ -0,0 +1,57 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## Overview
|
||||
|
||||
A single-file Node.js CLI for downloading music from NetEase Cloud Music (网易云音乐), with lyrics, cover art, and ID3 tag embedding. All logic lives in `163_music_downloader.js` (~2600 lines). There is no `package.json` — the script runs on Node built-ins only (`https`, `http`, `fs`, `path`, `readline`, `child_process`). The UI, comments, and console output are entirely in Chinese.
|
||||
|
||||
## Running
|
||||
|
||||
```bash
|
||||
# Interactive menu (TTY required for pause hotkey)
|
||||
node 163_music_downloader.js
|
||||
|
||||
# Command-line batch mode (bypasses the menu entirely)
|
||||
node 163_music_downloader.js <songId> <songId> ...
|
||||
node 163_music_downloader.js --playlist=<playlistId>
|
||||
|
||||
# Flags (batch mode only)
|
||||
--level=lossless # override quality; see QUALITY_LEVELS
|
||||
--retries=5 # download retry count (default 3)
|
||||
--no-lyric # skip .lrc download
|
||||
--no-cover # skip cover/tag embedding
|
||||
```
|
||||
|
||||
There are no tests, linter, or build step. Verify changes by running the script.
|
||||
|
||||
## External dependencies (all optional / runtime-detected)
|
||||
|
||||
- **`api.chksz.top`** — third-party API (`API` object at top of file) for song URLs, search, lyrics, and playlists. This is the core download source.
|
||||
- **`music.163.com`** — queried directly (`fetchNeteaseSongDetail`, `fetchNeteaseAlbumDetail`) for rich metadata (album, publish date, popularity). Requires `Cookie: os=pc` header.
|
||||
- **`node-id3`** (npm) — preferred for MP3 tag/lyric/cover embedding. `require`d lazily via `hasNodeID3()`; absent by default.
|
||||
- **`ffmpeg`** (system) — fallback embedder for non-MP3 (FLAC etc.) and when node-id3 is missing. Detected via `hasFFmpeg()`.
|
||||
- **Audio players** (`mpv`, `ffplay`, `play`, `cvlc`, `aplay`) — for the preview/play features, detected via `which`. Note: `which` is Unix-only, so preview won't find players on Windows even if installed.
|
||||
|
||||
If a dependency is missing the relevant feature degrades gracefully (skips embedding, prints the URL, etc.).
|
||||
|
||||
## Architecture
|
||||
|
||||
Everything is one flat module — functions defined top-to-bottom, then a `main()` at the bottom drives either batch mode or an infinite interactive menu loop (`while (true)` + `switch` on single-char menu choices). Key layers:
|
||||
|
||||
- **Network helpers** — `fetchJSON`, `downloadFile` (streams with a live progress bar, follows redirects), `downloadBuffer`, all Promise-wrapped around `https.get`.
|
||||
- **`downloadSong` → `_downloadSong`** — the core pipeline: `downloadSong` wraps `_downloadSong` with retry/backoff; `_downloadSong` resolves the URL, skips/overwrites based on existing-file size comparison (1% tolerance), writes audio, then lyrics, then embeds cover+tags, then records history.
|
||||
- **Lyrics** — `fetchLyric` returns `{ lrc, tlyric, ... }`; `mergeLrc` interleaves original + translation by matching `[mm:ss.xx]` timestamps into a `.合并翻译.lrc` file.
|
||||
- **Cover/tags** — `embedCover` downloads the image to a temp `.cover.jpg`, tries node-id3 (MP3) then ffmpeg (`-map` audio+cover, `-c copy`), always cleans up the temp file in `finally`.
|
||||
- **Persistence** (all JSON in the script's `__dirname`, not the download dir):
|
||||
- `download_history.json` — capped at 500 entries, newest-first (`addHistory`).
|
||||
- `downloader_config.json` — key/value config, currently only the `level` quality setting (`getConfig`/`setConfig`).
|
||||
- **Output layout** — audio + `.lrc` files go to `downloads/`. Deletes move files to `.trash/` (not permanent). ZIP packaging uses `.tmp_zip/`. The `c` menu option cleans these up.
|
||||
|
||||
## Conventions & gotchas
|
||||
|
||||
- **Quality levels** — `QUALITY_LEVELS` array is the source of truth; `DEFAULT_LEVEL = 'jymaster'`. The chksz API may return a lower `actualLevel` than requested.
|
||||
- **Filenames** — always `sanitize(`${artist} - ${name}`)` (strips `/\:*?"<>|`). Lyric/rename logic depends on this exact `"artist - name"` shape when parsing filenames back out.
|
||||
- **Menu dispatch** — adding a feature means adding a `case` in the `main()` switch AND a line in both `printMenu()` and the `h` help text. Note the switch currently has a duplicated `case 'p'/'P'` block (the second is unreachable) and the keypress listener is registered twice — mirror the existing style rather than assuming it's clean.
|
||||
- **Pause** — global `isPaused`/`waitIfPaused()` gate batch loops; toggled by the `p` hotkey (only wired up in interactive mode with a TTY).
|
||||
- Batch loops sleep ~300–500ms between songs to avoid hammering the API — preserve this when editing download loops.
|
||||
@@ -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 语法；脚本读取失败会回退到内置默认配置并显示警告。
|
||||
+21
@@ -0,0 +1,21 @@
|
||||
{
|
||||
"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": "/AstrBot/Music",
|
||||
"historyFile": "download_history.json",
|
||||
"runtimeConfigFile": "downloader_config.json",
|
||||
"trashDir": ".trash",
|
||||
"tempZipDir": ".tmp_zip"
|
||||
},
|
||||
"defaults": {
|
||||
"quality": "jymaster",
|
||||
"retries": 3,
|
||||
"historyLimit": 500
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,68 @@
|
||||
[
|
||||
{
|
||||
"id": "3342981041",
|
||||
"name": "铁花飞",
|
||||
"artist": "Mili/塞壬唱片-MSR",
|
||||
"album": "铁花飞",
|
||||
"level": "lossless",
|
||||
"bitrate": 904424,
|
||||
"size": 27432639,
|
||||
"file": "Mili_塞壬唱片-MSR - 铁花飞.flac",
|
||||
"timestamp": "2026-07-13T10:25:51.755Z"
|
||||
},
|
||||
{
|
||||
"id": "3336080601",
|
||||
"name": "SAIKAI",
|
||||
"artist": "Mili",
|
||||
"album": "SAIKAI",
|
||||
"level": "lossless",
|
||||
"bitrate": 791784,
|
||||
"size": 32067914,
|
||||
"file": "Mili - SAIKAI.flac",
|
||||
"timestamp": "2026-07-13T10:16:32.596Z"
|
||||
},
|
||||
{
|
||||
"id": 3336080601,
|
||||
"name": "SAIKAI",
|
||||
"artist": "Mili",
|
||||
"album": "SAIKAI",
|
||||
"level": "hires",
|
||||
"bitrate": 2733875,
|
||||
"size": 110709636,
|
||||
"file": "Mili - SAIKAI.flac",
|
||||
"timestamp": "2026-07-13T09:36:41.412Z"
|
||||
},
|
||||
{
|
||||
"id": 3336080601,
|
||||
"name": "SAIKAI",
|
||||
"artist": "Mili",
|
||||
"album": "SAIKAI",
|
||||
"level": "lossless",
|
||||
"bitrate": 791784,
|
||||
"size": 32067914,
|
||||
"file": "Mili - SAIKAI.flac",
|
||||
"timestamp": "2026-07-13T07:41:34.485Z"
|
||||
},
|
||||
{
|
||||
"id": 3342981041,
|
||||
"name": "铁花飞",
|
||||
"artist": "Mili/塞壬唱片-MSR",
|
||||
"album": "铁花飞",
|
||||
"level": "jyeffect",
|
||||
"bitrate": 2872452,
|
||||
"size": 87120168,
|
||||
"file": "Mili_塞壬唱片-MSR - 铁花飞.flac",
|
||||
"timestamp": "2026-07-13T07:31:12.383Z"
|
||||
},
|
||||
{
|
||||
"id": 3336080601,
|
||||
"name": "SAIKAI",
|
||||
"artist": "Mili",
|
||||
"album": "SAIKAI",
|
||||
"level": "lossless",
|
||||
"bitrate": 791784,
|
||||
"size": 32067914,
|
||||
"file": "Mili - SAIKAI.flac",
|
||||
"timestamp": "2026-07-13T07:19:59.547Z"
|
||||
}
|
||||
]
|
||||
Reference in New Issue
Block a user