Metadata-Version: 2.3
Name: ncm-dl
Version: 0.1.0
Summary: Small uv/Python CLI for downloading NetEase Cloud Music tracks.
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# ncm-dl

`ncm-dl` 是一个基于 uv/Python 的网易云音乐命令行下载工具。

运行时只用 Python 标准库，不依赖第三方包。配置优先读取环境变量，命令行参数可以覆盖环境变量。

## 用法

```bash
cd ~/ncm-dl

uv run ncm-dl search "晴天"
uv run ncm-dl download 186016 --output ~/音乐
uv run ncm-dl url 186016
```

`download` 也可以写成 `dl`：

```bash
uv run ncm-dl dl 186016
```

下载整个网易云歌单并生成 Navidrome 可导入的 M3U：

```bash
export MUSIC_U='your_cookie_value'
uv run ncm-dl playlist 你的歌单ID \
  --music-root /opt/navidrome/music \
  --level lossless \
  --navidrome-scan \
  --navidrome-import \
  --navidrome-sudo \
  --sync
```

先不下载、只确认歌单是否能读取：

```bash
uv run ncm-dl playlist 你的歌单ID --dry-run --limit 10
```

默认会把歌曲下载到：

```text
/opt/navidrome/music/netease/<歌单名-歌单ID>/
```

并生成：

```text
/opt/navidrome/music/playlists/<歌单名-歌单ID>.m3u
```

M3U 里的歌曲路径会相对 `--music-root` 写入，适合 Navidrome 扫描和 `navidrome pls import`。

## 环境变量

支持这些环境变量：

| 变量 | 作用 |
| --- | --- |
| `MUSIC_U` | 网易云 `MUSIC_U` cookie，用于付费/VIP/无损歌曲。 |
| `OUTPUT_DIR` | 默认下载目录。 |
| `LEVEL` | 默认音质：`standard`、`higher`、`exhigh`、`lossless`、`hires`。默认 `exhigh`。 |
| `LIMIT` | 默认搜索结果数量。默认 `10`。 |
| `OVERWRITE` | 设为 `1`、`true` 或 `yes` 时，默认覆盖同名文件。 |
| `CHECK_MD5` | 设为 `0`、`false` 或 `no` 时，默认关闭 MD5 校验。 |
| `NAVIDROME_MUSIC_ROOT` | `playlist` 命令默认音乐库根目录。默认 `/opt/navidrome/music`。 |
| `NAVIDROME_BIN` | `playlist --navidrome-import` 使用的 Navidrome 可执行文件。默认 `navidrome`。 |
| `NAVIDROME_CONFIG` | Navidrome 配置文件。默认 `/etc/navidrome/navidrome.toml`。 |
| `NAVIDROME_USER` | 导入歌单所属的 Navidrome 用户。默认第一个管理员。 |
| `NAVIDROME_SUDO` | 设为 `1`、`true` 或 `yes` 时，导入步骤使用 `sudo navidrome`。 |
| `NAVIDROME_SYNC` | 设为 `1`、`true` 或 `yes` 时，导入时加 `--sync`。 |
| `NCM_TIMEOUT` | 下载超时时间，单位秒。默认 `60`。 |
| `NCM_USER_AGENT` | 自定义请求 User-Agent。 |

示例：

```bash
export MUSIC_U='your_cookie_value'
export OUTPUT_DIR="$HOME/音乐"
export LEVEL=lossless

uv run ncm-dl dl 186016
```

## 说明

- 本工具不会把 `MUSIC_U` 写入磁盘。
- 如果歌曲没有返回可播放 URL，通常需要设置有效网易云账号的 `MUSIC_U`。
- 网易云返回 MD5 时会默认校验下载文件；只有排查问题时才建议使用 `--no-md5`。
