Document recent playback stability changes

CarGuo · CarGuo · commit b75480568fc5 · 2026-05-06T11:11:52.000+08:00
diff --git a/doc/ARCHITECTURE.md b/doc/ARCHITECTURE.md
@@ -13,6 +13,8 @@
 | 多 URL 清晰度切换 | Demo player + manager | `SmartPickVideo` 使用临时 manager 预加载新 URL，同步位置后提交；异常时回退原播放。 |
 | Exo 自适应清晰度 | Exo manager | HLS master / DASH MPD 使用同一个媒体时间线，清晰度自动选择交给 Media3 TrackSelector；固定清晰度通过 TrackSelectionOverride 实现。 |
 | 完成后保留最后一帧 | Demo player | `KeepLastFrameVideo` 只作为 Demo 级验证，不改变基础播放器默认完成态和释放策略。 |
+| 播放器初始化失败处理 | Manager + Player | `GSYVideoBaseManager` 和各 `IPlayerManager` 将内核创建/初始化异常收敛到错误回调和资源清理。 |
+| Exo cache 与 GIF 清理 | Cache + Utils | `ExoSourceManager` 管理 Exo cache 生命周期，`GifCreateHelper` 负责 GIF 生成状态和临时资源清理。 |
 
 更多入口、API 和回归说明见 [RECENT_FEATURES.md](RECENT_FEATURES.md)。
 
diff --git a/doc/GSYVIDEO_PLAYER_PROJECT_INFO.md b/doc/GSYVIDEO_PLAYER_PROJECT_INFO.md
@@ -9,6 +9,7 @@
 * **Manager 内核管理层**：GSYVideoManager（GSYVideoBaseManager <- GSYVideoViewBridge）。
 * **Video  播放器控件层**：GSYTextureRenderVIew 到 GSYVideoPlayer 五层。
 * **Render 渲染控件层**：TextureView、SurfaceView、GLSurfaceView（GSYRenderView <- IGSYRenderView）。
+* **扩展能力层**：字幕、预览、截图、GL 效果、清晰度切换等能力优先挂在 UI/Manager/Render 这些可替换层，避免直接污染内核层。
 
 **目前整个video层即是传统controller层，也是大部分时候自定义实现需要继承的层**
 
@@ -32,6 +33,24 @@
 
 **从这里看出，项目的播放内核、管理器、渲染层都是可以自定义替换的。**
 
+### 近期能力对应的层级
+
+近期新增和调整的播放能力，可以按下面方式理解：
+
+| 能力 | 所在层级 | 说明 |
+| --- | --- | --- |
+| 通用外挂字幕 | Video/UI 层 | `GSYSubtitleController` 和 `GSYSubtitleView` 根据播放器进度渲染 SRT/WebVTT，加载失败不影响主视频。 |
+| WebVTT 进度条预览 | Demo + Preview Provider | `PreViewGSYVideoPlayer` 消费 `GSYVideoPreviewProvider`，缩略图和 sprite 坐标由业务侧或服务端提供。 |
+| 截图 | Render + Video 层 | Render 层负责取视频帧，`StandardGSYVideoPlayer` 新增组合截图 API，用于叠加播放器 UI。 |
+| GLSurfaceView 效果 | Render 层 | GL renderer 负责滤镜、纹理、截图和 release，Demo 退出时恢复原全局 render type。 |
+| 多 URL 清晰度切换 | Video + Manager 层 | `SmartPickVideo` 使用临时 manager 预加载新 URL，seek 同步后提交，失败时回退原播放。 |
+| Exo 自适应清晰度 | Exo Manager 层 | HLS master / DASH MPD 走单个媒体时间线，Media3 TrackSelector 自动选轨，固定清晰度使用 TrackSelectionOverride。 |
+| 完成后保留最后一帧 | Demo Video 层 | `KeepLastFrameVideo` 只作为业务语义验证，不改变基础播放器默认完成态。 |
+| 播放器初始化失败处理 | Manager + Player 层 | `GSYVideoBaseManager` 和各 `IPlayerManager` 将内核创建/初始化异常收敛到错误回调和资源清理。 |
+| Exo cache 与 GIF 清理 | Cache + Utils 层 | `ExoSourceManager` 管理 Exo cache 生命周期，`GifCreateHelper` 负责 GIF 生成状态和临时资源清理。 |
+
+更完整的入口、API、回归清单见 [RECENT_FEATURES.md](RECENT_FEATURES.md)。
+
 ### 自定义流程
 
 #### 1、通过API实现
@@ -69,5 +88,3 @@
 
 
 
-
-
diff --git a/doc/GSYVIDEO_PLAYER_PROJECT_INFO_EN.md b/doc/GSYVIDEO_PLAYER_PROJECT_INFO_EN.md
@@ -9,6 +9,7 @@
 * **Manager core management layer**: GSYVideoManager (GSYVideoBaseManager <- GSYVideoViewBridge).
 * **Video player control layer**: GSYTextureRenderVIew to GSYVideoPlayer five layers.
 * **Render rendering control layer**: TextureView, SurfaceView, GLSurfaceView (GSYRenderView <- IGSYRenderView).
+* **Extension capability layer**: subtitles, preview, screenshots, GL effects, and quality switching are kept in replaceable UI/Manager/Render layers whenever possible, instead of being pushed into the playback core.
 
 **Currently, the entire video layer is the traditional controller layer, and it is also the layer that needs to be inherited for custom implementation most of the time.**
 
@@ -32,6 +33,24 @@
 
 **From this, it can be seen that the project's playback core, manager, and rendering layer can all be customized and replaced.**
 
+### Recent Features By Layer
+
+Recent playback changes map to the existing architecture like this:
+
+| Feature | Layer | Notes |
+| --- | --- | --- |
+| Unified external subtitles | Video/UI layer | `GSYSubtitleController` and `GSYSubtitleView` render SRT/WebVTT by playback position; failures do not affect video playback. |
+| WebVTT seek preview | Demo + preview provider | `PreViewGSYVideoPlayer` consumes `GSYVideoPreviewProvider`; thumbnail files and sprite coordinates come from the app or server side. |
+| Screenshots | Render + Video layer | Render views capture the video frame; `StandardGSYVideoPlayer` adds composed screenshot APIs that include player UI. |
+| GLSurfaceView effects | Render layer | GL renderers handle filters, textures, screenshots, and release; the demo restores the previous global render type on exit. |
+| Multi-URL quality switching | Video + Manager layer | `SmartPickVideo` preloads the target URL with a temporary manager, syncs seek position, commits when ready, and falls back on failure. |
+| Exo adaptive quality | Exo Manager layer | HLS master / DASH MPD use one media timeline; Media3 TrackSelector handles auto track selection, and fixed quality uses TrackSelectionOverride. |
+| Keep last frame | Demo Video layer | `KeepLastFrameVideo` validates the business behavior without changing the base player's default completion state. |
+| Player init failure handling | Manager + Player layer | `GSYVideoBaseManager` and each `IPlayerManager` route core creation/init exceptions into error callbacks and resource cleanup. |
+| Exo cache and GIF cleanup | Cache + Utils layer | `ExoSourceManager` manages the Exo cache lifecycle, while `GifCreateHelper` cleans GIF generation state and temporary resources. |
+
+See [RECENT_FEATURES_EN.md](RECENT_FEATURES_EN.md) for entry points, APIs, and regression checks.
+
 ### Customization Process
 
 #### 1. Implementation through API
diff --git a/doc/RECENT_FEATURES.md b/doc/RECENT_FEATURES.md
@@ -13,6 +13,38 @@
 | GLSurfaceView 效果和生命周期 | `滤镜` | `DetailFilterActivity`、`GSYVideoGLView*Render` | 整理 GL render 生命周期，补充滤镜、纹理、多窗口、遮罩等 Demo 场景。 |
 | 多 URL 清晰度切换稳态优化 | `无缝切换` | `SmartPickVideo` | 保留双 manager 方案，强化切换过程中的位置同步、超时、失败回退和临时 manager 释放。 |
 | Exo 自适应清晰度 | `EXO自适应清晰度` | `ExoAdaptiveTrackActivity`、`GSYExo2MediaPlayer` | 使用单个 HLS master playlist 或 DASH MPD，由 Media3 TrackSelector 在同一时间线内自适应或固定 video track。 |
+| 播放器初始化失败安全处理 | 通用能力 | `GSYVideoBaseManager`、各 `IPlayerManager` | 内核创建或初始化失败时走错误回调和资源清理，避免直接 crash。 |
+| Exo 缓存生命周期和 GIF 清理 | 通用能力 | `ExoSourceManager`、`GifCreateHelper` | 收紧 Exo cache 的打开/释放流程，GIF 生成流程结束或失败时更可靠地清理。 |
+
+## 近期提交覆盖
+
+按近期提交逐条对应如下：
+
+| 提交 | 文档覆盖 |
+| --- | --- |
+| `Add Exo adaptive quality demo and docs` | `README*`、`USE*`、`RECENT_FEATURES*`、`UPDATE_VERSION*`、`ARCHITECTURE.md`、`GSYVIDEO_PLAYER_PROJECT_INFO*` |
+| `Harden smart quality switching` | 多 URL 清晰度切换章节、架构层级表、回归清单 |
+| `Harden GL renderer lifecycle and demo` | GLSurfaceView 效果章节、架构层级表、回归清单 |
+| `Fix screenshot callbacks and composed capture` | 截图能力章节、组合截图 API、架构层级表 |
+| `Add keep last frame demo` | 完成后保留最后一帧章节、入口总览、回归清单 |
+| `feat: add unified subtitle support` | 通用外挂字幕章节、`SUBTITLE_CN.md`、入口总览、回归清单 |
+| `Add WebVTT seek preview support` | WebVTT 进度条预览章节、入口总览、回归清单 |
+| `Handle player init failures gracefully` | 播放器初始化失败安全处理条目、版本说明 |
+| `Improve Exo cache lifecycle and GIF cleanup` | Exo 缓存生命周期和 GIF 清理条目、版本说明 |
+
+## 文档覆盖
+
+近期播放能力相关说明已经分散补充到以下文档：
+
+- `README_CN.md` / `README.md`：首页能力摘要和近期能力入口。
+- `doc/USE.md` / `doc/USE_EN.md`：使用层面的 Demo 入口和核心 API。
+- `doc/UPDATE_VERSION.md` / `doc/UPDATE_VERSION_EN.md`：Unreleased 版本变更摘要。
+- `doc/ARCHITECTURE.md`：播放能力在 UI、Manager、Render、Exo manager 等层级上的设计归属。
+- `doc/GSYVIDEO_PLAYER_PROJECT_INFO.md` / `doc/GSYVIDEO_PLAYER_PROJECT_INFO_EN.md`：项目结构说明里的近期能力层级映射。
+- `doc/SUBTITLE_CN.md`：通用字幕专题说明。
+- `doc/RECENT_FEATURES.md` / `doc/RECENT_FEATURES_EN.md`：近期能力总览、API 和回归清单。
+
+构建、依赖、SO、发布、解码器、FAQ 类文档没有强行加入本次播放能力说明，因为它们的主题不是 Demo 功能入口或播放架构。
 
 ## WebVTT 进度条预览
 
@@ -129,6 +161,18 @@ GSYExoVideoManager.instance().setVideoTrackOverride(groupIndex, trackIndex);
 - 选择固定清晰度时，会使用 `TrackSelectionOverride` 固定到某个 video track。
 - 清除 override 后恢复自适应。
 
+## 播放器初始化失败安全处理
+
+内核初始化相关改动集中在 `GSYVideoBaseManager` 和各内核 `IPlayerManager`。当 IJK、System、Exo、AliPlayer 创建或初始化失败时，流程会尽量走 `onError` 和释放清理，而不是把异常直接抛到业务层导致 crash。
+
+这个能力没有单独 Demo 入口，属于全局稳定性兜底。建议通过非法 URL、缺失解码能力或故意构造异常初始化场景回归，确认播放器进入错误态且应用不崩。
+
+## Exo 缓存生命周期和 GIF 清理
+
+`ExoSourceManager` 收紧了 Exo cache 的生命周期处理，降低 cache 打开、复用和释放过程中的资源残留风险。`GifCreateHelper` 在 GIF 生成结束、失败或取消后会更可靠地推进状态和清理临时资源。
+
+这个能力同样没有单独入口。回归时建议覆盖 Exo cache 播放、退出页面、重新进入播放，以及滤镜 Demo 里的 GIF 生成/失败路径。
+
 ## 回归建议
 
 每次修改这些能力后，至少执行：
@@ -146,3 +190,5 @@ adb install -r app/build/outputs/apk/debug/app-debug.apk
 - `滤镜`：切换滤镜和 GL 场景，确认播放、截图、GIF 不崩。
 - `无缝切换`：切换多个 URL，确认不回 0，失败可回退。
 - `EXO自适应清晰度`：HLS 和 DASH 都能播放，轨道列表能显示，自动/固定清晰度能切换。
+- 播放失败和内核初始化异常：确认进入错误回调，不直接 crash。
+- Exo cache 和 GIF：确认退出、重进、失败路径都能清理资源。
diff --git a/doc/RECENT_FEATURES_EN.md b/doc/RECENT_FEATURES_EN.md
@@ -13,6 +13,38 @@ This document summarizes recent demo and playback changes so maintainers can qui
 | GLSurfaceView effects and lifecycle | `Filter` | `DetailFilterActivity`, `GSYVideoGLView*Render` | Cleans up GL renderer lifecycle and adds filter, texture, multi-window, mask, and blur scenes. |
 | Multi-URL quality switching | `Seamless switch` | `SmartPickVideo` | Keeps the two-manager approach and improves position sync, timeout, fallback, and temporary manager release. |
 | Exo adaptive quality | `EXO adaptive quality` | `ExoAdaptiveTrackActivity`, `GSYExo2MediaPlayer` | Uses one HLS master playlist or DASH MPD and lets Media3 TrackSelector switch video tracks in one media timeline. |
+| Graceful player init failure handling | Global capability | `GSYVideoBaseManager`, each `IPlayerManager` | Routes player creation/init failures through error callbacks and cleanup instead of crashing directly. |
+| Exo cache lifecycle and GIF cleanup | Global capability | `ExoSourceManager`, `GifCreateHelper` | Tightens Exo cache open/release behavior and cleans GIF generation state more reliably. |
+
+## Recent Commit Coverage
+
+Recent commits map to the docs like this:
+
+| Commit | Documentation coverage |
+| --- | --- |
+| `Add Exo adaptive quality demo and docs` | `README*`, `USE*`, `RECENT_FEATURES*`, `UPDATE_VERSION*`, `ARCHITECTURE.md`, `GSYVIDEO_PLAYER_PROJECT_INFO*` |
+| `Harden smart quality switching` | Multi-URL quality switching section, architecture layer table, regression checklist |
+| `Harden GL renderer lifecycle and demo` | GLSurfaceView effects section, architecture layer table, regression checklist |
+| `Fix screenshot callbacks and composed capture` | Screenshot section, composed screenshot APIs, architecture layer table |
+| `Add keep last frame demo` | Keep-last-frame section, entry table, regression checklist |
+| `feat: add unified subtitle support` | Unified subtitles section, `SUBTITLE_CN.md`, entry table, regression checklist |
+| `Add WebVTT seek preview support` | WebVTT seek preview section, entry table, regression checklist |
+| `Handle player init failures gracefully` | Graceful player init failure handling entry, changelog |
+| `Improve Exo cache lifecycle and GIF cleanup` | Exo cache lifecycle and GIF cleanup entry, changelog |
+
+## Documentation Coverage
+
+Recent playback feature notes are covered in:
+
+- `README_CN.md` / `README.md`: top-level feature summary and recent feature links.
+- `doc/USE.md` / `doc/USE_EN.md`: demo entry points and core APIs.
+- `doc/UPDATE_VERSION.md` / `doc/UPDATE_VERSION_EN.md`: Unreleased changelog summary.
+- `doc/ARCHITECTURE.md`: layer ownership across UI, Manager, Render, and Exo manager.
+- `doc/GSYVIDEO_PLAYER_PROJECT_INFO.md` / `doc/GSYVIDEO_PLAYER_PROJECT_INFO_EN.md`: recent feature mapping in the project structure guide.
+- `doc/SUBTITLE_CN.md`: unified subtitle guide.
+- `doc/RECENT_FEATURES.md` / `doc/RECENT_FEATURES_EN.md`: full recent feature overview, APIs, and regression checklist.
+
+Build, dependency, SO, publishing, decoder, and FAQ documents are not forced to repeat these playback feature notes because their scope is not demo entry points or playback architecture.
 
 ## WebVTT Seek Preview
 
@@ -129,6 +161,18 @@ Notes:
 - Fixed quality uses `TrackSelectionOverride` for a specific video track.
 - Clearing the override restores adaptive playback.
 
+## Graceful Player Init Failures
+
+Player initialization hardening is mainly in `GSYVideoBaseManager` and each core `IPlayerManager`. When IJK, System, Exo, or AliPlayer creation/init fails, the flow tries to report `onError` and release resources instead of throwing directly into the app.
+
+There is no standalone demo entry for this global safety behavior. Regression should cover invalid URLs, missing codec capability, or intentionally failed init paths and verify the app enters the error state without crashing.
+
+## Exo Cache Lifecycle And GIF Cleanup
+
+`ExoSourceManager` now handles Exo cache open/reuse/release more carefully to reduce stale resource risks. `GifCreateHelper` also cleans temporary state more reliably after GIF creation finishes, fails, or is cancelled.
+
+There is no standalone entry for this capability. Regression should cover Exo cache playback, leaving and re-entering a page, and GIF creation/failure paths in the filter demo.
+
 ## Regression Checklist
 
 Run at least:
@@ -146,3 +190,5 @@ Manual checks:
 - `Filter`: switch filters and GL scenes; playback, screenshots, and GIF creation should not crash.
 - `Seamless switch`: switch multiple URLs and confirm it does not jump back to 0.
 - `EXO adaptive quality`: HLS and DASH play, tracks are listed, and auto/fixed quality switching works.
+- Playback failure and init exceptions: confirm they route to error callbacks and do not crash the app.
+- Exo cache and GIF: confirm exit/re-enter/failure paths clean resources.
diff --git a/doc/UPDATE_VERSION.md b/doc/UPDATE_VERSION.md
@@ -12,6 +12,8 @@
 - GL 渲染 Demo 增加多种效果场景，强化 GL renderer 生命周期、截图和释放安全性。
 - 多 URL 清晰度切换优化位置同步、超时、失败回退和临时 manager 释放，降低切换回 0 的风险。
 - 新增完成后保留最后一帧 Demo，方便验证自然播放完成后的封面和 Surface 保留策略。
+- 播放器内核创建和初始化失败时走错误回调与资源清理，降低直接 crash 风险。
+- 优化 Exo cache 生命周期处理和 GIF 生成结束/失败后的清理流程。
 
 ### v12.1.0 (2026-04-01)
 
@@ -1598,4 +1600,3 @@ holder.gsyVideoPlayer.setPlayPosition(position);
 ### 1.1.1
 * 增加了ListVideoUtil全屏是否显示横屏，全屏是否自动旋转。
 * 增加了ListVideoUtils隐藏状态栏和title的接口。
-
diff --git a/doc/UPDATE_VERSION_EN.md b/doc/UPDATE_VERSION_EN.md
@@ -12,6 +12,8 @@
 - GL demos include more effect scenes and safer renderer lifecycle, screenshot, and release behavior.
 - Multi-URL quality switching improves position sync, timeout handling, failure fallback, and temporary manager release to reduce jump-back-to-0 risk.
 - Add a keep-last-frame demo for validating cover and Surface retention behavior after natural completion.
+- Player core creation and initialization failures now route through error callbacks and cleanup to reduce direct crash risk.
+- Improve Exo cache lifecycle handling and cleanup after GIF creation finishes or fails.
 
 ### v12.1.0 (2026-04-01)
 
