基础播放器构建：SimpleExoPlayer 创建、MediaItem 封装、PlayerView 在 Compose 中嵌入、SurfaceProvider 绑定

本章将完整搭建一个基于 ExoPlayer 的最小播放器内核，涵盖从 player 实例创建、媒体条目封装、到 Compose 视图集成与 Surface 绑定四个核心步骤。这是后续所有高级功能（缓存、DRM、字幕、自定义控制器）的基石，必须确保每一步的生命周期与渲染链路正确闭合。

2.1 核心职责与数据流

一个完整的基础播放器由四个角色协作完成：

• SimpleExoPlayer：播放引擎核心，负责解码、渲染、状态管理。
• MediaItem：媒体资源描述对象，封装 URI、DRM 方案、字幕轨道等元数据。
• PlayerView（Compose 侧）：通过 AndroidView 封装原生 SurfaceView/TextureView，为 player 提供显示画布。
• SurfaceProvider：连接 player 输出端与视图 Surface 的生命周期安全桥接。

下图展示了四者之间的依赖与数据流向：

2.2 SimpleExoPlayer 创建

ExoPlayer 推荐通过 ExoPlayer.Builder 链式构建，并绑定应用生命周期。核心点：

• 使用 android.content.Context 创建 builder。
• 可通过 .setRenderersFactory() 自定义解码器工厂。
• 必须通过 .build() 获取实例，并在 Activity/Fragment 的 onStop 中 release()。

// 创建包含默认渲染器的播放器
SimpleExoPlayer player = new ExoPlayer.Builder(context)
        .setRenderersFactory(new DefaultRenderersFactory(context))
        .build();

// 生命周期管理示例（在 ViewModel 或 CompositionLocal 中维护）
override fun onStop() {
    super.onStop()
    player.release() // 释放解码器与 Surface
}

2.3 MediaItem 封装

MediaItem 是 ExoPlayer 3.x 引入的统一资源描述对象，替代旧版 MediaSource 链式构建。封装时需明确：

MediaItem mediaItem = new MediaItem.Builder()
        .setUri(Uri.parse("https://storage.googleapis.com/exoplayer-test-media-1/mkv/android-screens-lavf-56.36.100-aac-avc-main-1280x720.mkv"))
        .setMediaMetadata(
            new MediaMetadata.Builder()
                .setTitle("ExoPlayer 测试视频")
                .build()
        )
        .build();

2.4 PlayerView 在 Compose 中嵌入

Compose 中没有对应的 ExoPlayer 原生视图，必须通过 AndroidView 桥接 StyledPlayerView 或 PlayerView（来自 com.google.android.exoplayer2.ui 包）。核心步骤：

1. 在 AndroidView 的 factory 中创建 StyledPlayerView(context)。
2. 在 update 或 LaunchedEffect 中绑定 player 实例。
3. 设置 useController 控制是否显示内置控制条。

@Composable
fun ExoPlayerView(
    player: SimpleExoPlayer,
    modifier: Modifier = Modifier
) {
    // 使用 StyledPlayerView 以获得默认控制条
    AndroidView(
        modifier = modifier,
        factory = { context ->
            StyledPlayerView(context).apply {
                this.player = player
                useController = true        // 显示播放/暂停/进度条
                keepScreenOn = true
            }
        },
        update = { view ->
            view.player = player             // 确保重组时重新绑定
        }
    )
}

2.5 SurfaceProvider 绑定

当需要自定义渲染 Surface（例如使用 TextureView 配合 Camera/GL 叠加）时，必须手动提供 SurfaceProvider。ExoPlayer 从 2.13 开始使用 setVideoSurfaceProvider() 替代旧的 setVideoSurface()，以支持异步 Surface 生命周期。

// 自定义 TextureView 作为 SurfaceProvider
val textureView = TextureView(context)
val surfaceProvider = object : SurfaceProvider {
    override fun onSurfaceReady(surface: Surface) {
        player.setVideoSurface(surface, true) // true 表示释放旧 surface
    }
    override fun onSurfaceDestroyed() {
        player.setVideoSurface(null, false)
    }
}
textureView.surfaceTextureListener = object : TextureView.SurfaceTextureListener {
    override fun onSurfaceTextureAvailable(surface: SurfaceTexture, width: Int, height: Int) {
        surfaceProvider.onSurfaceReady(Surface(surface))
    }
    override fun onSurfaceTextureDestroyed(surface: SurfaceTexture): Boolean {
        surfaceProvider.onSurfaceDestroyed()
        return true
    }
    // 其他回调...
}

在 Compose 中如果直接使用 StyledPlayerView，内部已自动管理 SurfaceProvider，无需手动处理。只有在自定义渲染视图时才需要介入。

2.6 调试要点与常见错误

2.7 完整集成流程总结

1. 创建 SimpleExoPlayer 实例（建议使用 ExoPlayer.Builder 并注入 Application Context）。
2. 构造 MediaItem，设置 URI 及可选元数据。
3. 调用 player.setMediaItem(mediaItem) 并 player.prepare()。
4. 在 Compose 中通过 AndroidView 放置 StyledPlayerView，绑定 player。
5. 如需自定义 Surface，手动实现 SurfaceProvider 并调用 player.setVideoSurfaceProvider()。
6. 在 DisposableEffect 或 onStop 中 player.release()。