pure_live v2.1.6 Android 播放状态专项修复:灰白播放器根因、音频模式独立后台播放与生命周期治理实录
pure_live v2.1.6 Android 播放状态专项修复:灰白播放器根因、音频模式独立后台播放与生命周期治理实录
本文以 docs/STAGE_UPDATE_2_1_6.md 为主线,结合 pure_live 当前仓库源码,完整还原 v2.1.6(源码版本
2.1.6+54)针对 Android 音频/视频模式切换与后台音频生命周期的专项修复:灰白播放器的真实根因与修复手法、issue #750 中音频模式作为独立后台播放条件的策略边界,以及基于 PJZ110 / Android 16 / ColorOS 真机的覆盖安装与切换验收方法。读者可以借此掌握 Flutter 播放器组件销毁重建竞态、串行状态队列、后台播放策略分层设计与真机回归的基本套路。
一、背景与版本定位
v2.1.6 是一次纯粹的 Android 播放状态修复版本,源码版本号为 2.1.6+54。它的两个核心目标分别是:
- 修复“灰白播放器”:用户在 Android 上快速切换“视频 → 纯音频 → 视频”模式时,播放区域出现灰白画面,被误认为直播线路返回了白色视频。
- 修复 issue #750:让“纯音频模式”成为独立的后台播放条件,不再依赖通用的“后台播放”总开关。
从当前仓库的版本演进看,该版本属于纯 Live 播放链路早期阶段的里程碑修复(仓库现版本已演进至 assets/version.json 中的 3.x 系列),其设计的策略分层与串行队列思想至今仍保留在 lib/domains/live/domain/live_player_facade.dart、lib/core/player/core 等核心模块中,可作为理解当前播放架构的起点。
二、灰白播放器根因:不是白色视频,而是 Flutter 的 ErrorWidget
2.1 根因判定
v2.1.6 首先纠正了一个关键认知:灰白区域并不是直播线路返回的白色视频帧,而是 Flutter 发布模式(release)下,组件在构建(build)阶段发生异常时渲染的默认 ErrorWidget(灰底白字错误占位)。
这一点与当前仓库代码相互印证:lib/domains/live/presentation/playback/widgets/video_player/video_controller_panel.dart 中定义了自定义的 ErrorWidget(展示 play_video_failed 文案与“重试”按钮),但若组件树在更底层的构建环节抛错且未被接管,Flutter 引擎会回退到框架内置的灰白错误占位——两者画面表现相近,极易被误判为“线路问题”。因此排查的第一步应是确认日志中是否存在 Flutter 构建异常,而不是怀疑 CDN 线路。
2.2 竞态产生的机制
v2.1.6 文档指出,旧实现在模式切换时存在三处交叉:
- 先销毁后重建:旧实现先销毁 media_kit / MediaCodec 底层播放器,再从组件树移除旧的视频控制器;
- 异步迟到回调:新控制器以异步方式开始播放,其播放结果回调可能晚于组件树的销毁/重建完成;
- 结果交叉绑定:迟到的播放结果回调重新绑定到旧 Surface 上,与已卸载的旧组件形成“鬼影”绑定。
2.3 新实现的四项关键设计
v2.1.6 的新实现围绕“先卸载组件、再销毁底层”与“串行化请求”展开:
- 先卸载旧视频组件并等待一帧,再销毁底层播放器,避免销毁动作与正在渲染的纹理/Surface 竞争;
- 所有模式请求通过串行队列执行,积压操作只应用最后一次目标状态(即“合并去重”而非“依次执行”);
- 播放器组件在一次构建中固定使用同一个播放器快照,并防御“历史画面适配索引越界”以及“关闭外层检查通过后底层引用又被异步清空”的窗口;
- 新播放器初始化可等待,
hardDispose会作废旧播放会话,避免迟到的播放结果重新绑定旧 Surface。
上述“串行队列 + 只应用最后一次状态”的设计理念,在当前仓库中仍能找到同构实现。例如 lib/core/utils/latest_async_value_queue.dart 中的 LatestAsyncValueQueue<T>:它在内部维护 _pending / _active 状态,submit() 期间若新的请求到达,只覆盖 _pending,队列 drain 时只应用最新值,从而保证“积压操作只应用最后一次目标状态”。它被 lib/core/player/core/background_playback_service.dart 用于 Android CPU/Wi-Fi 保活开关的串行化,可视为 v2.1.6 串行化思想在当前代码库中的延续。
三、issue #750:音频模式成为独立的后台播放条件
3.1 策略变化要点
issue #750 的核心诉求是:用户手动切换到纯音频模式(如戴耳机听直播)后,退到桌面或锁屏时播放不应中断,即使通用“后台播放”开关是关闭的。v2.1.6 的改动如下:
- 音频模式 = 独立后台播放条件,不依赖通用“后台播放”开关;
- 退到桌面或锁屏时,音频模式保持媒体会话(MediaSession)、前台服务(foreground service)与 CPU/Wi-Fi 保活;通知栏播放状态继续与播放器同步;
- 普通视频且后台播放关闭时仍按原设计暂停;
- 睡眠会话(sleep session)与显式后台播放开关保持原行为,不受影响。
3.2 源码中的策略分层印证
当前仓库中,该决策被收敛到三个小而清晰的文件,正是 v2.1.6 引入的“策略边界”的直接延续:
- lib/core/player/core/background_playback_policy.dart:
BackgroundPlaybackPolicy.shouldContinue(...)是唯一的决策点,接受backgroundPlaybackEnabled、sleepSessionActive、audioOnlySessionActive三个输入。值得注意的是,其返回值只由backgroundPlaybackEnabled || sleepSessionActive决定,并特意将audioOnlySessionActive保留在参数边界内——“让调用方不能在共享决策点之外意外引入纯音频的绕过逻辑”。也就是说,纯音频的“后台继续”在策略层并不直接打开全局保活,而是通过生命周期协调器与前台媒体服务共同承担。 - lib/core/player/core/background_playback_service.dart:通过
MethodChannel('pure_live/background_playback')调用原生setKeepAlive方法,负责“仅在用户主动发起的后台播放期间持有 Android CPU/Wi-Fi 资源”,并维护sleepSessionActive、audioOnlySessionActive两个会话标记;其注释明确“前台媒体服务仍是进程存活的主要机制”。 - lib/core/player/core/live_audio_service.dart:
shouldContinueInBackground汇总三个条件;setPlayer(..., audioOnly: ...)会把audioOnlySessionActive = audioOnly并调用syncKeepAlive();睡眠定时器到期时自动触发暂停命令(分钟数经clamp(1, AppSettingsController.maxSleepMinutes)收敛)。
从源码结构可以进一步推断出“睡眠会话与显式后台播放开关保持原行为”的实现路径:
- 睡眠会话:由 lib/core/player/core/live_audio_service.dart 的
_armSleepTimer负责,到期后清除sleepSessionActive并调用_pauseCommand,与 v2.1.6 文档描述的“睡眠会话保持原行为”一致; - 显式后台播放开关:对应
BackgroundPlaybackService.setKeepAlive与syncKeepAlive(),即SettingsService.to.app.enableBackgroundPlay.v。
3.3 生命周期协调:hidden 延迟与音频恢复
v2.1.6 文档提到“退到桌面或锁屏时音频模式保持媒体会话、前台服务与保活”,背后是生命周期状态机的精细控制。lib/core/player/core/playback_lifecycle_coordinator.dart 中的 PlaybackLifecycleCoordinator 实现了:
- 对
hidden/paused/detached统一进入_enterHiddenState(),对resumed进入_enterResumedState(); - 进入隐藏态时:若
_isAudioOnly()先提交_commitAudioOnlyPowerSaving()(纯音频省电提交);若shouldContinueInBackground()为真则直接返回(不暂停),否则等待hiddenPauseDelay(默认 1500ms)后再执行_applyHiddenPause。这个 1500ms 的窗口专门用于合并 Android 在旋转、进入画中画或替换 Surface 时连续发出的 hidden/paused 事件,避免误暂停; - 回到前台时:若处于纯音频且非睡眠会话,调用
_prepareAudioOnlyVideoRestore()准备视频轨恢复,再根据 pause token 决定是否续播;token 过期(房间/线路变化或用户显式命令)则不会复活旧会话。
这一设计正好支撑了 v2.1.6 验收中“关闭通用后台播放后进入纯音频、退到桌面 15 秒,媒体会话仍为 PLAYING(3)、音频前台服务保持运行”的结果——普通视频路径在 hiddenPauseDelay 后被暂停,而纯音频路径在策略层被放行。媒体会话的挂载入口可参见 lib/core/player/kernel/player_kernel_service.dart 的 MediaSessionBootstrap.attachTo(...)。
四、音频模式的房间级语义:从全局开关到房间动作
v2.1.6 文档未展开的另一个细节是“音频模式现在是独立的后台播放条件”背后的房间级(room-scoped)语义。当前仓库将其固化如下:
- 入口控件为播放页顶栏的耳机按钮
AudioOnlyButton(lib/domains/live/presentation/playback/widgets/video_player/video_controller_panel.dart),它监听audioModeSwitching(进行中禁用按钮)与isAudioOnly,通过controller.toggleAudioOnly()触发切换,高亮色使用0xFFFFD166区分开/关态;按钮始终显示耳机图标(headphone_line/headphone_fill),与“投屏”的电视图标明确区分; VideoController.changeAudioOnlyMode(...)(lib/domains/live/presentation/playback/widgets/video_player/video_controller.dart)负责向LivePlayerFacade.setAudioOnlyMode(value)下发命令,并回写audioOnlyState;失败时回滚到切换前的状态并rethrow;toggleAudioOnly()(video_controller.dart)在切换前会等待房间首次初始化完成(initialization.timeout(_playerManager.audioModeSwitchTimeout),超时 5 秒),防止初始 source/track 选择的旧audioOnly参数覆盖本次点击;- 配置层:lib/core/config/player_settings_controller.dart 中原来的全局
audioOnly字段已注释为“为旧备份保留的惰性兼容字段”,音频模式现在由房间动作或 ASMR 自动启动控制。
五、纯音频与视频解码的取舍:占位视频判定
v2.1.6 修复涉及“音频模式切换”时是否停止视频解码的决策,当前仓库以纯函数策略文件 lib/core/player/core/audio_only_mode_policy.dart 表达:
bool audioOnlyStopsVideoDecoding({required bool entering, required bool stopVideoDecoding}) {
return !entering || stopVideoDecoding;
}
对应测试 test/core/player/audio_only_mode_policy_test.dart 给出了三条边界:
- 手动切进纯音频不关视频解码:画面只是被盖住,视频组件留在树上继续解码渲染——这是“切回即时”的前提,无需重建纹理、不用重新等首帧,帧心跳也不会断;
- 助眠自动进入纯音频时关闭视频解码以省电;
- 退出纯音频总是恢复视频轨,不记录“当初是谁设的”,避免助眠关掉视频轨后退出只置标记、留下“有声无画”的房间。
此外,由于部分平台(如 kilakila、missevan)本身就是音频平台,lib/core/player/core/dummy_video_policy.dart 定义了 isDummyVideoSize(短边 ≤ 32 判定为占位视频轨)与 audioOnlyPlatforms 集合;test/core/player/dummy_video_policy_test.dart 验证了 16×16 与 32×32 是占位、33×33 不是,1080×2280 竖屏与 144p 不会被误判,未知尺寸(0 或负数)不算占位(应显示加载态)。这些判定与 pictureCoverFor(audioOnly: ..., dummyVideo: ...) 一起在 lib/domains/live/presentation/playback/widgets/video_player/video_player.dart 的 _buildVideo 中消费,决定封面图的显示时机。
六、构建目标与真机验收
6.1 构建目标
v2.1.6 的构建目标为:优先构建正式包名 com.mystyle.purelive 的 arm64-v8a APK,并在 Android 16 / ColorOS 真机做覆盖安装回归。该包名在当前仓库 android/app/build.gradle.kts 中依然有效(namespace 与 applicationId 均为 com.mystyle.purelive)。文档同时明确:其他平台源码不受 Android 生命周期策略影响——后台播放/保活相关代码(如 BackgroundPlaybackService 中的 if (!Platform.isAndroid) return;)均按平台隔离。
6.2 覆盖安装验收要点
验收过程本身也值得作为回归模板复用:
- 覆盖升级路径:从
2.1.5+53覆盖升级到2.1.6+54,要求包名与签名证书保持一致,首次安装时间与用户数据均保留; - 连续切换回归:在 PJZ110 / Android 16 / ColorOS 上连续完成 5 轮“视频 → 纯音频 → 视频”切换,最终视频持续渲染;日志中无 Flutter 构建异常、崩溃或 ANR;
- 后台保活回归:关闭通用“后台播放”后进入纯音频模式并退到桌面 15 秒,媒体会话仍为
PLAYING(3),音频前台服务保持运行;测试结束后恢复用户原有的后台播放开关。
6.3 质量门禁
v2.1.6 发布前通过了四道门禁:
- Built-in Kotlin 审计(Android 原生层审计);
- Flutter Analyze(静态分析无告警);
- 96 项 Flutter 测试全部通过——纯音频解码策略、占位视频判定等策略测试均属于该集合,可参见 test/core/player 下的用例;
- 26/26 平台公开接口探测通过。
七、总结与启发
v2.1.6 的修复给 Flutter 直播播放器带来三点可复用的工程经验:
- 先定性、再修复:灰白画面先确认是
ErrorWidget还是视频内容,避免把 UI 异常误判成线路故障而浪费排查时间; - 组件树与底层播放器的生命周期分离:先卸载组件并等待一帧,再销毁底层播放器;所有模式请求串行化并只应用最后目标状态,配合可等待的初始化与
hardDispose会话作废,杜绝迟到回调绑定旧 Surface; - 后台播放策略分层:把“通用后台播放”“睡眠会话”“音频模式”拆成独立条件,由唯一的策略决策点(
BackgroundPlaybackPolicy.shouldContinue)与生命周期协调器(PlaybackLifecycleCoordinator)共同治理,兼顾用户意图与系统资源。
这些设计的源码至今仍保留在 lib/core/player/core、lib/domains/live/domain/live_player_facade.dart 与 lib/domains/live/presentation/playback/widgets/video_player 中,配合 test/core/player 的边界测试,可以作为继续研究 pure_live 播放架构的入口。