KugouMusic.NET播放源解析原理:音质URL获取与VIP权益判定全流程
KugouMusic.NET播放源解析原理:音质URL获取与VIP权益判定全流程
KugouMusic.NET 是一款基于 .NET 10 与 Avalonia 的轻量级跨平台酷狗音乐客户端。本文用尽量少的代码,带你完整拆解它的播放源解析原理:一首歌点击播放后,客户端如何判断音质 URL 从哪来、如何自动降级音质、又如何判定 VIP 权益,最终把可用的音频地址交给播放器。
一、播放源从哪里来:四种来源的优先级路由
播放器要做的第一件事,不是联网,而是搞清楚"这首歌到底从哪放"。PlaybackSourceResolver.cs 中的 ResolveAsync 方法按固定优先级依次判断四种来源:
| 优先级 | 来源 | 判定方式 |
|---|---|---|
| 1 | Jellyfin 媒体库 | jellyfin:// 伪路径或本地库来源标记 |
| 2 | 本地文件 | 本地文件路径存在且文件可读 |
| 3 | 酷狗用户云 | 歌曲标记为 UserCloud,需向用户云接口取址 |
| 4 | 酷狗曲库 | 默认路径,走完整的音质 + VIP 判定流程 |
只有走到第 4 种来源时,才会触发下文重点讲的音质 URL 获取与 VIP 权益判定。解析结果统一封装为 PlaybackSourceResult,并带上"来源"(本地 / Jellyfin / 用户云 / 曲库)和"失败原因"(需登录 / 资源不可用 / 返回空 URL),方便界面给出精准提示。
💡 设计亮点:本地与 Jellyfin 来源完全离线,不检查登录态;登录检查只发生在需要访问酷狗服务器的时候。
二、音质怎么定:音频等级排序与智能降级
用户设置的期望音质,不等于最终播放的音质。中间要过一道"权益校验"。
首先,AudioQuality.cs 定义了音质等级序列与名次(Rank):
| 常量 | 标识 | 含义 |
|---|---|---|
| Standard | 128 |
标准(128K) |
| High | 320 |
高品质(320K) |
| Lossless | flac |
无损 |
| HiRes | high |
Hi-Res 母带 |
在 PlaybackSourceResolver.cs 的 ResolvePlaybackQualityAsync 中,流程是这样的:
- 用用户设置的音质得到请求名次(如
flac= 2); - 调用 SongClient.cs 的
GetPrivilegeLiteAsync,向酷狗media.store.kugou.com的/v2/get_res_privilege/lite接口查询这首歌当前账号实际拥有的全部音质; - 如果账号拥有的最高音质名次 低于 请求名次(比如想要
flac但只有320),就把有效音质降为最高可用档,并写一条降级日志; - 否则维持原请求音质。
也就是说,客户端会"先问权益、再发请求",避免拿一个注定 403 的音质去打取址接口。
三、酷狗返回的权益数据长什么样:递归的 relate_goods
这是整个判定流程里最"反直觉"的一步。接口返回的 PrivilegeLiteResponse.cs 中,PrivilegeLiteData 是一个自引用结构:
quality:音质标识(128、320、flac、high,甚至viper_atmos等音效档);privilege:权限标识,通常 8 = 免费,10 = VIP / 付费;relate_goods:关联的其他音质商品——同结构的子节点,里面又套着更多音质。
所以"这首歌我到底能听哪些音质"不是一拍即得,而是对整棵 relate_goods 树做深度遍历。PlaybackSourceResolver.cs 中的 EnumerateSupportedQualities 用一个显式栈 + HashSet 去重,把所有合法音质枚举出来再取最高名次,既不会死循环也不会漏档。
四、VIP 权益判定:三个关键信号
判定"能不能听",KugouMusic.NET 综合了三类信号,而不只是看一眼用户是不是 VIP:
1. 会话信号 —— KgSession.cs
登录后,KgSessionManager 会把账号状态缓存为 KgSession 对象:UserId、Token、VipType(VIP 类型)、VipToken(VIP 凭证),并同步到 Cookie(vip_type / vip_token)。解析播放源前先检查:
Token为空 或UserId == "0"→ 直接返回 LoginRequired(需登录),不再浪费一次网络请求;VipType与VipToken会随取址请求一起提交,告诉服务器"这个账号是什么级别的会员"。
2. 音质级信号 —— privilege 字段
即上文的权益树:8 表示该音质免费可听,10 表示需要 VIP 或单独付费。客户端据此决定是否需要降级,而不是盲目请求。
3. 取址级信号 —— priv_status 字段
最终播放地址由 GET /v5/url(RawSongApi.cs 的 GetUrlAsync)返回,响应模型 SongModel.cs 中的 PlayUrlData 给出了"服务器说了算"的最终判定:
url列表非空 且status == 1→ 成功,取第一个非空地址交给播放器;priv_status == 1(RequiresVip)→ 该资源需要 VIP 权限;priv_status == 10(RequiresAlbumPurchase)→ 需要购买整张专辑;url为空 → 记为 EmptyUrl 失败,触发后续恢复流程。
五、请求如何签名:hash、dfid 与 V5 密钥
播放地址接口并不是"裸调",RawSongApi.cs 的 /v5/url 请求会组装一整套参数:
hash:酷狗曲库中每首歌的唯一指纹(搜索接口返回的FileHash),所有取址都围绕它展开;dfid/mid:设备标识。若会话中没有dfid,会临时生成 24 位随机串;mid由dfid计算得出;quality:经过上一步降级后的有效音质;特殊版本(如piano、acappella)会被改写成magic_xxx形式;- V5 签名:KGSigner.cs 中的
CalcV5Key用 MD5 对hash + 盐 + AppId + mid + userid计算密钥,随请求提交,服务端据此校验请求合法性。
签名失败或参数不对,接口就会返回 status != 1,对应"资源不可用"——这也是为什么客户端把"会话刷新"放在恢复流程的第一步。
六、失败了怎么办:播放源自愈与每日 VIP 领取
真实网络环境里,token 过期、VIP 到期都会导致取址失败。PlaybackSourceRecoveryService.cs 提供了一层"自愈"包装:
- 先正常解析,成功或来源不适用则直接返回;
- 失败且来源是酷狗曲库 / 用户云时,进入恢复流程(带 1 分钟冷却,防止刷接口);
- 恢复动作一:调用登录客户端
RefreshSessionAsync刷新会话,拿到新的 Token 与 VIP 凭证; - 恢复动作二:若来源是曲库,顺带尝试 每日 VIP 权益(见 VipEntitlementService.cs)——先查领取记录,若当天未领则执行"领取一天 VIP + 升级 VIP 奖励"两步;
- 恢复成功后重试一次播放源解析,把新结果返回给播放器。
整个过程对最终用户完全透明:多数情况下,你只会看到歌曲"卡了一下"然后正常播放。
七、一张图看懂全流程
点击播放
│
├─ Jellyfin / 本地文件 ──────────────► 直接播放(离线)
│
├─ 未登录?─────────────────────────► LoginRequired(提示登录)
│
├─ 用户云歌曲 ──► GetCloudUrl 取址 ─► 播放
│
└─ 曲库歌曲
│
├─ ① 查询权益树(/v2/get_res_privilege/lite)
│ 遍历 relate_goods → 得到拥有的全部音质
│ 请求音质高于可用最高档?──► 自动降级 + 日志
│
├─ ② 请求播放地址(/v5/url,V5 签名 + 会话 VIP 凭证)
│ status==1 且 url 非空 ──► 交给播放器
│
└─ ③ 失败 ──► 恢复服务:刷新会话 + 每日VIP领取 ──► 重试一次
八、小结:这套设计的三个"省心"
- 先问权益,再取地址:用一次轻量的权益查询,换取播放成功率与音质的最优平衡;
- 失败原因可解释:
LoginRequired/Unavailable/EmptyUrl三类失败码直达 UI 提示,用户知道该登录、等资源还是换来源; - 静默自愈:会话刷新与每日 VIP 领取封装在恢复服务里,配合冷却锁避免对服务器造成压力。
想进一步阅读源码,建议按这条路径走:PlaybackSourceResolver.cs → SongClient.cs → RawSongApi.cs → PlaybackSourceRecoveryService.cs,从"界面层"一路追到"协议层",即可完整复刻本文的播放源解析原理。




