# music_dl

**Repository Path**: bluetune/music_dl

## Basic Information

- **Project Name**: music_dl
- **Description**: music_dl based on musicdl
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-28
- **Last Updated**: 2026-09-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# music-dl

多平台音乐**下载链接解析**库。按歌曲 ID 从多个第三方/官方接口获取可请求的 HTTP 音频 URL，不依赖 [musicdl](https://github.com/CharlesPikachu/musicdl)。

支持：**QQ 音乐**、**网易云音乐**、**酷狗音乐**、**酷我音乐**。

> **v0.1.5** 四平台统一 `search()` 与 `UnifiedSongMeta`（含封面）；QQ Mobile 搜索与 smartbox 兜底；酷狗 `parse` 仅接受 hash。
>
> **v0.1.4** 对齐 musicdl 第三方源、按探测结果重排默认链；移除失效源并更新 API 文档。
>
> **v0.1.3** 新增链接校验模块，过滤试听片段；优化酷我 yyy001 超时与 fail-fast。

## 特性

- 纯 Python + `requests`，无 musicdl 依赖
- 统一入口 `music_dl`，通过 `name`（`qq` / `wy` / `kw` / `kg`）切换平台
- 统一音质四档：`best` / `lossless` / `high` / `standard`（默认 `lossless`）
- 多源自动重试；`id` 为空时可仅凭 `keyword` 搜索并解析第一条结果
- 各平台可独立使用（`music_dl.modules.qq` 等）

## 快速开始

### 安装

**从 Gitee 克隆**

```bash
git clone https://gitee.com/bluetune/music_dl.git
cd music_dl

python -m venv .venv
.venv\Scripts\activate        # Windows
# source .venv/bin/activate   # Linux / macOS

pip install -e .

# 可选：网易云 official / 部分 eapi 源
pip install cryptography
```

或直接通过 pip 安装（无需克隆）：

```bash
pip install git+https://gitee.com/bluetune/music_dl.git
```

不安装到环境时，也可在项目目录下直接运行脚本（需已 `pip install -r requirements.txt`）。

### 统一接口（推荐）

```python
from music_dl import parse

# 有 id — 精确解析（keyword 可省略）
r = parse("qq", "001xd0HI0X9GNq")
r = parse("wy", "347230")
r = parse("kw", "6871880")
r = parse("kg", "B3A52A7A958BF0AED0EBFBA2E9A818B7")

# 无 id — 仅凭 keyword 搜索第一条（四平台均支持）
r = parse("qq", "", "一路向北-周杰伦")
r = parse("wy", "", "告白气球 周杰伦")
r = parse("kw", "", "一路向北 周杰伦")
r = parse("kg", "", "晴天 周杰伦")

if r.ok:
    print(r.platform)          # qq / wy / kw / kg
    print(r.song_id)           # 实际解析到的歌曲 ID
    print(r.method)            # direct_* 或 search_first
    print(r.download_url)      # HTTP 下载链接
    print(r.link.quality)      # 统一音质档位
    print(r.link.source)       # 命中的数据源，如 vkeys、cgg
    print(r.elapsed_s)         # 耗时（秒）
```

### 指定音质

```python
from music_dl import parse, UnifiedQuality

r = parse("qq", "001xd0HI0X9GNq", quality="high")
r = parse("wy", "347230", quality=UnifiedQuality.STANDARD)
```

| 档位 | 说明 |
|------|------|
| `best` | 最高可用（可能含母带，体积大） |
| `lossless` | 无损（**默认**） |
| `high` | 高音质，约 320k |
| `standard` | 标准，约 128k |

## 解析规则

`parse(name, song_id, keyword="", ...)` 按 **id 是否为空** 分两种模式：

| 模式 | 条件 | 行为 |
|------|------|------|
| **精确模式** | `song_id` 非空 | 只解析该 ID；任一源成功即返回，`method=direct_*`；全部失败则 `failed` |
| **搜索模式** | `song_id` 为空且 `keyword` 非空 | 调用平台搜索 API，取**第一条**结果再解析，`method=search_first` |
| **无效输入** | `song_id` 与 `keyword` 均为空 | 直接 `failed` |

要点：

- 传入 **错误 ID** 时直接 `failed`，**不会**用 keyword 搜索结果的第一条顶替（避免 silent wrong success）
- 搜索模式成功时，`r.song_id` 为**实际解析到的 ID**（不再留空）；`r.link.extra` 含 `requested_keyword`
- `keyword` 在精确模式下**不参与**解析，可省略

**`method` 取值**

| 值 | 含义 |
|----|------|
| `direct_mid` / `direct_id` / `direct_rid` | 凭传入 ID 解析成功 |
| `search_first` | id 为空，搜索第一条后解析成功 |
| `failed` | 解析失败 |

### 复用解析器实例

```python
from music_dl import MusicDLParser

parser = MusicDLParser(
    qq_cookies={...},   # 可选，QQ 官方 vkey
    wy_cookies={...},   # 可选，网易云 official
    kg_cookies={...},   # 可选，酷狗 official
)

r = parser.parse("qq", "001xd0HI0X9GNq", quality="lossless")

# 搜索列表：四平台均返回 UnifiedSongMeta
items = parser.search("kg", "晴天 周杰伦", limit=5)
for m in items:
    r = parser.parse(m.platform, m.song_id, quality="lossless")
```

## 平台与 ID

| name | 平台 | song_id | 示例 |
|------|------|---------|------|
| `qq` | QQ 音乐 | `mid` | `001xd0HI0X9GNq` |
| `wy` | 网易云 | 数字 ID | `347230` |
| `kw` | 酷我 | `rid` | `6871880` 或 `MUSIC_6871880` |
| `kg` | 酷狗 | 32 位 `hash` | `B3A52A7A...` |

别名：`tx`→qq，`163`/`netease`→wy，`kuwo`→kw，`kugou`→kg。

`keyword` 格式建议 `歌名-歌手` 或 `歌名 歌手`，**仅在 `song_id` 为空时必填**。

## 项目结构

```
musicdl_test/
├── README.md
├── pyproject.toml
├── requirements.txt
├── music_dl/                 # 包根目录
│   ├── __init__.py
│   ├── music_dl.py           # 对外统一入口 parse / MusicDLParser
│   └── modules/              # 各平台实现
│       ├── qq.py
│       ├── wy.py
│       ├── kw.py
│       └── kg.py
└── docs/
    └── api.md
```

## 文档

- [docs/api.md](./docs/api.md) — 完整 API、各平台模块、底层数据源 HTTP 接口

## 独立模块

各平台也可单独导入：

```python
from music_dl.modules.qq import QQDLParser, QQQuality
from music_dl.modules.wy import NeteaseDLParser, NeteaseQuality
from music_dl.modules.kg import KugouDLParser, KugouQuality
from music_dl.modules.kw import KuwoDLParser, KuwoQuality

# 或从包根 re-export
from music_dl import QQDLParser, NeteaseDLParser

# 直接访问对外层
from music_dl.music_dl import parse, MusicDLParser

r = QQDLParser().parse("001xd0HI0X9GNq", quality=QQQuality.MP3_320)
r = QQDLParser().parse("", "一路向北-周杰伦", quality=QQQuality.MP3_320)  # 搜索第一条
```

底层模块使用各平台专属音质枚举；统一入口见上文四档映射。

## 注意事项

- 返回 URL 多含 **vkey/签名**，有时效，过期需重新 `parse()`
- 版权 / VIP 歌曲可能全部源失败，与歌曲 ID 有关
- 搜索模式取**第一条**结果，keyword 不准确时可能解析到同名/相似歌曲
- QQ 使用 `best` 可能返回母带级大文件；日常推荐 `lossless` 或 `high`
- 网易云部分 ID（如 `186016` 晴天）可能无可用源，可试 `347230` 等
- 仅供学习与研究，请遵守各平台服务条款与版权法规

## 依赖

- 必需：`requests>=2.28.0`
- 可选：`cryptography`（网易云 official eapi 等）

## License

未指定许可证时请自行补充。使用第三方 API 时请遵守相应服务条款。