01 Gsy Quickstart

---
name: gsy-quickstart
description: 从零把 GSYVideoPlayer 塞进一个 Activity 或 Fragment，跑通「setUp → startPlayLogic → release」最小闭环。
when_to_use: 用户第一次在项目里集成 GSYVideoPlayer；只要能播一个 mp4 就行；或需要确认基础生命周期是否接对。
inputs:
  - name: play_url
    description: 视频地址（http/https/file/asset/rtmp/rtsp）
    required: true
  - name: container
    description: 承载 View 的容器（一般是 FrameLayout）
    required: true
outputs:
  - StandardGSYVideoPlayer 实例已 setUp 并可控（play/pause/release）
references:
  - file: gsyVideoPlayer-java/src/main/java/com/shuyu/gsyvideoplayer/video/StandardGSYVideoPlayer.java
  - file: gsyVideoPlayer-java/src/main/java/com/shuyu/gsyvideoplayer/video/base/GSYVideoView.java
  - file: gsyVideoPlayer-java/src/main/java/com/shuyu/gsyvideoplayer/GSYVideoManager.java
  - file: app/src/main/java/com/example/gsyvideoplayer/PlayActivity.java
---

# gsy-quickstart

## 依赖

- 推荐整包：`io.github.carguo:gsyvideoplayer:14.0.0`（已含 Java、Exo2、三 ABI ex_so）。
- 分模块主库：`io.github.carguo:gsyvideoplayer-java:14.0.0`。
- 分模块 IJK so：选 `io.github.carguo:gsyvideoplayer-ex_so:14.0.0`，或所需独立 artifact `gsyvideoplayer-arm64` / `gsyvideoplayer-armv7a` / `gsyvideoplayer-x64`，不重复引入同 ABI 两套库。
- 默认 ABI 为 `arm64-v8a` / `armeabi-v7a` / `x86_64`（FFmpeg n5.1.10 / OpenSSL 3.5.9）；旧 armv5/x86 未升级，仅旧架构项目显式使用。
- 权限：`INTERNET`、`WAKE_LOCK`、`ACCESS_NETWORK_STATE`（AndroidManifest）

明细见 [doc/DEPENDENCIES.md](../../doc/DEPENDENCIES.md)。

## 核心 API

| 类 / 方法 | 位置 | 作用 |
|---|---|---|
| `StandardGSYVideoPlayer(Context)` | [StandardGSYVideoPlayer](../../gsyVideoPlayer-java/src/main/java/com/shuyu/gsyvideoplayer/video/StandardGSYVideoPlayer.java) | 主用 UI 组件，默认布局在 `R.layout.video_layout_standard` |
| `setUp(url, cacheWithPlay, title)` | [GSYVideoView#L438-L451](../../gsyVideoPlayer-java/src/main/java/com/shuyu/gsyvideoplayer/video/base/GSYVideoView.java) | 最短形式的地址绑定 |
| `setUp(url, cacheWithPlay, cachePath, title)` | [GSYVideoView#L477-L488](../../gsyVideoPlayer-java/src/main/java/com/shuyu/gsyvideoplayer/video/base/GSYVideoView.java) | 支持自定义缓存目录 |
| `setUp(url, cacheWithPlay, cachePath, headers, title)` | [GSYVideoView#L453-L475](../../gsyVideoPlayer-java/src/main/java/com/shuyu/gsyvideoplayer/video/base/GSYVideoView.java) | 附带 HTTP header |
| `startPlayLogic()` | `StandardGSYVideoPlayer`（继承自 `GSYVideoControlView`） | 触发 prepare→start 全流程 |
| `getCurrentPlayer()` | `GSYBaseVideoPlayer` | 获取"当前活跃 player"（可能是全屏克隆体） |
| `onVideoPause()` / `onVideoResume()` / `onVideoResume(boolean seek)` | [GSYVideoView#L518-L577](../../gsyVideoPlayer-java/src/main/java/com/shuyu/gsyvideoplayer/video/base/GSYVideoView.java) | 对应 Activity `onPause / onResume`；直播场景传 `seek=false` |
| `release()` | [GSYVideoView#L818](../../gsyVideoPlayer-java/src/main/java/com/shuyu/gsyvideoplayer/video/base/GSYVideoView.java) | 释放当前 Player 与 Surface |
| `GSYVideoManager.releaseAllVideos()` | [GSYVideoManager#L99-L104](../../gsyVideoPlayer-java/src/main/java/com/shuyu/gsyvideoplayer/GSYVideoManager.java) | 全局收尾（切页面时兜底） |
| `GSYVideoManager.onPause() / onResume()` | [GSYVideoManager#L110-L135](../../gsyVideoPlayer-java/src/main/java/com/shuyu/gsyvideoplayer/GSYVideoManager.java) | 全局暂停/恢复所有 GSY player |

## 参数表：`setUp(...)`

| 参数 | 类型 | 说明 |
|---|---|---|
| `url` | `String` | 支持 http/https/file/asset/rtmp/rtsp/自定义 scheme；`ProxyCacheManager` 会自动拦截可缓存的普通 http |
| `cacheWithPlay` | `boolean` | true → 边播边缓；对直播 / m3u8 / DRM 建议 false |
| `cachePath` | `File?` | 自定义缓存目录，默认 `context.cacheDir/videoCache` |
| `mapHeadData` | `Map<String,String>?` | HTTP 请求头（Referer、Cookie、Auth 等） |
| `title` | `String` | 顶部标题栏文案，会显示在 `R.id.title` |

返回值：`boolean`，false 表示 URL 为空或与当前 tag 相同（防重复 setup）。

## 最小调用序（Activity 生命周期）

1. `onCreate` → `player.setUp(...)` → 可选 `player.setThumb...`、`setPlayTag()` → `player.startPlayLogic()`
2. `onPause` → `player.getCurrentPlayer().onVideoPause()`
3. `onResume` → `player.getCurrentPlayer().onVideoResume()`（直播传 `false`）
4. `onBackPressed` → 若在全屏：`GSYVideoManager.backFromWindowFull(this)` 返回 true 就吞掉事件
5. `onDestroy` → `player.getCurrentPlayer().release()` + `GSYVideoManager.releaseAllVideos()`

## Demo 对照

- 最短一屏：[PlayActivity](../../app/src/main/java/com/example/gsyvideoplayer/PlayActivity.java)
- Fragment：[VideoFragment](../../app/src/main/java/com/example/gsyvideoplayer/fragment/VideoFragment.java) + [FragmentVideoActivity](../../app/src/main/java/com/example/gsyvideoplayer/FragmentVideoActivity.java)
- 空控件模式（自绘 UI）：[PlayEmptyControlActivity](../../app/src/main/java/com/example/gsyvideoplayer/PlayEmptyControlActivity.java) + [EmptyControlVideo](../../app/src/main/java/com/example/gsyvideoplayer/video/EmptyControlVideo.java)

## 常见坑

- 忘记 `release()` → dex 泄漏 + surface 崩溃：一定在 `onDestroy` 兜底。
- 不覆盖 `getCurrentPlayer()` 直接调 `player.onVideoPause()`：全屏切回后指令发到"影子"实例，导致状态错乱。
- `setUp` 传空 title 走 `null`，会隐藏顶部栏（`View.GONE`），不会崩。