KugouMusic.NET播放源解析原理:音质URL获取与VIP权益判定全流程

原创2026-10-24 18:46:181,907 阅读

KugouMusic.NET播放源解析原理:音质URL获取与VIP权益判定全流程

KugouMusic.NET 是一款基于 .NET 10 与 Avalonia 的轻量级跨平台酷狗音乐客户端。本文用尽量少的代码,带你完整拆解它的播放源解析原理:一首歌点击播放后,客户端如何判断音质 URL 从哪来、如何自动降级音质、又如何判定 VIP 权益,最终把可用的音频地址交给播放器。

KugouMusic.NET 跨平台酷狗音乐客户端主界面

一、播放源从哪里来:四种来源的优先级路由

播放器要做的第一件事,不是联网,而是搞清楚"这首歌到底从哪放"。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 中,流程是这样的:

  1. 用用户设置的音质得到请求名次(如 flac = 2);
  2. 调用 SongClient.cs 的 GetPrivilegeLiteAsync,向酷狗 media.store.kugou.com 的 /v2/get_res_privilege/lite 接口查询这首歌当前账号实际拥有的全部音质;
  3. 如果账号拥有的最高音质名次 低于 请求名次(比如想要 flac 但只有 320),就把有效音质降为最高可用档,并写一条降级日志;
  4. 否则维持原请求音质。

也就是说,客户端会"先问权益、再发请求",避免拿一个注定 403 的音质去打取址接口。

KugouMusic.NET 设置页中的播放与音质相关选项

三、酷狗返回的权益数据长什么样:递归的 relate_goods

这是整个判定流程里最"反直觉"的一步。接口返回的 PrivilegeLiteResponse.cs 中,PrivilegeLiteData 是一个自引用结构:

  • quality:音质标识(128、320、flac、high,甚至 viper_atmos 等音效档);
  • privilege:权限标识,通常 8 = 免费,10 = VIP / 付费;
  • relate_goods:关联的其他音质商品——同结构的子节点,里面又套着更多音质。

所以"这首歌我到底能听哪些音质"不是一拍即得,而是对整棵 relate_goods 树做深度遍历。PlaybackSourceResolver.cs 中的 EnumerateSupportedQualities 用一个显式栈 + HashSet 去重,把所有合法音质枚举出来再取最高名次,既不会死循环也不会漏档。

在 KugouMusic.NET 中搜索歌曲并选择音质的播放界面

四、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 失败,触发后续恢复流程。

KugouMusic.NET 每日推荐页签

五、请求如何签名: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. 先正常解析,成功或来源不适用则直接返回;
  2. 失败且来源是酷狗曲库 / 用户云时,进入恢复流程(带 1 分钟冷却,防止刷接口);
  3. 恢复动作一:调用登录客户端 RefreshSessionAsync 刷新会话,拿到新的 Token 与 VIP 凭证;
  4. 恢复动作二:若来源是曲库,顺带尝试 每日 VIP 权益(见 VipEntitlementService.cs)——先查领取记录,若当天未领则执行"领取一天 VIP + 升级 VIP 奖励"两步;
  5. 恢复成功后重试一次播放源解析,把新结果返回给播放器。

整个过程对最终用户完全透明:多数情况下,你只会看到歌曲"卡了一下"然后正常播放。

KugouMusic.NET 播放界面歌词与播放控制示意

七、一张图看懂全流程

点击播放
   │
   ├─ 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,从"界面层"一路追到"协议层",即可完整复刻本文的播放源解析原理。

登录后查看全文
KugouMusic.NET