gsy-subtitle-and-preview

外挂/内嵌字幕(SRT/VTT)、Exo 内嵌字幕轨、Seek 悬浮预览缩略图(VTT thumbnails)。

SKILL.md

GitHub

gsy-subtitle-and-preview

字幕 API

顶层控制器:GSYSubtitleController。视图:GSYSubtitleView。

方法 说明
new GSYSubtitleController(context, subtitleView) 绑定 UI
setSources(List<GSYSubtitleSource>) 一次注入多轨字幕
setSource(GSYSubtitleSource) 只有一条
getSources() 只读 List
selectSubtitle(String id) 按 id 切换字幕,"" 或 null 关闭
setStyle(GSYSubtitleStyle) 字体/描边/背景/颜色
setOffsetMs(long) 音画/字幕 offset
setEnabled(boolean) 开关
updatePosition(long positionMs) 由 player 进度驱动
release() 释放

GSYSubtitleSource 字段

见 GSYSubtitleSource:

字段 说明
id 唯一 id
label 显示名
language ISO code
mime 见 GSYSubtitleMime:text/vtt、application/x-subrip(srt)、text/plain
uri http 或 file uri
embedded 是否内嵌轨(Exo 场景)

内置解析器

Exo 内嵌字幕

gsyvideoplayer-exo_player2 的 Manager 会把 Exo 的 subtitle track 通过 GSYSubtitleController 上抛。Demo:GSYExoSubTitlePlayer + GSYExoSubTitleVideoManager。

Seek 预览 API

顶层:GSYVideoPreviewProvider 与列表实现 GSYVideoPreviewListProvider。

方法 说明
GSYVideoPreviewProvider#getPreviewFrame(long positionMs) 返 GSYVideoPreviewFrame,含 image url + crop 坐标
GSYVideoPreviewListProvider(List<GSYVideoPreviewFrame>) 直接注入帧列表(自己解析或用 VTT)
GSYVideoPreviewVttParser#parse(String vttContent, String baseUrl) 解析 WebVTT thumbnails(雪碧图 + 时间段)
GSYVideoPreviewVttParser#parseFrames(String vttContent, String baseUrl) 只要帧列表

GSYVideoPreviewFrame 字段

见 GSYVideoPreviewFrame:startTimeMs、endTimeMs、imageUrl、cropX/Y/Width/Height、hasCrop()。

关键调用序(VTT 预览 + SRT 字幕)

  1. 加载 subtitle:controller.setSource(new GSYSubtitleSource("cn", "中文", "zh", GSYSubtitleMime.SRT, uri, false));
  2. 播放进度回调(GSYVideoProgressListener)中 controller.updatePosition(current);
  3. 预览:GSYVideoPreviewVttParser.parse(vttText, base) → 得到 Provider → 注入到 PreViewGSYVideoPlayer#setPreviewProvider(provider);
  4. seekbar 拖动时 SDK 会自动调 provider.getPreviewFrame(target) 并做 crop。

Demo 对照

常见坑

  • SRT 时间轴带 BOM 或换行不规范会直接被 parser 丢弃;先用 UTF-8 无 BOM 保存。
  • VTT 缩略图 URL 相对路径必须传 baseUrl 才能拼绝对路径。
  • updatePosition 必须在 UI 线程或至少与 subtitleView 同线程;GSYSubtitleController 内部无线程切换。