# GSY Video Cache

Covers caching, cache cleanup, and offline download for GSYVideoPlayer on Android.

- Repository: https://github.com/CarGuo/GSYVideoPlayer (21524 stars)
- Category: Mobile
- License: Apache-2.0
- Last updated: 2026-10-10
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add CarGuo/GSYVideoPlayer --skill gsy-cache-and-download -g -a claude-code -y`
Codex: `npx skills add CarGuo/GSYVideoPlayer --skill gsy-cache-and-download -g -a codex -y`
Cursor: `npx skills add CarGuo/GSYVideoPlayer --skill gsy-cache-and-download -g -a cursor -y`
Gemini CLI: `npx skills add CarGuo/GSYVideoPlayer --skill gsy-cache-and-download -g -a gemini-cli -y`

## Description

边播边缓（AndroidVideoCache 代理）、自定义缓存目录、清理缓存、离线下载至完整文件。

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# gsy-cache-and-download

## 概念

- **缓存**（cache）：`ProxyCacheManager` 内部起本地 HTTP 代理，拦截 `player` 的请求，把响应流一边喂给 player 一边写到本地；文件名是 URL MD5。
- **下载**（download）：与缓存共享目录，但一定要走"从头到尾"完整播完才能保证文件可复用为独立 mp4；提前 seek 会造成 range 分片，回放时代理会重新下载缺失段。

## 开启缓存

方式 1：`setUp(url, true, title)` 第二参数 `cacheWithPlay=true`。

方式 2：`GSYVideoOptionBuilder`：
- `setCacheWithPlay(true)`
- `setCachePath(File)`（可选）

## 自定义缓存目录

```java
File dir = new File(getExternalFilesDir(null), "videoCache");
builder.setCachePath(dir);
```

若使用不同 `CacheManager`（例如 Exo），传给 `CacheFactory.setCacheManager(...)` 前记得也走 `setCachePath` 或自定义 `ICacheManager` 实现。

## `ICacheManager` API

见 [ICacheManager](../../gsyVideoPlayer-base/src/main/java/com/shuyu/gsyvideoplayer/cache/ICacheManager.java)。核心方法：

| 方法 | 说明 |
|---|---|
| `doCacheLogic(Context, IMediaPlayer, String url, Map<String,String> headers, File cachePath)` | 播放前介入，把 url 换为代理 url |
| `clearCache(Context, File cachePath, String url)` | 单条清除；`url = null` 清空整目录 |
| `hadCached()` | 当前播放是否已"命中"缓存（100% 完成） |
| `setCacheAvailableListener(CacheAvailableListener)` | 缓存进度回调 |
| `release()` | 释放代理 |

## `ProxyCacheManager` 关键静态方法

在 [ProxyCacheManager](../../gsyVideoPlayer-java/src/main/java/com/shuyu/gsyvideoplayer/cache/ProxyCacheManager.java) 里：

- `clearAllCache(Context, File)`, , 清空整个缓存目录。
- 内部 `HttpProxyCacheServer` 单例 lazy 初始化，第一次 `doCacheLogic` 时才起服务；Application 就绪即可。

## `ProxyCacheUserAgentHeadersInjector`

自定义 UA / Cookie / Referer 注入到代理层：见 [ProxyCacheUserAgentHeadersInjector](../../gsyVideoPlayer-java/src/main/java/com/shuyu/gsyvideoplayer/cache/ProxyCacheUserAgentHeadersInjector.java)。挂到 `HttpProxyCacheServer.Builder.headerInjector()` 上，或直接用 `Map` 传给 `setUp`。

## 离线下载

三步流程：

1. 用 `HttpProxyCacheServer` 单独跑一次预下载（不 attach 到 Player），或直接开一条播放并 `setStartAfterPrepared(false)` 静默走全长；
2. 事件 `VideoAllCallBack#onAutoComplete` 触发 → 缓存文件已完整；
3. 用 [FileUtils](../../gsyVideoPlayer-java/src/main/java/com/shuyu/gsyvideoplayer/utils/FileUtils.java) 拷贝 / 重命名到业务目录。

The rest: https://github.com/CarGuo/GSYVideoPlayer/blob/HEAD/skills/06-gsy-cache-and-download/SKILL.md