标签:
AndroidMedia3ExoPlayerLibVLCMediaSessionWebMusic
在私有音乐与 MV 媒体库项目 WebMusic 中,服务端通过 SMB 扫描会将 NAS 上的音频与视频统一索引入库。但在 Android 客户端实际使用中,我遇到了几个很典型的问题:
- 曲库里扫出来的视频,好像只有部分 MP4 能正常放,大量 MV 点开直接没反应或报错;
- 竖屏看 MV 时手机会按系统超时自动熄屏;
- 手动熄屏后,锁屏控制卡片显示的还是后台音频播放器,解锁回前台后视频画面变成黑屏。
今天花了一天时间从根因排查到架构重构,把 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 播放器存在两个问题:
- ExoPlayer(Media3)原生不支持
.avi容器:Media3 使用自带的纯 JavaExtractor(Mp4Extractor、MatroskaExtractor等),压根没有 AVI 解复用器,也没有对旧版视频编码的软解支持。 - 错误静默吞掉:
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边播边存、硬解低功耗和DefaultExtractorsFactoryCBR 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持有旧的或失效的视图表面,画面变成黑屏。
最终解法:
- 唯一的
MediaSession收敛到PlaybackService:- 在
PlaybackService中增加attachVideoPlayer(videoPlayer)与detachVideoPlayer(videoPlayer):进入视频时暂停后台音频并把唯一的mediaSession.player切换为视频播放器,退出视频(或重新点播音频队列)时归还给音频播放器,保留原音频队列和播放进度。
- 在
- 用
VlcSessionBridgePlayer统一桥接双内核:- 继承 Media3
ForwardingPlayer,在 ExoPlayer 模式下直通底层;在 LibVLC 模式下把LibVLC的播放状态、总时长、当前进度以及锁屏的 Play / Pause / Seek 指令双向桥接给MediaSession。
- 继承 Media3
- 冻结主界面音频状态,防止状态串扰:
- 在
MainActivity中增加PlaybackService.isVideoPlayerActive保护,视频接管MediaSession期间不覆盖迷你播放条的歌曲信息、队列与歌词。
- 在
- 解决熄屏解锁黑屏:
- ExoPlayer:监听
Lifecycle.Event.ON_STOP/ON_START,回前台后重新绑定PlayerView.player并触发当前位置刷新; - LibVLC:在
ON_STOP时记录当前视频轨 ID 并主动detachViews(),让音频继续在后台稳定输出并响应锁屏控制;在ON_START时通过递增surfaceEpoch重建全新的VLCVideoLayout,重新attachViews并恢复视频轨与当前帧画面。
- ExoPlayer:监听
四、 今日提交汇总
| 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、支持离线与流式播放、且与后台音频服务完全协调的完整播放体验。