gsy-compose-integration

在 Jetpack Compose 中通过 AndroidView 桥接 GSYVideoPlayer,覆盖列表、竖直短视频、生命周期管控。

SKILL.md

GitHub

gsy-compose-integration

模块

gsyVideoPlayer-compose 是 Compose 桥接层,两种模式并存:

模式 入口 说明
Wrapper(推荐上手) GSYVideoPlayerView / GSYAnyVideoPlayerView AndroidView 直接承载 StandardGSYVideoPlayer / 任意 NormalGSYVideoPlayer 子类,保留全部内置能力
Native(纯 Compose 控件) rememberGSYPlayerController + GSYPlayerSurface + GSYDefaultControls 只承载画面,控制层完全用 Compose 自绘
通用工具 LifecycleBridge LifecycleEffect { event -> ... } 用于订阅宿主 Lifecycle

Wrapper API:GSYVideoPlayerView

见 GSYVideoPlayerView#L28-L36:

参数 类型 说明
modifier Modifier 通常 Modifier.fillMaxWidth().aspectRatio(16f/9)
setUp (StandardGSYVideoPlayer) -> Unit 等价 GSYVideoOptionBuilder.build(player)
setUpKey Any? = null 非空时其变化会重新调用 setUp(典型:传 url)
autoReleaseOnDispose Boolean = true 离屏自动 player.release()
autoPauseResume Boolean = true 自动桥 Lifecycle:ON_PAUSE→GSYVideoManager.onPause()、ON_RESUME→onResume()
onPlayerCreated (StandardGSYVideoPlayer) -> Unit 拿到 player 实例的回调

Wrapper API:GSYAnyVideoPlayerView<T : NormalGSYVideoPlayer>

见 GSYAnyVideoPlayerView#L26-L35。相比 GSYVideoPlayerView 多出:

参数 类型 说明
factory (Context) -> T 传自定义子类(如 ListGSYVideoPlayer、SampleControlVideo、DanmakuVideoPlayer)

Native API:rememberGSYPlayerController

见 rememberGSYPlayerController#L26-L32:

参数 默认 说明
url null 非空时内部 LaunchedEffect 触发 controller.setUp(...)
cacheWithPlay false 边播边缓
title "" 标题(透传给底层 player)
autoPlay false attach 完成后自动 startPlayLogic
autoPauseResume true 自动订阅 Lifecycle(同 wrapper)

返回 GSYPlayerController,可以再调 .play() / .pause() / .seekTo(ms) / .setSpeed(...) / .changeTextureViewShowType() / .setUp(url, cache, title, autoPlay) / .dispose();状态订阅走 GSYPlayerState(StateFlow<GSYPlayerState>),事件走 GSYPlayerEvent。

最小可运行示例

Wrapper 模式:

GSYVideoPlayerView(
    modifier = Modifier.fillMaxWidth().aspectRatio(16f/9),
    setUpKey = url,
    setUp = { player ->
        GSYVideoOptionBuilder()
            .setUrl(url)
            .setCacheWithPlay(true)
            .setVideoTitle("demo")
            .setIsTouchWiget(true)
            .setAutoFullWithSize(true)
            .build(player)
        player.startPlayLogic()
    }
)

Native 模式:

val controller = rememberGSYPlayerController(url = url, autoPlay = true)
Box(Modifier.fillMaxWidth().aspectRatio(16f/9)) {
    GSYPlayerSurface(controller = controller, modifier = Modifier.matchParentSize())
    GSYDefaultControls(controller = controller)
}

生命周期最佳实践

val lifecycle = LocalLifecycleOwner.current.lifecycle
DisposableEffect(lifecycle) {
    val obs = LifecycleEventObserver { _, e ->
        when (e) {
            Lifecycle.Event.ON_PAUSE  -> state.pause()
            Lifecycle.Event.ON_RESUME -> state.resumeIfNeeded()
            Lifecycle.Event.ON_DESTROY-> state.release()
            else -> Unit
        }
    }
    lifecycle.addObserver(obs)
    onDispose { lifecycle.removeObserver(obs) }
}

Demo 对照

场景 Activity
原生桥接示例 DetailNativeActivity / BasicWrapperActivity / FullFeatureNativeActivity
广告 + 主片(列表内) AdInListComposeActivity
列表 + 全屏 ListWithFullscreenActivity / ListPlayNativeActivity / AutoPlayListActivity
抖音式竖屏 VerticalShortVideoComposeActivity
滤镜 DetailFilterComposeActivity
无缝切源 / Exo 切源 SwitchSeamlessComposeActivity / ExoSwitchSourceComposeActivity / SwitchUrlActivity
字幕 SubtitleComposeActivity
弹幕 DanmakuComposeActivity
缓存 / 下载 CacheDownloadComposeActivity
硬解 / MediaCodec MediaCodecComposeActivity
悬浮小窗 FloatingWindowComposeActivity
音频独立 AudioOnlyComposeActivity
多类型混排 MoreTypeComposeActivity
多窗口并行 MultiWindowActivity / MultiWindowParallelComposeActivity
本地文件 LocalFileComposeActivity
自定义主题 CustomControlsThemeComposeActivity
WebView 详情 WebDetailComposeActivity

样例 hosts 全在 compose/host/。

v14.0.0 状态与接入

外部坐标为 io.github.carguo:gsyvideoplayer-compose:14.0.0(GitHub Packages 使用 com.shuyu)。IJK 使用方还需选择 ex_so 或独立 ABI 原生模块;完整组合见 DEPENDENCIES.md。

detachHost 只解绑 View 侧回调/tick,dispose 统一释放保留的 host;snapshot.bufferPercent 合并内核轮询与回调值。controller.changeTextureViewShowType() 在主线程更新当前内嵌/全屏比例。Compose Demo 共 25 项,新增折叠屏 BOOK/TABLETOP。详见 COMPOSE_USE.md。

常见坑

  • Compose 频繁重组 → AndroidView 的 factory 只跑一次;不要把 setUp 放在 factory 里,放到 update block,并用 remember(url) 做去重。
  • AndroidView 内部布局要指定固定高度或 aspectRatio,否则 SurfaceView 会 0 高度导致黑屏。
  • 竖直短视频 + Pager:切页时用 pagerState.currentPage 触发 state.play(url) / previousState.pause();释放放在 DisposableEffect(pagerState) 里。
  • 与 Compose 主题深浅色切换:GSYVideoPlayerCompose 是原生 View 层,配色需要单独 setBottomProgressBarDrawable 等 API。