标签: Android Media3 ExoPlayer LibVLC MediaSession WebMusic

在私有音乐与 MV 媒体库项目 WebMusic 中,服务端通过 SMB 扫描会将 NAS 上的音频与视频统一索引入库。但在 Android 客户端实际使用中,我遇到了几个很典型的问题:

  1. 曲库里扫出来的视频,好像只有部分 MP4 能正常放,大量 MV 点开直接没反应或报错;
  2. 竖屏看 MV 时手机会按系统超时自动熄屏;
  3. 手动熄屏后,锁屏控制卡片显示的还是后台音频播放器,解锁回前台后视频画面变成黑屏。

今天花了一天时间从根因排查到架构重构,把 Android 端视频播放完整打通并推过了 GitHub Actions CI(最终构建版本 221b76a)。这里把排查思路与改造方案整理成笔记。


一、 先查清楚:为什么“只有 MP4 能放”?

连上生产库查了一下全库 758 首 MV 视频的格式分布,结果非常直观:

扩展名 数量 占比
.avi 372 49.1%
.mp4 307 40.5%
.mkv 64 8.4%
.ts 15 2.0%

将近一半(49.1%)的 MV 是 .avi!

而原版 Android 播放器存在两个问题:

  1. ExoPlayer(Media3)原生不支持 .avi 容器:Media3 使用自带的纯 Java Extractor(Mp4Extractor、MatroskaExtractor 等),压根没有 AVI 解复用器,也没有对旧版视频编码的软解支持。
  2. 错误静默吞掉:VideoPlayerDialog 之前没有监听 onPlayerError,解码失败时页面只剩黑屏或转圈,用户无法知道究竟是网络超时还是格式不支持。

二、 演进路线:从“兜底可见”到“双内核通吃”

1. 错误可见化 + 外部播放器兜底 + FFmpeg 音频软解(fcb1d76 ~ 7d8a515)

第一步先让问题“看得见”,并保证任何视频都有退路:

  • 在 VideoPlayerDialog 中监听 Player.Listener.onPlayerError 与 STATE_BUFFERING,在界面上直接展示错误码和底层 Exception 根因,并提供**「重试」与「外部播放器打开」**按钮(本地离线视频通过 FileProvider 授权,远端流携带 ?access_token= 交由 VLC / MX Player 等播放)。
  • 引入 org.jellyfin.media3:media3-ffmpeg-decoder:1.3.1+2(并开启 isCoreLibraryDesugaringEnabled = true),配置 EXTENSION_RENDERER_MODE_ON,优先硬解、遇到 AC-3 / E-AC3 / DTS 等音频轨自动回退到 FFmpeg 软解。

2. 为什么系统原生 MediaPlayer 也兜不住 .avi?最终上 LibVLC(e3be2e2 -> 7d8d485)

在排查中我们发现:手机自带“视频”App 能播放 .avi,但把它换成 Android 公共框架的 android.media.MediaPlayer + SurfaceView 后依然报 UNKNOWN_ERROR (what=1, extra=-2147483648)——说明手机厂商是把私有/FFmpeg 解码器打在了系统视频 App 内部,并没有开放给公共 MediaPlayer API。

为了不依赖外部 App,最终决定引入 org.videolan.android:libvlc-all:3.6.5,采用双内核智能路由:

  • .avi / .flv / .wmv / .rmvb 等 ExoPlayer 原生不支持的容器:直接交由内置 LibVLC 播放(顶部标注「VLC 内核」),省去先报错再切换的等待;
  • .mp4 / .mkv / .ts 等格式:优先走 ExoPlayer(享受 SimpleCache 边播边存、硬解低功耗和 DefaultExtractorsFactory CBR Seek),一旦遇到容器或解码异常再自动无缝切换至 LibVLC 兜底。

三、 播放体验打磨:常亮、缓冲与统一 MediaSession(b5a3660 -> 221b76a)

视频能播之后,紧接着解决了三个影响实际观感的细节问题:

1. 竖屏播放不再熄屏

原先 FLAG_KEEP_SCREEN_ON 只写在了 if (isFullscreen) 分支中,导致竖屏看 MV 很快自动熄屏。改为绑定播放状态:只要 isVideoPlaying && playbackError == null,无论横屏还是竖屏都保持屏幕常亮,暂停或关闭时立即释放。

2. 针对 NAS / SMB 大视频流的缓冲调优

为视频 ExoPlayer 配置了独立的 DefaultLoadControl:

  • bufferForPlaybackMs = 1500ms(加快起播)
  • minBufferMs = 15000ms、maxBufferMs = 60000ms(平滑应对 SMB 读取抖动)
  • backBufferDurationMs = 10000ms(保留 10 秒回溯缓存,小幅回拖不再重复发 HTTP Range 请求)
  • 同时开启 OkHttpClient.retryOnConnectionFailure(true) 与独立的视频 customCacheKey。

3. 统一音视频 MediaSession 与解决解锁黑屏

这是今天最核心的一次架构收敛。此前 VideoPlayerDialog 自己新建了一个独立 MediaSession,导致:

  • 锁屏后系统媒体通知仍被前台服务 PlaybackService 的音频 MediaSession 占据,显示的还是歌曲队列而不是当前 MV;
  • 手机熄屏时系统会销毁 SurfaceView,解锁回前台后 ExoPlayer / LibVLC 持有旧的或失效的视图表面,画面变成黑屏。

最终解法:

  1. 唯一的 MediaSession 收敛到 PlaybackService:
    • 在 PlaybackService 中增加 attachVideoPlayer(videoPlayer) 与 detachVideoPlayer(videoPlayer):进入视频时暂停后台音频并把唯一的 mediaSession.player 切换为视频播放器,退出视频(或重新点播音频队列)时归还给音频播放器,保留原音频队列和播放进度。
  2. 用 VlcSessionBridgePlayer 统一桥接双内核:
    • 继承 Media3 ForwardingPlayer,在 ExoPlayer 模式下直通底层;在 LibVLC 模式下把 LibVLC 的播放状态、总时长、当前进度以及锁屏的 Play / Pause / Seek 指令双向桥接给 MediaSession。
  3. 冻结主界面音频状态,防止状态串扰:
    • 在 MainActivity 中增加 PlaybackService.isVideoPlayerActive 保护,视频接管 MediaSession 期间不覆盖迷你播放条的歌曲信息、队列与歌词。
  4. 解决熄屏解锁黑屏:
    • ExoPlayer:监听 Lifecycle.Event.ON_STOP / ON_START,回前台后重新绑定 PlayerView.player 并触发当前位置刷新;
    • LibVLC:在 ON_STOP 时记录当前视频轨 ID 并主动 detachViews(),让音频继续在后台稳定输出并响应锁屏控制;在 ON_START 时通过递增 surfaceEpoch 重建全新的 VLCVideoLayout,重新 attachViews 并恢复视频轨与当前帧画面。

四、 今日提交汇总

Commit 说明
fcb1d76 接入 media3-ffmpeg-decoder 音频软解、错误提示浮层与外部播放器打开,新增 agent.md 调试规范
c13d778 开启 Core Library Desugaring 解决 AAR 元数据校验
7d8a515 在错误弹窗直接展示底层异常根因,放宽视频流读超时至 60s
b5a3660 修复竖屏播放熄屏、调优 DefaultLoadControl 缓冲参数、补充 MediaSession 初始对接
e3be2e2 增加原生 MediaPlayer 兜底与 DefaultExtractorsFactory CBR Seek(真机实测确认系统公共 API 仍无法解 .avi)
7d8d485 集成 LibVLC 3.6.5,实现 ExoPlayer + LibVLC 双内核自动路由与兜底
221b76a 统一音视频 MediaSession(VlcSessionBridgePlayer),解决锁屏控制错位与熄屏解锁黑屏

至此,Android 端的 MV 播放从“只能碰运气播 MP4”升级为支持全库 .avi / .mp4 / .mkv / .ts、支持离线与流式播放、且与后台音频服务完全协调的完整播放体验。