安卓TV用Compose接ExoPlayer直接抄作业

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），往往还需要支持字幕、缓存，以及处理播放中断和音频焦点。

本文示例将实现什么？

我们将搭建一个基于 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 中。这种方式同时支持锁屏控制和系统级控制。

核心要点：

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

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