1. ExoPlayer 扩展架构总览：播放器组件树、自定义扩展入口、Module 与 Player.Listener

ExoPlayer 是 Google 官方推荐的 Android 媒体播放库，其核心设计理念是“组件化”与“可扩展”。理解其组件树、扩展入口、Module 机制以及监听器接口，是进行任何高级自定义或边界扩展的前提。本章从架构总览出发，逐一拆解各层次的职责与交互方式，为后续实战章节打下理论基础。

1.1 播放器组件树

ExoPlayer 内部采用分层架构，从上至下依次为：播放器层（ExoPlayer / SimpleExoPlayer）、媒体管道层（MediaSource、Renderers、TrackSelector、LoadControl）以及底层数据源层（DataSource、MediaSource 内部实现）。一个典型的播放器实例在初始化后会创建如下组件树（概念结构）：

核心组件及职责
组件 职责 备注
ExoPlayer / SimpleExoPlayer 对外暴露播放控制接口（play/pause/seek），内部管理媒体管道生命周期 应用直接使用的入口
MediaSource 负责媒体数据的分片、拼接、渲染策略（如 ProgressiveMediaSource、DashMediaSource） 可嵌套（ConcatenatingMediaSource）
Renderer 解码并渲染音视频帧，常见实现：MediaCodecVideoRenderer、MediaCodecAudioRenderer 可自定义
TrackSelector 选择音频/视频/字幕轨道，支持自适应码率 默认 DefaultTrackSelector
LoadControl 控制缓冲策略（缓冲大小、是否开始播放） 默认 DefaultLoadControl
DataSource.Factory 创建数据源实例（FileDataSource、HttpDataSource、CacheDataSource） 每个 MediaSource 依赖一个 Factory

这些组件通过 ExoPlayer 内部的 Renderer[] 数组、MediaSourceList 等数据结构串联在一起。下图展示了播放器启动后的组件树关系：

ExoPlayer 组件树结构 SimpleExoPlayer MediaSource Renderer[] TrackSelector ProgressiveMediaSource DashMediaSource VideoRenderer AudioRenderer DefaultTrackSelector DataSource.Factory CacheDataSource 说明： 箭头表示组合/依赖关系。MediaSource 可嵌套，Renderer 可通过自定义扩展替换， TrackSelector 和 LoadControl 同样支持自定义子类。

1.2 自定义扩展入口

ExoPlayer 提供多个清晰的自定义点，开发者可通过继承或实现接口来扩展功能，无需修改核心库。主要入口包括：

  • 自定义 Renderer：继承 BaseRenderer 并实现 render、isReady 等方法，可用于实现自定义解码或后处理特效。
  • 自定义 DataSource：实现 DataSource 接口（或继承 BaseDataSource），可接入私有缓存协议、加密流等。
  • 自定义 MediaSource：继承 CompositeMediaSource 或实现 MediaSource 接口，用于组合分片、广告插入等场景。
  • 自定义 TrackSelector：继承 MappingTrackSelector 或 DefaultTrackSelector 并重写选择逻辑。
  • 自定义 LoadControl：实现 LoadControl 接口，控制缓冲水位线和回退策略。

这些扩展点均通过构造器或 Builder 注入到 ExoPlayer 实例中。例如注册自定义 Renderer：

val renderersFactory = RenderersFactory { handler, videoListener, audioListener, textOutput, metadataOutput, drmSessionManager ->
    arrayOf(
        MyCustomVideoRenderer(handler, videoListener),
        MediaCodecAudioRenderer(handler, audioListener, AudioCapabilities.DEFAULT)
    )
}

val player = ExoPlayer.Builder(context)
    .setRenderersFactory(renderersFactory)
    .build()

1.3 Module 机制

从 ExoPlayer 2.12 开始，官方引入了 Module 机制，用于将可复用组件打包为独立模块，通过 Module 接口统一注册。每个 Module 可提供自定义 Renderer、DataSource、TrackSelector 等，并自动参与播放器的构建流程。

Module 接口定义 
interface Module {
    fun getComponent(context: Context, builder: ExoPlayer.Builder)
}

使用方式：

val player = ExoPlayer.Builder(context)
    .setModules(listOf(
        MyCacheModule(),
        MyAdsModule()
    ))
    .build()

Module 内部通过 builder 调用 setRenderersFactory、setDataSourceFactory 等 API 注入自定义组件。这种机制使得第三方库（如 IMA 广告、DRM）可以零配置集成。

1.4 Player.Listener 接口

Player.Listener 是 ExoPlayer 状态回调的核心接口，应用层通过它监听播放状态变化、错误、缓冲、轨道切换等事件。自 ExoPlayer 2.15 起，该接口合并了旧版的多接口（Player.EventListener、VideoListener、AudioListener 等），统一为一个接口。

关键回调方法：

回调方法 触发时机 典型用途
onPlaybackStateChanged(state) 播放状态改变（准备、缓冲、播放、结束） 更新 UI 控制条
onPlayerError(error) 播放异常（IO、解码、格式错误） 错误日志、重试策略
onIsPlayingChanged(isPlaying) 播放/暂停状态变化 更新播放按钮图标
onTracksChanged(trackGroups, trackSelections) 轨道切换或选择变化 获取当前码率
onMediaItemTransition(mediaItem, reason) 媒体项切换（列表播放） 更新封面、标题

注册监听器：

player.addListener(object : Player.Listener {
    override fun onPlaybackStateChanged(playbackState: Int) {
        when (playbackState) {
            Player.STATE_BUFFERING -> showBuffering()
            Player.STATE_READY -> hideBuffering()
            Player.STATE_ENDED -> showEnded()
        }
    }

    override fun onPlayerError(error: PlaybackException) {
        Log.e("TAG", "Playback error: ${error.message}")
    }
})
注意： 从 ExoPlayer 2.19 起，Player.Listener 中新增了 onEvents(Player, Events) 回调，允许一次性处理多个事件，提升性能。若只需监听特定事件，建议用 Listener 的默认实现（Kotlin 中可用 object : Player.Listener {} 选择性重写）。

1.5 调试与常见错误

在日常集成中，开发者易忽略以下问题：

  • 未设置正确的 Looper：ExoPlayer 内部大量依赖 Handler，若在非主线程构造播放器且未提供 Looper，会导致崩溃。必须保证 ExoPlayer.Builder(context) 在主线程创建。
  • Module 冲突：多个 Module 尝试注册同一组件（如同时设置两个 RenderersFactory），会按照 Module 顺序覆盖，可能导致预期外的行为。建议 Module 内优先调用 builder.setRenderersFactory(…) 前检查是否已存在。
  • Listener 内存泄漏：addListener 后未在 onDestroy 中使用 removeListener，可能导致 Activity 泄漏。推荐使用 WeakReference 或生命周期绑定（如 AndroidX Lifecycle）。
  • 自定义 DataSource 未实现 open 的异常处理：open() 方法可能抛出 IOException，需捕获并转换为 PlaybackException 让播放器处理。
常见错误示例：在自定义 Renderer 的 render 方法中直接抛出未捕获异常，会导致播放器进入 STATE_IDLE 且无法恢复。正确的做法是调用 BaseRenderer.onStreamChanged 并通过 PlaybackException 通知上层。

1.6 性能与稳定性优化

针对扩展场景，以下优化策略可显著提升播放体验：

  • 缓存 DataSource 拦截：使用 CacheDataSource.Factory 包装本地缓存，减少网络请求。若自定义 DataSource，建议继承 BaseDataSource 并复用连接池。
  • 合理设置 LoadControl：对于低延迟场景（直播），使用 DefaultLoadControl.Builder() 调小缓冲区大小（如 setBufferDurationsMs(500, 1000, 200, 500)）。
  • Renderer 优先级：在多 Track 时，确保自定义 Renderer 的 getTrackType 返回值唯一，避免与系统 Renderer 冲突导致选择失败。
  • Module 懒加载：如果 Module 包含重量级初始化（如 DRM 会话），可在 getComponent 中优雅降级，使用 Lazy 或协程异步初始化。
← 上一章 📖 返回目录 下一章 →