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

如果你的 App 要同时满足 hls、rtsp、弹幕、外挂字幕和投屏，又不想被单一内核锁死，GSYVideoPlayer 值得一看。它和单内核封装的差异在于：IJKPlayer、Media3（ExoPlayer）、MediaPlayer、AliPlayer 走同一套控制与缓存层，运行时可切换。

一个控件包四个内核：GSYVideoPlayer 是什么

GSYVideoPlayer 的价值在"分层"：业务层只操作 StandardGSYVideoPlayer 这类控件，内核、缓存、渲染层都能替换。它解决的是"这个格式播不了、下个版本换内核，业务代码全要重写"的老问题。

能力面一览（完整清单见仓库根目录 README_CN.md）：

类别	提供什么
协议	h263/4/5、HLS、RTSP、RTMP、HTTPS、DASH（Media3）等
缓存	边播边缓存；代理缓存（默认）与 Exo SimpleCache 可换
媒体	SRT/WebVTT 外挂字幕、弹幕、滤镜水印、GIF 截图、帧截图
播放	单例/多个同时播放、列表滑动自动播、无缝切换、多清晰度切换
窗口	全屏/小窗、前后台暂停不黑屏、16K page size 适配
扩展	DLNA/UPnP 投屏（可选模块）、Jetpack Compose 接入

GSYVideoPlayer 分层架构：业务层只碰控件，内核、缓存、渲染各自可替换

Android 视频播放第一屏：接入与最小示例 📦

接入的最快路径是三步：加依赖、放控件、调 setUp。

// module 的 build.gradle（Maven Central） implementation 'io.github.carguo:gsyvideoplayer:14.0.0'

StandardGSYVideoPlayer videoPlayer = findViewById(R.id.video_player); videoPlayer.setUp("https://example.com/video.mp4", true, "视频标题"); videoPlayer.setIsTouchWiget(true); // 滑动调节亮度/音量

XML 侧只需在布局里声明一行 StandardGSYVideoPlayer。两个容易漏的细节：承载播放的 Activity 必须在 manifest 配置 configChanges（orientation、screenSize 等），否则旋转会重建页面；v14 下 ex_so 整包与独立 ABI 模块不要同时引入，会重复 so。完整配置见快速上手文档。

切换播放内核：IJK、Media3、MediaPlayer、AliPlayer

同一个控件可以换不同底层内核，选型逻辑比较直接：

内核	底层	什么时候用
IJKPlayer（默认）	FFmpeg n5.1.10	格式兼容优先：h263、RTSP、RTMP、concat 等
Media3（ExoPlayer）	Google Media3	DASH、HLS 自适应清晰度、SimpleCache 缓存
MediaPlayer	系统原生	要稳、包小，只播常见 mp4
AliPlayer	云内核	需要云能力，官方已支持 16K page size

全局切换就一行，缓存层可以一并换：

PlayerFactory.setPlayManager(IjkPlayerManager.class); // IJK，默认 PlayerFactory.setPlayManager(Exo2PlayerManager.class); // Media3 CacheFactory.setCacheManager(ProxyCacheManager.class); // 代理缓存，支持所有内核

格式支持细节看 DECODERS.md，自编译 so 看 BUILD_SO.md。

典型业务场景怎么做

官方 demo 就是一本"样例册"，绝大多数场景都有可运行示例，先照着抄再写代码（demo 目录：app/src/main/java/com/example/gsyvideoplayer/）。

列表播放

核心是"一个播放器、多个控件"：用 setPlayTag + setPlayPosition 标记当前播到哪一项，滑出屏幕统一释放，生命周期挂 GSYVideoManager 的 onPause / onResume / releaseAllVideos。两种模式的完整代码见 USE.md，示例入口在 SimpleListVideoActivityMode1。

其他高频场景

边播边缓存：默认代理缓存即可；m3u8 需切 Exo 缓存（ExoPlayerCacheManager），注意 Exo 缓存目录被锁时会自动回退非缓存路径；
外挂字幕：SRT/WebVTT 跨内核通用，Media3 内嵌字幕可桥接到同一套 UI，见 SUBTITLE_CN.md；
滤镜与 GL 效果：LUT 调色、美颜、Bloom、多 pass 模糊等，见 RECENT_FEATURES.md；
投屏：可选 gsyvideoplayer-cast 模块（minSdk 26），投屏后可按本地进度续播，断开再无缝回本地；
Compose 接入：Wrapper 一行嵌入，或 Native 模式完全自绘控制层，见 COMPOSE_USE.md。

背景铺满模糊播放：把播放器当页面背景用的常见形态

播放不出来的时候：常见报错与排查 ⚠️

坑大多集中在下面四类，官方问题集锦是标准答案册，先翻它再搜索：

症状	看哪里	怎么处理
混淆后 ClassNotFoundException、全屏崩溃	反射规则未保留	按 QUESTION.md 的规则保留 PlayerFactory/CacheFactory/播放器构造器，别整包 keep
找不到 so、加载失败	ABI 不匹配	检查 ndk abiFilters 与所选模块一致，用 Analyze Apk 验证打包
依赖拉不到	Jitpack 历史丢包	迁到 Maven Central（11.0.0 起）
全屏/旋转时重建、自动停止	manifest 配置缺失	Activity 加 configChanges