163-music-dl/SKILL.md

name, description

name

description

musicdl

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：

# 打开中文交互菜单
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：

{
  "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 设置历史记录上限。

使用相对路径时，以脚本所在目录为基准。也可直接使用绝对路径：

{
  "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，就直接进入批处理模式并跳过菜单：

# 单曲和多首歌曲
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。

理解输出文件

普通单曲、歌单和歌手批量下载默认保存为：

downloadDir/
├── 歌手 - 歌名.flac
├── 歌手 - 歌名.lrc
└── 歌手 - 歌名.合并翻译.lrc

专辑下载保存为：

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