GSYVideoPlayer 使用指南：一个 Android 视频播放器接入 IJK、ExoPlayer 与系统内核-育师

GSYVideoPlayer 使用指南：一个 Android 视频播放器接入 IJK、ExoPlayer 与系统内核

【免费下载链接】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

GSYVideoPlayer 是一个 Android 视频播放器框架，最核心的一点：同一套 UI 控件和 API，底下可以挂 IJKplayer、Media3(ExoPlayer)、MediaPlayer 甚至 AliPlayer 四个内核，切换只换注册方式，你的播放页、列表页、全屏逻辑一行不用改。依赖声明一下，控件扔进布局，setUp传个地址，画面就出来了。

项目定位

维度	说明
解决什么问题	不用自己在 FFmpeg 构建、多内核适配、渲染层和全屏切换上花时间
给谁用	需要接视频播放但不想自维护 so 和渲染层的 App 团队
和同类方案的差异	控件、内核、管理三层解耦，UI 换内核不改代码，反之亦然

内核层：IJKplayer、Media3(ExoPlayer)、MediaPlayer、AliPlayer，全局切换
缓存层：基于 AndroidVideoCache 的边播边缓存，Media3 走 SimpleCache
能力面：弹幕、外挂字幕（SRT / WebVTT）、滤镜、水印、GIF 截图、贴片广告
当前版本 v14：FFmpeg n5.1.10 + OpenSSL 3.5.9，arm64/armv7a/x64 适配 16K page size
协议覆盖：http(s)、hls、rtmp、rtsp、concat、mpeg 等

快速上手

声明 Maven 依赖

整包最省事，v14 的gsyvideoplayer聚合包已经带上 Java 层、Exo2 适配和三 ABI 的 IJK so：

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

想按 ABI 裁剪包体就分模块引：gsyvideoplayer-java当主库，再按需要加gsyvideoplayer-exo2，so 选ex_so或单个 ABI 的模块。⚠️ 同一个 ABI 不要两套 native 库同时引，这是后面高频踩的坑。

布局里放一个播放控件

StandardGSYVideoPlayer是默认布局最完整的控件：

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

各模块的依赖关系看这张图就能对上：

接好生命周期再 startPlayLogic

播放只有三行代码：

player.setUp("https://example.com/video.mp4", true, "标题"); player.startPlayLogic();

真正要记住的是生命周期。全屏状态下你手里的控件引用不是真正在播的那个实例，所有状态操作都走getCurrentPlayer()：

// onPause player.getCurrentPlayer().onVideoPause(); // onResume（直播场景传 false，不从原进度恢复） player.getCurrentPlayer().onVideoResume(false); // onDestroy player.getCurrentPlayer().release(); GSYVideoManager.releaseAllVideos();

功能亮点

边播边缓存

普通 http 视频在setUp时把cacheWithPlay传true，播放同时写入本地缓存目录，第二次打开秒开。适用场景：课程视频、剧集这类反复回看的点播内容。m3u8 和直播流反过来，必须传false。

一行代码换内核

内核注册走GSYVideoManager.setPlayManager(...)，四个内核实现同一套IPlayerManager接口，播放、暂停、状态回调的 API 对上层完全一致。格式吃不准、弱网卡顿，先换 Exo 或系统内核试试，业务代码不动。

跨内核的统一字幕层

外挂字幕不区分内核：SRT 和 WebVTT 在 IJK、Media3、MediaPlayer 上走同一套 UI 渲染，Media3 的内嵌 cues 也能桥接到这个图层。做国际化内容播放，不用为每个内核各写一遍字幕逻辑。

滤镜、水印与 GIF 截图

GL 渲染管线上叠加滤镜：美颜、LUT 调色、高斯/金字塔模糊、复古 CRT、故障风都在近期特性清单里。截图分两种：纯视频帧和带 UI 的整播放器画面，都能转 GIF。短内容和工具类 App 拿来做"分享当前画面"这类功能，不用自己写 GL 管线。

可选模块按需加

DLNA 投屏是独立的gsyvideoplayer-cast模块，核心包不背 Jetty 的重量；Jetpack Compose 项目有专门的 wrapper 模块。demo 应用里 50 多个 Activity 覆盖列表、ViewPager2、悬浮窗、折叠屏等场景，拿不准的用法直接翻 demo 对照。

实战走读：从列表进详情页播放

跟着 Demo 的 PlayActivity 走一遍完整链路：列表页点一条视频进详情页，带多清晰度切换和全屏旋转。

入口在onCreate，拿绑定、注册返回拦截、初始化播放器：

binding = ActivityPlayBinding.inflate(getLayoutInflater()); setContentView(binding.getRoot());

多清晰度播放：把每个源包成SwitchVideoModel组成列表，setUp传 list 而不是单个 url，UI 上直接出现清晰度菜单：

List<SwitchVideoModel> list = new ArrayList<>(); list.add(new SwitchVideoModel("普通", url1)); list.add(new SwitchVideoModel("清晰", url2)); binding.videoPlayer.setUp(list, false, "测试视频");

注意这里cacheWithPlay传了false——demo 源是 HLS，属于必须关缓存的场景。接着加封面图、显示标题栏、挂OrientationUtils处理全屏横竖屏切换，然后startPlayLogic()。

返回键逻辑值得抄：先判断当前是否全屏，是的话把点击交给全屏按钮（退出全屏），否则才释放并 finish：

if (orientationUtils.getScreenType() == ActivityInfo.SCREEN_ORIENTATION_LANDSCAPE) { binding.videoPlayer.getFullscreenButton().performClick(); return; } binding.videoPlayer.setVideoAllCallBack(null); GSYVideoManager.releaseAllVideos(); finish();

整条链路结束：暂停、恢复、退出全屏、释放，四件事都有明确归属，getCurrentPlayer()+release()是收尾的关键。

高频坑与直接修法

m3u8 / 直播流卡死或加载异常。缓存模块不支持 HLS。修法：这类源cacheWithPlay一律false，别为了秒开硬开。

同一个 ABI 引了两套 IJK so。比如ex_so和gsyvideoplayer-arm64同时上。结果不是崩就是加载到错的 so。修法：按 ABI 二选一，依赖文档有完整组合表。

全屏后暂停、释放不生效，或状态错乱。你操作的是外层控件，真正在播的是全屏克隆体。修法：所有状态操作统一player.getCurrentPlayer().xxx()，释放时再加GSYVideoManager.releaseAllVideos()兜底。

旋转后视频重头播或黑屏。屏幕旋转触发了 Activity 重建。修法：播放页在 Manifest 里配configChanges覆盖 orientation 和 screenSize，screenOrientation设为 portrait，把旋转交给OrientationUtils控制。

16K page size 新设备加载 so 失败。修法：用 v14 的 arm64/armv7a/x64 模块或ex_so，已适配；armv5 和老 x86 模块没升级 FFmpeg 5，只给存量旧架构项目用。