pure_live v2.1.6 Android 播放状态专项修复:灰白播放器根因、音频模式独立后台播放与生命周期治理实录

原创2026-10-14 13:20:281,455 阅读
文章标签:音视频直播跨平台移动开发桌面应用

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。它的两个核心目标分别是:

  1. 修复“灰白播放器”:用户在 Android 上快速切换“视频 → 纯音频 → 视频”模式时,播放区域出现灰白画面,被误认为直播线路返回了白色视频。
  2. 修复 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 的新实现围绕“先卸载组件、再销毁底层”与“串行化请求”展开:

  1. 先卸载旧视频组件并等待一帧,再销毁底层播放器,避免销毁动作与正在渲染的纹理/Surface 竞争;
  2. 所有模式请求通过串行队列执行,积压操作只应用最后一次目标状态(即“合并去重”而非“依次执行”);
  3. 播放器组件在一次构建中固定使用同一个播放器快照,并防御“历史画面适配索引越界”以及“关闭外层检查通过后底层引用又被异步清空”的窗口;
  4. 新播放器初始化可等待,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 给出了三条边界:

  1. 手动切进纯音频不关视频解码:画面只是被盖住,视频组件留在树上继续解码渲染——这是“切回即时”的前提,无需重建纹理、不用重新等首帧,帧心跳也不会断;
  2. 助眠自动进入纯音频时关闭视频解码以省电;
  3. 退出纯音频总是恢复视频轨,不记录“当初是谁设的”,避免助眠关掉视频轨后退出只置标记、留下“有声无画”的房间。

此外,由于部分平台(如 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 发布前通过了四道门禁:

  1. Built-in Kotlin 审计(Android 原生层审计);
  2. Flutter Analyze(静态分析无告警);
  3. 96 项 Flutter 测试全部通过——纯音频解码策略、占位视频判定等策略测试均属于该集合,可参见 test/core/player 下的用例;
  4. 26/26 平台公开接口探测通过。

七、总结与启发

v2.1.6 的修复给 Flutter 直播播放器带来三点可复用的工程经验:

  1. 先定性、再修复:灰白画面先确认是 ErrorWidget 还是视频内容,避免把 UI 异常误判成线路故障而浪费排查时间;
  2. 组件树与底层播放器的生命周期分离:先卸载组件并等待一帧,再销毁底层播放器;所有模式请求串行化并只应用最后目标状态,配合可等待的初始化与 hardDispose 会话作废,杜绝迟到回调绑定旧 Surface;
  3. 后台播放策略分层:把“通用后台播放”“睡眠会话”“音频模式”拆成独立条件,由唯一的策略决策点(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 播放架构的入口。

登录后查看全文
pure_live