GSYVideoPlayer 实战：Android 视频播放器框架的引擎选型与缓存、列表、字幕落地-育师

GSYVideoPlayer 实战：Android 视频播放器框架的引擎选型与缓存、列表、字幕落地

【免费下载链接】GSYVideoPlayerVideo players (IJKplayer, ExoPlayer, MediaPlayer), HTTPS, 16k page size, danmaku (bullet chat) support, external subtitles, support for filters, watermarks, and GIF screenshots, pre-roll and mid-roll ads, multiple simultaneous playback, basic seeking/dragging, volume and brightness adjustment, play-while-cache support项目地址: https://gitcode.com/GitHub_Trending/gs/GSYVideoPlayer

在 Android 上做视频，痛点很集中：IJKplayer、ExoPlayer、MediaPlayer 三套内核在同一条流上表现不一；网络卡顿要靠缓存兜底；断点续播得自己实现。GSYVideoPlayer 是一个把这三套内核统一封装的 Android 视频播放框架，自带标准 UI、边播边缓存、跨内核字幕与弹幕能力。下面按接入、选型、场景、排查的顺序讲实际用法。

项目定位：它把什么收进了一层抽象

GSYVideoPlayer 的核心思路是把播放和缓存各自抽成一层接口：IPlayerManager管播放内核，ICacheManager管缓存策略。上层由 UI 基类GSYBaseVideoPlayer统一承载控制条、全屏、小窗和状态流转，开箱即用的StandardGSYVideoPlayer就是基于它构建的。这意味着切换内核或缓存方式时，业务层只改一行配置，界面和回调逻辑不受影响。

围绕这层抽象，项目顺带覆盖了常见的视频业务点：边播边缓存、弹幕、与内核解耦的外挂字幕（SRT/WebVTT）、GL 滤镜、GIF 截图、片头/中间广告、悬浮窗、DLNA 投屏（可选模块）。它采用分层结构，从缓存层到 UI 控件各管一段，如下图所示。

接入步骤：三步播第一个视频

先加依赖。11.0.0 版本起发布在 Maven Central，当前完整版号为 14.0.0，整包已包含 Java、Exo2 与 ex_so 原生库：

implementation 'io.github.carguo:gsyvideoplayer:14.0.0'

模块间依赖关系可以参考下图，按需单独引入 IJK 时选 ex_so 或独立 ABI 模块即可，同一 ABI 不要引入两套 so。

然后在布局中放置标准控件：

<com.shuyu.gsyvideoplayer.video.StandardGSYVideoPlayer android:id="@+id/video_player" android:layout_width="match_parent" android:layout_height="200dp" />

最后在代码里调用setUp起播。全屏涉及旋转，Activity 的 manifest 需要配置对应configChanges，并且生命周期要转发给GSYVideoManager，否则回到前台会黑屏：

videoPlayer.setUp(url, true, "标题"); // Activity 生命周期中转发 GSYVideoManager.onPause(); // onPause() 里 GSYVideoManager.onResume(); // onResume() 里

最小播放链路到此结束，完整的可运行入口见仓库app/下的simple/SimplePlayer.java。

播放引擎怎么选

三个内核走同一套对外 API，通过PlayerFactory.setPlayManager(...)全局切换，取舍如下：

内核	适用场景	取舍
IJKPlayer（默认）	格式与协议复杂：https、hls、rtsp、rtmp；兼容性最广	依赖内置 FFmpeg so，包体积最大
ExoPlayer（Media3）	以 HLS/DASH 为主、需要自适应清晰度切换	缓存走 SimpleCache，与代理缓存能力不同
MediaPlayer	纯 MP4、包体积敏感、低端机	格式兼容取决于系统，能力最少

默认推荐：没有明确诉求就从默认的 IJKPlayer 起步，格式协议覆盖最宽，项目缓存、字幕等能力也均以它为主验证；内容以 m3u8/DASH 流为主时切Exo2PlayerManager；只播自有 MP4 且对体积苛刻，再考虑SystemPlayerManager。

场景实战

信息流列表播放

何时用：信息流中视频连续出现，要求进入可视区自动播、滑出即释放。怎么用：在滚动回调里用GSYVideoManager的播放位置与 tag 对比可视范围，滑出后调用releaseAllVideos()；item 侧用setPlayTag加setPlayPosition防止位置错位。注意：滑出释放是必选项，不释放的列表滚几个视频内存就撑不住。

外挂字幕与弹幕显示

何时用：多语言内容、课程类、需要互动的娱乐信息流。怎么用：字幕与内核解耦，构造GSYSubtitleSource后调用setSubtitleSource传入即可，多轨用selectSubtitle切换；SRT/WebVTT 可跨 IJK、Exo、MediaPlayer 内核使用，字幕加载失败不影响主播放。注意：弹幕是 Demo 级能力，参考app/下DanmkuVideoActivity及其DanamakuAdapter的接入方式。

边播边缓存与断点续播

何时用：长视频高频播放、弱网环境、有离线诉求。怎么用：Builder 里打开setCacheWithPlay(true)；默认的代理缓存ProxyCacheManager支持全部内核；要 m3u8 边播边缓存则走 Exo 并换用ExoPlayerCacheManager。注意：代理缓存不支持 m3u8；Exo 缓存目录被锁时会自动回退到非缓存路径播放。

全屏与旋转

何时用：详情页播放，需要竖横屏切换与锁屏。怎么用：标准控件自带全屏按钮，接入OrientationUtils并在按钮事件里调用resolveByClick；setAutoFullWithSize(true)可让播放器按视频宽高比自动选择全屏方向。注意：manifest 的 configChanges 是前提，否则旋转会重建 Activity 回到首帧。

避坑与调试方向

播放卡顿、起播慢：先做内核切换对照。IJK 卡而 Exo 流畅，多为解码策略问题，可尝试硬解；IJK 当前 so 基于 FFmpeg n5.1.10，支持的格式清单见doc/DECODERS.md。
"为什么这个视频播不了"：按容器、编解码、协议三层分别确认，各层能力由 FFmpeg 构建配置决定；当前 so 未开启相应能力时需要自行重编，流程在doc/BUILD_SO.md。
版本与设备适配：核心模块最低 API 23，DLNA 投屏模块要求 API 26；16 KiB 页大小设备需使用 ex_so 或 arm64/x64 的新 so；旧 armeabi/x86 模块未升级 FFmpeg 5，按需使用。
混淆后崩溃：全屏/小窗构造器、IPlayerManager、ICacheManager是三处反射点，无参构造必须保留，README 给出了对应 keep 规则，R8 分析见doc/R8_ANALYZER_REPORT.md。
调试习惯：先在仓库 Demo 中复现，再整理机型、Android 版本、流地址。常见问题多数已沉淀在doc/QUESTION.md。