qqmusic-api-python 0.6.5__tar.gz → 0.6.7__tar.gz

{qqmusic_api_python-0.6.5 → qqmusic_api_python-0.6.7}/.github/workflows/docs.yml

@@ -41,14 +41,16 @@ jobs:
         env:
           OUTPUT: docs/release-notes.md
           GITHUB_REPO: ${{ github.repository }}
+      - name: Export web requirements.txt
+        run: uv export --format requirements.txt --group web --output-file web/requirements.txt
       - name: Commit
         run: |
           git checkout main
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
           set +e
-          git add docs/release-notes.md
-          git commit -m "🧹 chore(release-notes): 更新 release notes"
+          git add docs/release-notes.md web/requirements.txt
+          git commit -m "🧹 chore(release): 更新 release notes 及 web 依赖"
           git push origin main
       - name: Build with zensical
         run: uv run zensical build

{qqmusic_api_python-0.6.5 → qqmusic_api_python-0.6.7}/AGENTS.md

@@ -49,6 +49,5 @@
 
 ## Agent behavior
 
-* 每次回答都以 `皇上启奏:` 开头。
 * **核心规约**：遵循 `docs/contributing.md` 中的详细规约。**在执行任务前，必须完整阅读该指南以确保合规。**
 * 仅在明确要求时，才能 `git commit` 或 `git push`。

{qqmusic_api_python-0.6.5 → qqmusic_api_python-0.6.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qqmusic-api-python
-Version: 0.6.5
+Version: 0.6.7
 Summary: QQ音乐API封装库
 Project-URL: documentation, https://l-1124.github.io/QQMusicApi/
 Project-URL: homepage, https://l-1124.github.io/QQMusicApi/

qqmusic_api_python-0.6.7/docs/coding.md

@@ -0,0 +1,428 @@
+# API 编写指南
+
+`qqmusic_api` 采用 `Client + ApiModule + Request` 的结构:
+
+* `Client` 负责网络发送、平台信息和凭证。
+* `ApiModule` 负责声明接口参数，并返回可 `await` 的 `Request`。
+
+## 调用流程图
+
+### 单请求
+
+```text
+模块方法
+  -> self._build_request(...)
+  -> Request
+  -> await request
+  -> Client.execute(request)
+  -> Client.request_api(...)  (根据 request.is_jce 分发改用 JCE 或 JSON 协议)
+  -> Client._build_result(...)
+  -> 返回原始 dict / TarsDict 或 Pydantic 模型
+```
+
+### 批量并发请求
+
+```text
+多个模块方法
+  -> self._build_request(...)
+  -> Request 列表
+    -> Client.gather(requests)
+    -> 按协议、平台、公共参数和凭证分组
+    -> 每组按 batch_size 拆分为批量请求
+    -> 依次调用 Client.request_api(..., lazy=True) 生成响应任务
+    -> 使用客户端内部的 multiplexed AsyncSession 并发执行这些任务（self._session.gather）
+    -> 按 req_n 解析每个响应项
+    -> 按输入顺序返回结果
+```
+
+`gather` 的分组边界由 `Request._group_key` 决定。只有协议类型、显式平台、公共参数和凭证相同的请求才会合并到同一个批量请求中。
+
+## 编写新的 API
+
+### 添加新模块
+
+1. 在 `qqmusic_api/modules/` 下创建新文件，例如 `foo.py`。
+2. 定义模块类，继承 `ApiModule`。
+3. 在 `Client` 中注册为 `@cached_property`。
+
+```python
+# qqmusic_api/modules/foo.py
+from ._base import ApiModule
+
+
+class FooApi(ApiModule):
+    """Foo 相关 API."""
+
+    def get_something(self, id: int):
+        """获取某项数据."""
+        return self._build_request(
+            module="music.foo.Svc",
+            method="GetSomething",
+            param={"id": id},
+        )
+```
+
+```python
+# qqmusic_api/core/client.py
+from functools import cached_property
+
+class Client:
+    @cached_property
+    def foo(self) -> "FooApi":
+        from ..modules.foo import FooApi
+        return FooApi(self)
+```
+
+### 添加新的请求方法
+
+API 方法返回 `Request` 对象，不直接发起请求。使用 `self._build_request(...)` 工厂方法构建：
+
+```python
+def get_detail(self, song_id: int):
+    """获取歌曲详情."""
+    return self._build_request(
+        module="music.songDetail",       # 接口所属模块
+        method="GetDetail",              # 方法名
+        param={"songid": song_id},       # 业务参数
+    )
+```
+
+对于非标准 CGI 接口（如直接 GET 请求），使用 `self._request(...)`：
+
+```python
+async def quick_search(self, keyword: str) -> dict[str, Any]:
+    """快速搜索 (直接返回解析后的 JSON 数据)."""
+    resp = await self._request(
+        "GET",
+        "https://c.y.qq.com/splcloud/fcgi-bin/smartbox_new.fcg",
+        params={"key": keyword},
+    )
+    resp.raise_for_status()
+    return resp.json()["data"]
+```
+
+### `_build_request` 参数说明
+
+| 参数             | 类型                        | 说明                                                      |
+|------------------|-----------------------------|-----------------------------------------------------------|
+| `module`         | `str`                       | 接口所属模块名                                            |
+| `method`         | `str`                       | 方法名                                                    |
+| `param`          | `dict`                      | 业务参数                                                  |
+| `response_model` | `type[BaseModel]` 或 `None` | 响应模型，为 None 时返回原始 dict                         |
+| `comm`           | `dict` 或 `None`            | 附加的公共参数                                            |
+| `override_comm`  | `bool`                      | 为 True 时 `comm` 完全替代自动生成的参数；为 False 时合并 |
+| `credential`     | `Credential` 或 `None`      | 覆盖本次请求的凭证                                        |
+| `platform`       | `Platform` 或 `None`        | 覆盖本次请求的平台                                        |
+| `is_jce`         | `bool`                      | 是否作为 JCE (Tars) 二进制协议发送                        |
+| `preserve_bool`  | `bool`                      | 是否保留布尔值原样（默认转为 0/1 整型）                   |
+| `sign`           | `bool`                      | 是否对请求进行签名                                        |
+| `pager_meta`     | `PagerMeta` 或 `None`       | 分页元数据，提供后返回 `PaginatedRequest`                 |
+| `refresh_meta`   | `RefreshMeta` 或 `None`     | 换一批元数据，提供后返回 `RefreshableRequest`             |
+
+### `client.request` 参数说明
+
+`client.request` 是底层 HTTP 请求方法，自动装配凭证 Cookies 和平台 User-Agent：
+
+| 参数         | 类型                   |                                                                              说明 |
+|--------------|------------------------|----------------------------------------------------------------------------------:|
+| `method`     | `str`                  |                                                   HTTP 方法，如 `"GET"`、`"POST"` |
+| `url`        | `str`                  |                                                                          请求地址 |
+| `credential` | `Credential` 或 `None` |                                            覆盖本次请求的凭证，默认使用客户端凭证 |
+| `platform`   | `Platform` 或 `None`   |                                            覆盖本次请求的平台，默认使用客户端平台 |
+| `lazy`       | `bool`                 |                                                  是否延迟发送请求（用于批量并发） |
+| `**kwargs`   |                        | 透传给底层 `niquests` 的参数（`params`、`json`、`data`、`headers`、`cookies` 等） |
+
+!!! note
+
+    `client.request` 返回的是原始 `niquests.Response` 对象，需要手动解析响应。而 `_build_request` 返回的 `Request` 对象支持 `await`，会自动完成响应验证和模型解析。
+
+常见用法：
+
+```python
+# GET 请求
+resp = await client.request("GET", "https://example.com/api", params={"key": "value"})
+
+# POST JSON
+resp = await client.request("POST", "https://example.com/api", json={"key": "value"})
+
+# POST form data
+resp = await client.request("POST", "https://example.com/api", data={"key": "value"})
+
+# 自定义 headers
+resp = await client.request("GET", "https://example.com/api", headers={"X-Custom": "value"})
+
+# 覆盖凭证
+resp = await client.request("GET", "https://example.com/api", credential=my_credential)
+```
+
+## 响应模型
+
+### 基础用法
+
+每个响应模型都应继承 `models.request.Response`：
+
+```python
+from pydantic import Field
+
+from .request import Response
+
+
+class MyResponse(Response):
+    """我的响应模型."""
+
+    name: str
+    count: int
+```
+
+`Response` 基类配置了 `frozen=True`（不可变）和 `extra="ignore"`（忽略多余字段）。
+
+### JSONPath 字段映射
+
+可以通过 `Field(json_schema_extra={"jsonpath": ...})` 声明字段的 JSONPath 映射路径，自动从嵌套响应中提取数据：
+
+```python
+class SonglistMeta(Response):
+    """歌单元数据示例."""
+
+    id: int = Field(json_schema_extra={"jsonpath": "$.result.tid"})
+    dirid: int = Field(json_schema_extra={"jsonpath": "$.result.dirId"})
+    name: str = Field(json_schema_extra={"jsonpath": "$.result.dirName"})
+```
+
+对于列表字段，使用 `[*]` 通配符：
+
+```python
+class CommentListResponse(Response):
+    """评论列表响应."""
+
+    comments: list[Comment] = Field(
+        default_factory=list,
+        json_schema_extra={"jsonpath": "$.commentlist[*]"},
+    )
+```
+
+### 字段别名
+
+Pydantic 的 `validation_alias` 支持多别名兼容：
+
+```python
+class Singer(Response):
+    """歌手信息."""
+
+    id: int = Field(
+        default=-1,
+        validation_alias=AliasChoices("id", "singerID", "singerId", "SingerID"),
+    )
+    mid: str = Field(
+        default="",
+        validation_alias=AliasChoices("mid", "singerMid", "singerMID"),
+    )
+```
+
+### 需登录的接口
+
+需要登录的接口应通过 `_require_login` 校验凭证：
+
+```python
+def get_vip_info(self, *, credential: Credential | None = None):
+    """获取 VIP 信息."""
+    target_credential = self._require_login(credential)
+    return self._build_request(
+        module="VipLogin.VipLoginInter",
+        method="vip_login_base",
+        param={},
+        credential=target_credential,
+        response_model=UserVipInfoResponse,
+    )
+```
+
+## 翻页与换一批
+
+### 连续翻页
+
+通过 `pager_meta` 声明连续翻页能力，返回的请求对象会暴露 `.paginate()`：
+
+```python
+from ..core.pagination import OffsetStrategy, PagerMeta, ResponseAdapter
+
+
+def get_detail(self, songlist_id: int, num: int = 10, page: int = 1):
+    """获取歌单详情."""
+    return self._build_request(
+        module="music.srfDissInfo.DissInfo",
+        method="CgiGetDiss",
+        param={
+            "disstid": songlist_id,
+            "song_begin": num * (page - 1),
+            "song_num": num,
+        },
+        response_model=GetSonglistDetailResponse,
+        pager_meta=PagerMeta(
+            strategy=OffsetStrategy(offset_key="song_begin", page_size_key="song_num"),
+            adapter=ResponseAdapter(
+                has_more_flag="hasmore",
+                total="total",
+                count=lambda response: len(response.songs),
+            ),
+        ),
+    )
+```
+
+### 换一批
+
+通过 `refresh_meta` 声明换一批能力，返回的请求对象会暴露 `.refresh()`：
+
+```python
+from ..core.pagination import BatchRefreshStrategy, RefreshMeta, ResponseAdapter
+
+
+def get_related_mv(self, songid: int, last_mvid: str | None = None):
+    """获取歌曲相关 MV."""
+    return self._build_request(
+        module="MvService.MvInfoProServer",
+        method="GetSongRelatedMv",
+        param={"songid": str(songid), "songtype": 1, "lastmvid": last_mvid or 0},
+        response_model=GetRelatedMvResponse,
+        refresh_meta=RefreshMeta(
+            strategy=BatchRefreshStrategy(refresh_key="lastmvid"),
+            adapter=ResponseAdapter(
+                has_more_flag="has_more",
+                cursor=lambda response: response.mv[-1].id if response.mv else None,
+            ),
+        ),
+    )
+```
+
+### 内置策略速查
+
+| 策略                             |     适用场景 | 关键参数                        |
+|----------------------------------|-------------:|---------------------------------|
+| `PageStrategy`                   |     页码递增 | `page_key`                      |
+| `OffsetStrategy`                 |   偏移量滑窗 | `offset_key` + `page_size_key`  |
+| `CursorStrategy`                 | 响应游标回写 | `cursor_key`                    |
+| `MultiFieldContinuationStrategy` |   多字段续翻 | 自定义 `build_next_params` 函数 |
+| `BatchRefreshStrategy`           |       换一批 | `refresh_key`                   |
+
+`pager_meta` 与 `refresh_meta` 不能同时声明。
+
+## JCE (Tars) 协议
+
+部分接口使用 JCE 二进制协议而非 JSON。通过 `is_jce=True` 启用：
+
+```python
+def get_something(self):
+    """获取数据 (JCE 协议)."""
+    return self._build_request(
+        module="music.foo.Svc",
+        method="GetSomething",
+        param={0: "value"},  # JCE 使用整数 key
+        is_jce=True,
+    )
+```
+
+JCE 协议的响应会自动解码为 `TarsDict`。
+
+## 请求签名
+
+部分接口需要对请求体进行签名。通过 `sign=True` 启用：
+
+```python
+def get_sheet(self, mid: str):
+    """获取曲谱."""
+    return self._build_request(
+        module="music.mir.SheetMusicSvr",
+        method="GetMoreSheetMusic",
+        param={"songMid": mid},
+        sign=True,
+    )
+```
+
+签名后请求会发送到 `musics.fcg` 而非 `musicu.fcg`，并在 URL 参数中附加 `_`（时间戳）和 `sign`。
+
+## 公共参数 `comm`
+
+默认情况下，`comm` 参数由 `VersionPolicy.build_comm()` 自动生成。可以通过 `comm` 附加额外参数：
+
+```python
+# 合并到自动生成的 comm 中（默认行为）
+self._build_request(
+    ...,
+    comm={"extra_key": "value"},
+)
+```
+
+使用 `override_comm=True` 完全替代自动生成的参数：
+
+```python
+self._build_request(
+    ...,
+    comm={
+        "g_tk": 5381,
+        "uin": "",
+        "format": "json",
+        "inCharset": "utf-8",
+        "outCharset": "utf-8",
+        "notice": 0,
+        "needNewCode": 1,
+    },
+    override_comm=True,
+)
+```
+
+## 编写测试
+
+测试文件放在 `tests/` 下，按模块命名（如 `test_song.py`）。
+
+### 基本格式
+
+```python
+"""歌曲模块测试."""
+
+import pytest
+
+from qqmusic_api import Client
+
+
+async def test_query_song(client: Client) -> None:
+    """测试根据 ID 查询歌曲."""
+    result = await client.song.query_song(["003w2xz20QlUZt"])
+    assert result.tracks
+    assert result.tracks[0].name
+```
+
+### 使用 parametrize
+
+```python
+@pytest.mark.parametrize("page", [1, 2])
+async def test_general_search(client: Client, page: int) -> None:
+    """测试综合搜索翻页."""
+    result = await client.search.general_search("周杰伦", page=page)
+    assert result.song.items is not None
+```
+
+### 需要登录的测试
+
+使用 `authenticated_client` fixture：
+
+```python
+async def test_get_vip_info(authenticated_client: Client) -> None:
+    """测试获取 VIP 信息."""
+    result = await authenticated_client.user.get_vip_info()
+    assert result.vip_flag is not None
+```
+
+### 测试分页
+
+```python
+async def test_search_paginate(client: Client) -> None:
+    """测试搜索分页."""
+    pager = client.search.search_by_type("周杰伦", num=5).paginate(limit=2)
+
+    assert pager.has_more() is True
+    first_page = await pager.next()
+    assert pager.has_more() is True
+    second_page = await pager.next()
+
+    assert first_page.song
+    assert second_page.song
+```

{qqmusic_api_python-0.6.5 → qqmusic_api_python-0.6.7}/docs/release-notes.md

@@ -1,4 +1,64 @@
 
+## What's Changed
+
+### 功能更新
+
+* **(web)** 添加 has_sheet 路由 ([9e7a143](https://github.com/L-1124/QQMusicApi/commit/9e7a1439ff597ae43a4ef99d88ec08ee32889b9a)) by [@L-1124](https://github.com/L-1124)
+
+### 文档更新
+
+* 完善快速开始文档并新增多篇核心教程 ([d6143cd](https://github.com/L-1124/QQMusicApi/commit/d6143cdc047ebeb4963b061680a21103ba3d58d4)) by [@L-1124](https://github.com/L-1124)
+
+### 贡献者
+
+* @L-1124
+* @github-actions[bot]
+
+## [[0.6.6](https://github.com/L-1124/QQMusicApi/compare/v0.6.5..v0.6.6)] - 2026-06-13
+
+### Bug 修复
+
+* **(song)** 修复 get_sheet 获取无曲谱歌曲时触发异常的问题 ([f47a643](https://github.com/L-1124/QQMusicApi/commit/f47a643e956ef52a532b0017ea8365cb2537593d)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 修复评论适配器与凭证锁内存泄漏，优化基础设施 ([66a6cc4](https://github.com/L-1124/QQMusicApi/commit/66a6cc4901b1acd99b0c4541f88a1d8e0a9b0888)) by [@L-1124](https://github.com/L-1124)
+
+### Revert
+
+* **(models)** 回退 BaseModel 额外字段处理策略为 extra='ignore' ([f6691e0](https://github.com/L-1124/QQMusicApi/commit/f6691e078b87a45f5178d7a018f9a1bd0d5e391a)) by [@L-1124](https://github.com/L-1124)
+
+### 功能更新
+
+* **(client)** 支持 zzc 请求签名 ([eb4eb66](https://github.com/L-1124/QQMusicApi/commit/eb4eb66f5c20c2adbe430bbfb11140d0431d48d5)) by [@L-1124](https://github.com/L-1124)
+* **(core)** 支持在使用 allow_error_codes 放行时强制解析模型 ([fac2a71](https://github.com/L-1124/QQMusicApi/commit/fac2a71bfb2f2ea700d59215a439fc65b40461f2)) by [@L-1124](https://github.com/L-1124)
+* **(core)** 支持通过 override_comm 彻底替代通用请求载荷 ([72edb4f](https://github.com/L-1124/QQMusicApi/commit/72edb4f3cc96a063643f2d58b92d41722ad95e8f)) by [@L-1124](https://github.com/L-1124)
+* **(song)** 添加新的曲谱相关 API和相关示例 ([9c461db](https://github.com/L-1124/QQMusicApi/commit/9c461dbdff15acf804ae047a7bc827cd6b1e7dd5)) by [@L-1124](https://github.com/L-1124)
+* **(song)** 支持 HasSheetMusic 接口检查歌曲是否有曲谱 ([94723ff](https://github.com/L-1124/QQMusicApi/commit/94723ffda911f74d680f7f661e9436bba74c3612)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 补充 requirements.txt ([d806214](https://github.com/L-1124/QQMusicApi/commit/d80621477635f6e0ad3589116cbb97c75e31dc6c)) by [@L-1124](https://github.com/L-1124)
+
+### 性能优化
+
+* **(qrc)** 优化自定义 3DES 解密性能并补充测试 ([0b808a5](https://github.com/L-1124/QQMusicApi/commit/0b808a5537643f2c3bd0ef94e5c72263ec378bb8)) by [@L-1124](https://github.com/L-1124)
+
+### 构建配置
+
+* **(web)** 在 Dockerfile 运行命令中添加 --no-sync 防止容器运行期同步 dev 依赖 ([cf1fbc5](https://github.com/L-1124/QQMusicApi/commit/cf1fbc5523c83b21734d82763a89aef450825674)) by [@L-1124](https://github.com/L-1124)
+
+### 贡献者
+
+* @L-1124
+* @github-actions[bot]
+
+## [[0.6.5](https://github.com/L-1124/QQMusicApi/compare/v0.6.4..v0.6.5)] - 2026-06-12
+
+### Bug 修复
+
+* **(core)** 开启 allow_incoming_cookies=False 防止上下请求的 cookies 污染 ([1cd1b69](https://github.com/L-1124/QQMusicApi/commit/1cd1b69338ffa2f26409480490b18b9c9080a29e)) by [@L-1124](https://github.com/L-1124)
+* **(login)** `Platform.WEB` 的 `check_expired` 总是返回 True ([f0b4533](https://github.com/L-1124/QQMusicApi/commit/f0b4533e7c172b6cb5b0556fbd7ff13e8b20f4c7)) by [@L-1124](https://github.com/L-1124)
+
+### 贡献者
+
+* @L-1124
+* @github-actions[bot]
+
 ## [[0.6.4](https://github.com/L-1124/QQMusicApi/compare/v0.6.3..v0.6.4)] - 2026-06-12
 
 ### Bug 修复

{qqmusic_api_python-0.6.5 → qqmusic_api_python-0.6.7}/docs/tutorial/client.md

@@ -76,10 +76,6 @@ client = Client(credential=credential)
 
 默认的请求平台是 `android`，如果需要可以在初始化时覆盖：
 
-!!! note
-
-    部分 API 的请求平台是固定的，无法覆盖。
-
 ```python
 import asyncio
 
@@ -91,10 +87,21 @@ async def main():
         ...
 
 
-asyncio.run(_main())
-
+asyncio.run(main())
 ```
 
+支持的平台：
+
+| 平台 | `Platform` 值 | 说明 |
+| ------ | -------------- | ------ |
+| Android | `Platform.ANDROID` | 默认，大部分接口使用 |
+| Desktop | `Platform.DESKTOP` | QQ 音乐桌面端 |
+| Web | `Platform.WEB` | QQ 音乐网页端 |
+
+!!! note
+
+    部分接口的请求平台是固定的，传入 `platform` 参数不会生效。例如 `get_detail` 固定使用 Web 平台，`send_authcode` 固定使用 Android 平台。
+
 ## 设备信息
 
 可通过 `device_path` 参数指定设备信息文件的路径进行持久化存储：

qqmusic_api_python-0.6.7/docs/tutorial/download.md

@@ -0,0 +1,124 @@
+# 下载歌曲
+
+获取歌曲文件链接需要登录凭证。基本流程：先获取 CDN 节点，再请求文件地址。
+
+## 基本用法
+
+```python
+import asyncio
+import random
+
+from qqmusic_api import Client, Credential
+from qqmusic_api.modules.song import SongFileInfo
+
+
+async def main() -> None:
+    credential = Credential(musicid=123456, musickey="Q_H_L_xxx")
+    async with Client(credential=credential) as client:
+        cdn_dispatch = await client.song.get_cdn_dispatch()
+        cdn = random.choice(cdn_dispatch.sip)
+
+        urls = await client.song.get_song_urls(
+            [SongFileInfo(mid="003w2xz20QlUZt")]
+        )
+        for info in urls.data:
+            if info.purl:
+                print(f"{info.mid}: {cdn}{info.purl}")
+
+
+asyncio.run(main())
+```
+
+## 检查下载权限
+
+通过 `query_song` 获取歌曲信息后，可从 `pay` 字段判断是否需要付费：
+
+```python
+song = await client.song.query_song(["003w2xz20QlUZt"])
+track = song.tracks[0]
+
+# pay_play: 1=需要付费播放, 0=免费
+# pay_down: 1=需要付费下载, 0=免费
+# pay_month: 1=需要绿钻/付费包
+if track.pay.pay_month == 1:
+    print("需要绿钻或付费包权限")
+elif track.pay.pay_down == 1:
+    print("需要单独付费下载")
+else:
+    print("可免费下载")
+```
+
+请求文件链接后，`UrlinfoItem.result` 会返回授权结果码：
+
+| result   | 含义                       |
+|----------|----------------------------|
+| `0`      | 成功，`purl` 可用          |
+| `104003` | 无权限（未登录或等级不够） |
+| `104004` | VKey 获取失败              |
+| `104013` | 播放设备受限               |
+
+```python
+urls = await client.song.get_song_urls([SongFileInfo(mid="003w2xz20QlUZt")])
+for info in urls.data:
+    if info.result == 0 and info.purl:
+        url = cdn + info.purl
+        print(f"可下载: {url}")
+    else:
+        print(f"无法下载 (result={info.result})")
+```
+
+## 检查文件是否存在
+
+`query_song` 返回的 `file` 字段包含各音质的文件大小，值为 `0` 表示该音质不存在：
+
+```python
+song = await client.song.query_song(["003w2xz20QlUZt"])
+track = song.tracks[0]
+
+file = track.file
+if file.size_flac > 0:
+    print(f"FLAC 无损可用, 大小: {file.size_flac / 1024 / 1024:.1f} MB")
+if file.size_320mp3 > 0:
+    print(f"MP3 320k 可用, 大小: {file.size_320mp3 / 1024 / 1024:.1f} MB")
+if file.size_128mp3 > 0:
+    print(f"MP3 128k 可用, 大小: {file.size_128mp3 / 1024 / 1024:.1f} MB")
+```
+
+## 同时获取多种音质
+
+`get_song_urls` 支持在一次请求中为同一首歌请求不同音质。为每首歌构造多个 `SongFileInfo`，指定不同的 `file_type`：
+
+```python
+from qqmusic_api.modules.song import SongFileInfo, SongFileType
+
+song_mid = "003w2xz20QlUZt"
+media_mid = "003w2xz20QlUZt"  # 从 track.file.media_mid 获取
+
+urls = await client.song.get_song_urls(
+    [
+        SongFileInfo(mid=song_mid, file_type=SongFileType.MP3_128, media_mid=media_mid),
+        SongFileInfo(mid=song_mid, file_type=SongFileType.FLAC, media_mid=media_mid),
+        SongFileInfo(mid=song_mid, file_type=SongFileType.OGG_320, media_mid=media_mid),
+    ]
+)
+
+for info in urls.data:
+    if info.result == 0 and info.purl:
+        print(f"{info.filename}: {cdn}{info.purl}")
+```
+
+常用的 `SongFileType`：
+
+| 枚举值    | 音质      | 格式              |
+|-----------|-----------|-------------------|
+| `MP3_128` | 标准音质  | MP3 128k          |
+| `MP3_320` | HQ 高品质 | MP3 320k          |
+| `OGG_192` | HQ 高品质 | OGG 192k          |
+| `OGG_320` | HQ 高品质 | OGG 320k          |
+| `FLAC`    | SQ 无损   | FLAC              |
+| `OGG_640` | SQ 无损   | OGG 640k          |
+| `MASTER`  | 臻品母带  | FLAC 24Bit/192kHz |
+
+!!! tip
+
+    `ACC_96`音质部分 VIP 歌曲即使未登录或无会员，也可能通过该音质获取到播放链接（试听级别）。