Android TV 接入 ExoPlayer 实践 —— 安卓电视端媒体播放（Jetpack Compose 版）

完整示例代码 Github 地址https://github.com/prahaladsharma/AndroidTV_App

本文主要介绍如何结合 ExoPlayer、MediaSession 和 Jetpack Compose，搭建一个健壮的 Android TV 媒体播放器。面向正在开发 Android TV 应用的开发者（优先适配遥控器/DPAD交互），要求读者具备基础的 Android 和 Compose 开发知识。

为什么 Android TV 需要特殊处理？

• TV 应用运行在大屏设备上，通常只能通过遥控器（DPAD、播放暂停键、媒体按键）操作，焦点管理和适配遥控器的控制逻辑至关重要。
• 系统级媒体控制（快捷设置、Google 助理、遥控器OSD面板）都依赖正确配置的 MediaSession。
• TV 设备通常需要播放自适应流媒体（HLS/DASH），往往还需要支持字幕、缓存，以及处理播放中断和音频焦点。

推荐架构总览

• UI层：采用 Jetpack Compose 遵循 TV UI 设计规范，使用 AndroidView 承载 ExoPlayer 的 PlayerView（StyledPlayerView）来实现高效的视频渲染。
• 播放器层：使用 ExoPlayer（推荐 Media3 版本的 ExoPlayer），托管在可感知生命周期的组件中（ViewModel 或者独立 Service）。
• MediaSession：使用 MediaSessionCompat 或者 androidx.media3.session.MediaSession 将播放器对接系统，实现媒体按键响应、播放恢复、TV 桌面启动器集成等能力。
• MediaBrowserService（可选）：如果需要支持系统级内容浏览（Leanback、频道、系统集成），实现 MediaBrowserServiceCompat 即可。
• 后台播放：如果需要跨应用生命周期保持播放，推荐把 ExoPlayer 托管在 Service 中，适合长视频播放和系统交互场景。
• 缓存：使用 SimpleCache + CacheDataSource 实现离线缓存，提升在线播放流畅度。
• DRM：如果需要版权保护，可以通过 ExoPlayer 集成 Widevine。

本文示例将实现什么？

我们将搭建一个基于 Compose 的 Android TV 应用，实现以下功能：

• 使用 ExoPlayer 播放 HLS 或 DASH 流媒体
• 在 Compose 中实现适配遥控器的播放暂停、快进快退、字幕切换浮层控制
• 集成 MediaSession，支持遥控器媒体按键和系统 UI 控制播放
• 正确处理音频焦点和生命周期资源清理
• 演示缓存和字幕支持

示例项目结构

/app  
  /src/main/java/com/androidtv  
    MainActivity.kt  
    player/  
      PlayerViewModel.kt  
      ExoPlayerHolder.kt  
      MediaSessionConnector.kt  
      CacheProvider.kt  
    ui/theme  
      PlayerScreen.kt  
      ControlsOverlay.kt  
  AndroidManifest.xml  
  res/values/...

清单文件配置

<manifest ...><application ...><activity  
      android:name=".MainActivity"  
      android:exported="true"  
      android:banner="@drawable/your_tv_banner"  
      android:label="@string/app_name"><intent-filter><action android:name="android.intent.action.MAIN"/><category android:name="android.intent.category.LEANBACK_LAUNCHER"/><category android:name="android.intent.category.LAUNCHER"/></intent-filter></activity><!-- 如果需要在 Service 中实现后台播放控制 --><service  
      android:name=".player.MediaPlaybackService"  
      android:exported="false"  
      android:foregroundServiceType="mediaPlayback"><intent-filter><action android:name="android.media.browse.MediaBrowserService"/></intent-filter></service></application></manifest><!-- 添加 LEANBACK_LAUNCHER 分类才能让应用出现在 TV 桌面启动器中 -->

核心实现步骤

1. 生命周期安全的 ExoPlayer 持有类

ExoplayerHolder 负责创建和持有 ExoPlayer 实例，配置媒体源和缓存：

// ExoPlayerHolder.kt  
package com.androidtv.player  
  
importandroid.content.Contextimportcom.google.android.exoplayer2.ExoPlayerimportcom.google.android.exoplayer2.MediaItemimportcom.google.android.exoplayer2.upstream.DefaultDataSourceimportcom.google.android.exoplayer2.source.MediaSourceimportcom.google.android.exoplayer2.source.ProgressiveMediaSourceimportcom.google.android.exoplayer2.source.hls.HlsMediaSourceimportcom.google.android.exoplayer2.util.Utilimportandroidx.lifecycle.DefaultLifecycleObserverimportandroidx.lifecycle.LifecycleOwnerclassExoPlayerHolder(  
    private val context: Context,  
) : DefaultLifecycleObserver {  
  
    val player: ExoPlayer by lazy {  
        ExoPlayer.Builder(context).build()  
    }  
  
    fun prepareAndPlay(url: String, playWhenReady: Boolean = true) {  
        val mediaItem = MediaItem.fromUri(url)  
        val dataSourceFactory = DefaultDataSource.Factory(context)  
        val mediaSource: MediaSource = when {  
            url.contains(".m3u8") -> HlsMediaSource.Factory(dataSourceFactory).createMediaSource(mediaItem)  
            else-> ProgressiveMediaSource.Factory(dataSourceFactory).createMediaSource(mediaItem)  
        }  
        player.setMediaSource(mediaSource)  
        player.prepare()  
        player.playWhenReady = playWhenReady  
    }  
  
    override fun onPause(owner: LifecycleOwner) {  
        player.pause()  
    }  
  
    override fun onDestroy(owner: LifecycleOwner) {  
        player.release()  
    }  
}

💡 注意：

• 如果播放 DASH 流，请使用 DashMediaSource
• 如果需要 DRM，请配置 MediaItem.DrmConfiguration

2. ViewModel 管理播放器生命周期和配置

// PlayerViewModel.kt  
package com.androidtv.player  
  
importandroid.app.Applicationimportandroidx.lifecycle.AndroidViewModelimportandroidx.lifecycle.viewModelScopeimportkotlinx.coroutines.Dispatchersimportkotlinx.coroutines.launchclassPlayerViewModel(application: Application) : AndroidViewModel(application) {  
    val exoHolder = ExoPlayerHolder(application)  
  
    fun playUrl(url: String) {  
        viewModelScope.launch(Dispatchers.Main) {  
            exoHolder.prepareAndPlay(url)  
        }  
    }  
  
    override fun onCleared() {  
        // 如果没有其他地方通过生命周期观察者管理，在这里释放资源
        exoHolder.player.release()  
        super.onCleared()  
    }  
}

3. 集成 MediaSession

将 ExoPlayer 对接 MediaSessionCompat，才能让媒体按键和系统控制正常工作：

// MediaSessionConnector.kt  
package com.androidtv.player  

importandroid.content.Contextimportandroid.support.v4.media.session.MediaSessionCompatimportandroidx.media.session.MediaButtonReceiverimportcom.google.android.exoplayer2.Playerimportcom.google.android.exoplayer2.ext.mediasession.MediaSessionConnectorclassMediaSessionConnectorHelper(  
    context: Context,  
    private val player: Player  
) {  
    private val mediaSession: MediaSessionCompat =  
        MediaSessionCompat(context, "TVPlayerMediaSession").apply {  
            isActive = true  
        }  

    private val connector = MediaSessionConnector(mediaSession)  

    init {  
        connector.setPlayer(player)  
    }  

    fun release() {  
        connector.setPlayer(null)  
        mediaSession.release()  
    }  
}

💡 注意：

• ExoPlayer 提供的 MediaSessionConnector 可以帮我们省去大量胶水代码
• 如果需要支持可浏览内容，可以额外实现 PlaybackPreparer 和 QueueNavigator

4. Compose 播放器页面：通过 AndroidView 嵌入 PlayerView

StyledPlayerView（ExoPlayer 原生UI组件）可以高效渲染视频，我们再用 Compose 做自定义控制浮层：

// PlayerScreen.kt  
package com.androidtv.ui.theme  

importandroid.view.ViewGroupimportandroidx.compose.foundation.layout.Boximportandroidx.compose.foundation.layout.fillMaxSizeimportandroidx.compose.runtime.*importandroidx.compose.ui.Modifierimportandroidx.compose.ui.viewinterop.AndroidViewimportcom.google.android.exoplayer2.ui.PlayerViewimportcom.example.tvplayer.player.PlayerViewModelimportandroidx.lifecycle.viewmodel.compose.viewModel@Composable  
fun PlayerScreen(  
    viewModel: PlayerViewModel = viewModel(),  
    mediaUrl: String  
) {  
    val player = viewModel.exoHolder.player  

    LaunchedEffect(mediaUrl) {  
        viewModel.playUrl(mediaUrl)  
    }  

    Box(modifier = Modifier.fillMaxSize()) {  
        AndroidView(  
            factory = { ctx ->  
                PlayerView(ctx).apply {  
                    useController = false // 我们自己在 Compose 中实现自定义控制
                    player = player  
                    layoutParams = ViewGroup.LayoutParams(  
                        ViewGroup.LayoutParams.MATCH_PARENT,  
                        ViewGroup.LayoutParams.MATCH_PARENT  
                    )  
                }  
            },  
            modifier = Modifier.fillMaxSize()  
        )  

        // 叠加Compose控制浮层（快进、播放暂停等）
        ControlsOverlay(player = player)  
    }  
}

ControlsOverlay 可以响应 DPAD 按键事件，根据状态显示/隐藏UI。

5. 适配遥控器的控制浮层

实现一个简单支持焦点、适配遥控器的浮层，包含播放暂停和快进快退功能：

// ControlsOverlay.kt  
package com.androidtv.ui.theme  

importandroidx.compose.foundation.focusableimportandroidx.compose.foundation.layout.*importandroidx.compose.material3.Buttonimportandroidx.compose.material3.Textimportandroidx.compose.runtime.*importandroidx.compose.ui.Modifierimportcom.google.android.exoplayer2.Playerimportandroidx.compose.ui.unit.dpimportandroidx.compose.ui.Alignment@Composable  
fun ControlsOverlay(player: Player) {  
    var isVisible by remember { mutableStateOf(true) }  

    Box(  
        modifier = Modifier  
            .fillMaxSize(),  
        contentAlignment = Alignment.BottomCenter  
    ) {  
        Row(modifier = Modifier  
            .padding(24.dp)  
            .focusable(true),  
            horizontalArrangement = Arrangement.spacedBy(16.dp)  
        ) {  
            Button(onClick = {  
                if (player.isPlaying) player.pause() else player.play()  
            }) {  
                Text(if (player.isPlaying) "暂停"else"播放")  
            }  

            Button(onClick = {  
                val newPos = (player.currentPosition -10_000).coerceAtLeast(0)  
                player.seekTo(newPos)  
            }) {  
                Text("后退 10s <<")  
            }  

            Button(onClick = {  
                val newPos = (player.currentPosition +10_000).coerceAtMost(player.duration.coerceAtLeast(0))  
                player.seekTo(newPos)  
            }) {  
                Text("前进 10s >>")  
            }  
        }  
    }  
}

请确保 TV 端焦点功能正常工作：Compose TV 库提供了焦点遍历和焦点高亮的能力，focusable(true) 是基础要求。

处理遥控器（DPAD/媒体按键）

• 如果 MediaSession 已经激活，ExoPlayer + MediaSession 会自动处理所有 KEYCODE_MEDIA_* 按键事件。
• 在 Compose 浮层中处理 DPAD 导航时，请正确使用 focusable() 和 Compose TV 焦点API，确保遥控器可以正常导航到各个按钮。
• 如果需要在 Activity 中直接拦截按键事件，可以重写 onKeyDown/onKeyUp 方法，把事件转发给播放器控制或者 MediaSession。全局媒体按键优先交给 MediaSession 处理。

// 在 Activity 中添加
override fun onKeyDown(keyCode: Int, event: KeyEvent?): Boolean {  
    when (keyCode) {  
        KeyEvent.KEYCODE_MEDIA_PLAY_PAUSE -> {  
            if (player.isPlaying) player.pause() else player.play()  
            return true  
        }  
        // 按需处理快进快退按键
    }  
    returnsuper.onKeyDown(keyCode, event)  
}

只要激活了 MediaSession，大部分按键都会被系统自动处理，不需要手动编写代码。

后台播放与 Service

如果你的 TV 应用需要在 Activity 不可见时继续播放（比如用户最小化应用），请将 ExoPlayer 托管在 MediaBrowserServiceCompat 或者前台 Service 中。这种方式同时支持锁屏控制和系统级控制。

核心要点：

1. 创建继承自 MediaBrowserServiceCompat 的 MediaPlaybackService
2. 创建 MediaSession 并设置 Session Token
3. 如果需要支持内容浏览，暴露媒体浏览器目录
4. 播放时将服务升级为前台服务，并发送一个媒体样式通知

TV 端的后台播放场景并不多，大部分 TV 应用只需要在应用前台时播放即可。

字幕处理

ExoPlayer 原生支持 WebVTT、SRT、TTML 等文本字幕格式，只需要给 MediaItem 添加字幕配置即可：

val subtitle = MediaItem.Subtitle(  
    uri = Uri.parse("https://example.com/subtitles_en.vtt"),  
    mimeType = MimeTypes.TEXT_VTT,  
    language ="en",  
    selectionFlags =0  
)  

val mediaItem = MediaItem.Builder()  
    .setUri(videoUri)  
    .setSubtitles(listOf(subtitle))  
    .build()  
player.setMediaItem(mediaItem)

ExoPlayer 会自动把字幕渲染到 PlayerView 上。如果你需要自己在 Compose 浮层中绘制字幕，只需要监听播放器的文本输出事件即可。

缓存实现

使用 SimpleCache 配合 CacheDataSourceFactory 即可实现缓存，让在线播放更流畅：

// CacheProvider.kt 单例实现
importandroid.content.Contextimportcom.google.android.exoplayer2.upstream.cache.SimpleCacheimportcom.google.android.exoplayer2.upstream.cache.LeastRecentlyUsedCacheEvictorimportcom.google.android.exoplayer2.database.ExoDatabaseProviderimportjava.io.Fileobject CacheProvider {  
    private var simpleCache: SimpleCache?= null  

    fun getCache(context: Context): SimpleCache {  
        return simpleCache ?: synchronized(this) {  
            val cacheFolder = File(context.cacheDir, "media")  
            val evictor = LeastRecentlyUsedCacheEvictor(100L *1024L *1024L) // 最大缓存 100MB
            val dbProvider = ExoDatabaseProvider(context)  
            SimpleCache(cacheFolder, evictor, dbProvider).also { simpleCache = it }  
        }  
    }  
}

之后在构建 ExoPlayer 数据源时，使用 CacheDataSource.Factory 包装即可。

Android TV 测试要点

• 使用 Android Studio AVD 管理器提供的 Android TV 模拟器镜像测试
• 一定要测试遥控器按键交互和 DPAD 焦点导航
• 使用不同类型的流测试：HLS、DASH、普通 progressive mp4
• 测试网络中断、缓存加载和播放恢复逻辑

性能与最佳实践

• 使用 StyledPlayerView 获得最佳的视频渲染性能
• heavy 工作已经被 ExoPlayer 自动放到后台线程，不要自己在UI线程做耗时操作
• 如果播放器运行在前台 Service，请调用 player.setForegroundMode(true) 避免被系统杀死
• 不需要播放器时一定要释放资源，正确处理 onStop/onDestroy 生命周期
• 正确配置 MediaSession，让系统可以正确管理音频焦点和音频路由（比如 HDMI、电视扬声器）
• 所有 TV 端控件都需要有清晰的焦点状态，点击热区要足够大
• 遵循 10 英尺 UI 设计规范：大字体、清晰按钮、安全边距。

最简 MainActivity 示例

// MainActivity.kt 精简版
classMainActivity : ComponentActivity() {  

    private val viewModel: PlayerViewModel by viewModels()  

    override fun onCreate(savedInstanceState: Bundle?) {  
        super.onCreate(savedInstanceState)  
        setContent {  
            val testUrl ="https://storage.googleapis.com/exoplayer-test-media-0/play.mp3"// 替换成你自己的 HLS/MP4 地址
            PlayerScreen(viewModel, mediaUrl = testUrl)  
        }  
    }  

    override fun onStop() {  
        super.onStop()  
        // 如果需要Activity进入后台就停止播放，打开下面这行注释：// viewModel.exoHolder.player.pause()  
    }  

    override fun onDestroy() {  
        super.onDestroy()  
        viewModel.exoHolder.player.release()  
    }  
}

其他注意事项

• DRM：使用 DefaultDrmSessionManager + MediaItem.DrmConfiguration 配置即可
• 自适应轨道选择：配置 DefaultTrackSelector 来设置音视频画质偏好
• 多音频与字幕：可以通过 player.currentTracks 获取轨道信息，在 Compose 浮层中实现切换功能
• 画中画（PiP）：TV 设备上很少用到这个功能
• Chromecast 投屏：如果需要

原文链接：https://medium.com/@prahaladsharma4u/exoplayer-setup-for-android-tv-media-playback-on-tv-compose-part-6-e321cf4722eb