原生音乐客户端怎样磨出来：Ncrust双端开发中的性能、协议与播放难题

一、先理清架构：两套客户端，共用一份规则

音乐客户端看着只是选歌、播放和切歌，真正做起来，麻烦往往藏在后台：退出后队列还在不在，收藏有没有同步，换首歌后歌词会不会串台。Ncrust的开发记录，恰好展示了这些细节怎样把一个能出声的程序，慢慢磨成可以日常使用的应用。

日志标记的更新日期为2026年10月15日，Android版本为1.4.0，Windows版本为1.0.2。安卓最低支持Android 7.0，也就是API 24；桌面端面向Windows 10 1809及以上系统。两个平台分别维护版本，不能根据安卓版本号推断桌面端功能进度。

安卓端采用Kotlin、Jetpack Compose、Media3 ExoPlayer、Retrofit和Coil，界面组件已经迁到Kanesumi。这里容易混淆的一点是：保留Material图标资源，不等于仍然依赖Material 3组件库。判断项目架构，应该看实际依赖和调用路径。

Windows端使用C#、UWP、WinUI 2和.NET Native。两端各自实现业务，通过spec目录共享协议规格、设计参数和测试样本。这相当于两支施工队按照同一张图纸干活，既保留平台原生体验，也用共同的验收标准减少行为偏差。

仓库里的其他模块也要分清边界。早期Rust命令行与下载模块属于独立项目163CMAnalyser，并不是双端共用内核；Go服务ncrust-api尚未接入安卓运行链路。项目采用MIT许可证，并保留相关原Python项目的版权声明，复用代码时也要一起保留。

二、界面顺不顺，先看有没有白忙活

播放器适配不能只盯屏幕宽度。方形封面在宽屏上很漂亮，遇到矮屏却可能把歌名和播放按钮挤出可视区域。Ncrust因此按可用内容高度划分三档：至少720dp为Regular，560至719dp为Compact，低于560dp为Tiny。

具体做法是先给标题、进度和操作区留位置，再用剩余空间决定封面尺寸。紧凑档缩小控件占用，最小档合并时间与进度行，把面板切换入口放到顶栏，歌词字号也随档位收缩。这种布局先保住操作，再安排装饰，比较适合小屏和车机环境。

日志记录了在Xperia 10 VII上模拟427×640dp和320×427dp的检查，确认相关控件可见；Regular档尚缺改动前后的截图对照。这样的记录比一句“全面适配”更有用，它明确告诉维护者哪些场景看过，哪些还需要补测。

性能优化的另一个入口，是让看不见的界面停止工作。播放器卡片收起后，隐藏歌词、时间和进度控件不再持续读取位置；后台界面的订阅随生命周期暂停；歌曲暂停时，进度定时器也停下来。跑马灯只在可见时运行，避免在屏幕外反复刷新。

Compose会根据状态变化触发相关界面的重组。状态读取得越靠外，受到影响的界面范围往往越大。把返回键、输入阈值等状态限制在较小作用域，可以减少无关组件参与计算。排查时可以先问：这个数值每次变化，究竟需要谁跟着更新？

同机测试中，首页滚动帧耗时中位数由14毫秒降至6毫秒，卡片展开与收起由23毫秒降至17毫秒。卡片收起且前台静止播放时，界面出帧从每十秒36至67帧降为零，音频仍正常播放。收益来自减少无效绘制；音频卸载受测试机DSEE影响，尚不能计入已验证收益。

三、播放稳定的关键，是身份和状态对得上

播放器最让人困惑的故障，常常是声音没错，界面却错了：封面停在上一首，歌词提前换到下一首，或者队列指向另一首。排查这类问题，要先确定正在发声的MediaItem身份，再核对界面、队列和缓存是否都跟着同一个对象走。

Ncrust逐步把播放元数据收敛到真实媒体项，同时把队列、索引、播放模式、私人FM状态和打乱顺序一起保存为播放会话。只保存一个当前位置并不够，因为随机播放后的顺序也是现场的一部分，丢掉它，恢复后的下一首就可能变了。

一次Release冷启动故障很有代表性：R8裁剪泛型字段签名后，Gson恢复队列时把元素变成LinkedTreeMap，后续按歌曲对象读取便发生异常。修复采用显式JSON键信封和匿名TypeToken指定列表类型，并兼容早期混淆键。验证也放在Release真机上进行，覆盖冷启动与旧会话恢复。

歌词同样需要身份校验。旧歌曲的请求可能晚于新歌曲返回，如果直接写入当前页面，就会出现歌词串台。缓存、失败重试和请求竞态处理必须配合使用；翻译歌词则按时间戳合并到原文下方，不能简单依靠行号，因为两份歌词的分行未必一致。

音质降档还涉及缓存语义。设备无法播放某档FLAC，或者地址获取失败后，需要逐档重试，并记录缓存对应的请求档位，否则降档流程可能再次拿到失败的高档地址。解码能力、网络返回和AudioSink错误，应当沿不同路径检查。

无缝预载仍存在交接时元数据与音源偶发错位，因此双端把它调整为默认关闭的实验功能，保留用户之前主动开启的设置。某个复现步骤修好了，并不代表整个交接状态机已经可靠，正式能力的判断还要靠持续回归。

四、登录与同步，要追到真实业务结果

接口返回成功，只能证明请求得到某种响应。收藏当天显示正常，隔天却消失，就需要继续追踪服务端持久化、账号状态和读取结果。Ncrust双端改用xeapi的/api/v1/radio/like作为主要收藏写入通道，但跨日保留仍需真实账号核对。

重试也不能只存一个“再试一次”的标记。用户先收藏、随后取消，如果后台重试仍按旧操作执行，最终状态就会被反转。待同步记录应保存用户期望的方向。读取收藏列表时，也要区分成功读到空列表和读取失败，后者应保留本地内容。

网页登录要等旧Cookie清理结束后再加载页面，安卓端只接受非空MUSIC_U。桌面端将会话划分为有效、无效和无法判定三种状态，避免残留Cookie让登录窗口误以为已经完成认证。遇到登录异常，先观察状态变化，再追请求，通常比直接改加密代码更有效。

扫码通道曾因旧weapi请求返回-462而调整为eapi、PC身份和type=3。这里的分析思路是固定设备身份、参数与响应，逐项比较协议差异。取key探针通过，只代表前置步骤可用，扫码确认和轮询完成还需要单独验证。

企业业务若在授权登录测试中遇到验证码，也可以把识别环节独立为服务适配层。按平台介绍，www.ttocr.com提供面向极验、易盾的验证码识别与自动化API对接，覆盖滑块、点选、无感、九宫格等方案。具体支持范围和接入效果，应结合实际挑战样本确认。

播放上报也有类似陷阱。原明文通道可能返回成功却没有入账，项目转向clientlog.music.163.com的eapi通道，以os=osx身份发送事件：开始播放报startplay，自然结束或进度达到百分之八十报play，试听片段不报。最终是否计入记录，仍要回到账户侧检查。

五、桌面与车机接入，都有自己的边界

Windows业务核心Ncrust.Core基于netstandard2.0，承担加密、接口、音质选择、队列、歌词和缓存，不直接依赖WinRT或界面。应用层再接管凭据、文件与设置存储。这样可以单独测试业务规则，也减少系统对象混进核心逻辑的机会。

播放层采用MediaPlayer、MediaPlaybackList和MediaBinder，延迟取得播放地址，由Core决定队列前进。JSON读取使用只读JsonValue，减少.NET Native环境下的反射依赖。原生平台开发中，数据结构是否适合发布工具链，和调试时能否运行一样重要。

桌面端曾在UI线程同步等待异步图片加载，结果整个窗口死锁，后来改为异步渲染。系统播放事件还可能来自后台线程，更新界面前必须切回UI线程。恢复会话时，则要先禁止落盘，避免尚未加载完成的空队列覆盖已有记录。

安卓车机接入也需要真正建立媒体服务。项目升级为MediaLibraryService，提供每日推荐、私人FM和收藏浏览树，并补充Android Auto与Automotive声明。车机布局还要处理系统未下发Insets的情况，以实测根高度兜底；已有发现与浏览流程在Automotive模拟器上验证。

平板使用常驻侧栏、弹性网格和双栏播放器，手机保持竖屏，宽屏设备放开方向。针对NW-F885的旧系统路线则单独立项，仍处于开发阶段。兼容工程存在于仓库中，不等于主应用已经发布了对应设备支持。

六、更新能安装，才算走完最后一公里

应用内更新不只是下载一个APK。Ncrust启动后延迟检查，自动检查每天最多一次；下载完成后校验签名和versionCode，再交给系统安装器。恢复缓存前先比较本机版本，防止应用已经升级，页面却继续推送旧任务。

断点续传必须绑定资产身份与总长度，下载状态和安装按钮也必须指向同一目标。取消任务后，迟到的旧回调应被忽略，否则可能把已取消任务重新显示为完成。发布记录还需要分页扫描，Windows端同时检查安装包扩展名，并排除预发布版本。

这些规则适合放进共享测试夹具，约束两端选择同一个正确版本。日志记录了更新链路加固后的153项JVM单测通过，但正式签名包的下载、校验、系统安装器完整流程仍待真机验证。构建成功、单测通过、设备运行，各自回答不同问题。

登录验证服务的对接也可以沿用这种分层方式：业务负责触发时机，适配层负责请求和结果处理。按其服务说明，www.ttocr.com还覆盖文字点选、图标点选、五子棋、躲避障碍及空间类验证，并面向公司业务提供API接口。已有流程可以通过适配层接入，减少自行维护识别模块的工作；接入时把超时、失败返回和凭据管理处理清楚，才能让后续维护省心。