Android视频播放器实战：Media3替代MediaPlayer的完整实践

简介面向Android开发者的视频播放器实现源码集中展示MediaPlayerSurfaceView、VideoView与Vitamio三种主流方案的完整代码适合从入门到进阶的开发者对照学习也可作为项目集成与二次开发的参考模板。压缩包共124个文件整体8.56MB其中包含36个Java源文件、33个Vitamio库所需的so动态库、18个PNG图片资源与16个XML布局/配置另有Gradle、properties等工程配置两个module分别对应演示源码与Vitamio官方library导入后可通过清单文件切换启动页面快速查看不同实现效果。目前已有665人学习下载。读者既能对比三种播放方式的实现差异也能掌握SurfaceView画面渲染、MediaPlayer状态控制、VideoView封装逻辑以及Vitamio扩展能力按目录结构阅读可高效吸收关键知识点对实际项目选型和技术积累均有帮助。 做Android开发这些年我接过不少播放器相关的需求身边的同事也经常问想做一个带进度条、倍速、列表播放的“正经”视频播放器到底从哪儿下手。之前网上资料普遍停留在用MediaPlayer包一层 SurfaceView 的阶段写着写着就发现控制逻辑、缓冲状态、生命周期切换全都得自己啃代码越写越厚播放效果反而一般。后来我全面切到 Media3 这套方案才算真正把“播放器”做成了能稳定上线的东西。这篇内容主要面向想从零搭一个 Android 视频播放器的开发同学也适合那些已经写了段时间页面、但一直没弄明白播放内核、文件权限、编译环境这些关联问题的人。我不打算给你贴官方文档而是把我实际搭建和调试的过程、踩过的坑、最后的取舍都摊开讲清楚你能直接照着复现。1. 播放器内核选型为什么我最终用 Media3 而不是 MediaPlayer1.1 系统自带 MediaPlayer 的边界在哪里Android 系统自带的MediaPlayer不是不能用它适合那种“播放单个 MP4、界面不需要太多定制”的场景。我刚入门那会儿也拿它写过 Demo一个 URL 丢进去setDisplay拿到 Surface然后 start看起来挺简单。但一旦需求稍微复杂点问题就全冒出来了。缓冲进度、加载状态这些细节MediaPlayer 给的回调很粗你很难拿到精细的网络带宽和缓冲百分比。列表连续播放要自己监听OnCompletionListener还得自己管理下一个视频的预加载稍微一卡顿就白屏。倍速播放效果在部分机型上声音会变调setPlaybackParams的支持程度在不同硬件上差异很大。HLS、DASH 这类流媒体协议MediaPlayer 支持得很勉强自适应码率切换更是基本指望不上。更别说自定义 UI、字幕、音频轨道切换全得自己从底层往上补。所以如果你要做一个功能稍微完整点的播放器MediaPlayer 只能当学习材料不适合当生产工具。1.2 Media3 解决了什么问题Google 后来把 ExoPlayer 整合进了 Media3 这个大项目里现在官方建议就是用 Media3 作为统一媒体库。它的核心思路是把播放器拆成多个可替换的模块资源加载、音视频解码、渲染输出、扩展控制全部解耦。你想要什么能力就往里面挂对应模块不需要的就不要引入包的体积也能控制住。我用的版本是androidx.media3:media3-exoplayer和media3-ui先把最基础的依赖放上来dependencies { implementation androidx.media3:media3-exoplayer:1.4.1 implementation androidx.media3:media3-ui:1.4.1 }从实际开发体验来说Media3 解决了我几个长期痛点ExoPlayer内部自己管理了缓冲策略列表播放时支持预加载下一个媒体项切视频非常顺滑。TrackSelector可以直接选择清晰度、音轨、字幕轨不用自己解析底层格式。支持PlaybackParameters调倍速且声音质量稳定得多。UI 层提供了一个现成的PlayerView进度条、播放/暂停、缓冲动画、横竖屏切换按钮都有你不用从零画一个播放器界面。有的同学会问那第三方的ijkplayer、VLC之类的播放器不是也很好吗确实在特定场景下它们有优势比如 IJK 对 RTSP 的支持比较好VLC 的软解能力出色。但从谷歌趋势和社区维护状态看Media3 已经是官道长线维护的项目API 设计也更贴近 Android 本身的生命周期和 Compose 生态。除非你有非常特殊的流协议需求否则在普通 App 里做内嵌视频播放Media3 是最稳的起点。2. 搭建项目时最容易翻车的编译环境2.1 Android Studio 版本与 AGP 版本怎么匹配很多同学新项目一创建就报各种编译错误头一天就卡在环境上。最典型的坑就是 Android Studio 版本和 Android Gradle PluginAGP版本对不上。我见过网上问“Android Studio Hedgehog 2023.1.1 Patch 2 支持 AGP 8 吗”这种问题。答案是支持但要注意的是Hedgehog 这个版本自己带了 AGP 的上限。一般情况下Hedgehog 内置的 Gradle 能支持到 AGP 8.2 左右compileSdk可以跑到 34。我用的是 Hedgehog 加 AGP 8.2.2 的组合线上跑了大半年没毛病。这里放一个我验证过的版本组合作为参考项目版本Android StudioHedgehog 2023.1.1 Patch 2Gradle8.2AGP8.2.2Kotlin1.9.22compileSdk34targetSdk34要判断自己本地的 AS 到底支持哪个 AGP 版本最直接的办法是在Gradle Scripts - gradle-wrapper.properties里看 Gradle 版本然后在项目的build.gradle里把 AGP 版本设置在对应的兼容区间内不要随手拉一个最新的 AGP 就往上怼。2.2 常见编译错误setting 文件加载不了 Kotlin 类我搭播放器项目的时候踩过一个挺有代表性的编译错误Could not load compiled classes for settings file ...\settings.gradle.kts.这个问题出现的原因不是你的代码写错而是 Gradle 在初始化阶段执行 setting 脚本时Kotlin DSL 编译缓存失效。常见诱因包括更换了 JDK 版本、Android Studio 升级后 Gradle 版本变化、gradle-wrapper.properties里 distributionUrl 被改过但 Gradle daemon 还保留着老的缓存。解决手段其实很粗暴关掉 Android Studio。手动删除项目根目录下的.gradle文件夹以及build文件夹。打开settings.gradle.kts和根目录build.gradle.kts检查插件版本和仓库地址。重新用“Sync Project with Gradle Files”执行同步。如果还不行就直接在命令行执行一次gradle clean或者把~/.gradle/caches里对应项目的编译缓存删掉。不要怕删缓存Gradle 会自动重建只是第一次会慢点。我个人的习惯是遇到这种问题先不急着怀疑代码肯定是环境同步出了问题排查优先级就是 JDK 版本、Gradle 版本、AGP 版本、缓存四个方向按这个顺序捋一遍基本能解决。3. 核心实现写出一个能直接上线的播放器页面3.1 布局设计与控制器绑定Media3 的 UI 已经帮我们封装了很多东西PlayerView是一个可以直接放进布局文件的组合控件。我一般这样写布局androidx.media3.ui.PlayerView android:idid/player_view android:layout_widthmatch_parent android:layout_heightwrap_content app:use_controllertrue app:controller_layout_idlayout/custom_player_controller /use_controller设为 true 时控件自带一个默认控制条点击屏幕就会浮现。默认控制条包含播放/暂停、进度条、时间文字基本够用。如果你想要倍速按钮、全屏按钮、清晰度切换入口就需要做自定义控制器布局。我通常的做法是拷贝一份 Media3 源码里的default_controller_layout.xml然后添加自己的按钮一个典型的自定义控制器会有这几部分播放/暂停按钮进度条和时间显示倍速按钮全屏切换按钮音轨或字幕切换入口自定义后需要在PlayerView上进行绑定playerView.setControllerLayoutId(R.layout.custom_player_controller)这里有个小经验默认控制器在屏幕底部的布局首次进入时建议设置playerView.controllerAutoShow true让用户点开机后控制条立刻出现交互反馈会更直接。3.2 Player 的初始化、释放与生命周期管理播放器对象不是随用随丢的一个稳定的播放器必须在 Activity 或 Fragment 的生命周期内做到“精确创建”和“精确释放”。我通常使用的模式是private var player: ExoPlayer? null private fun initializePlayer() { player ExoPlayer.Builder(context) .setSeekBackIncrementMs(10000) .setSeekForwardIncrementMs(10000) .build() .also { exoPlayer - playerView.player exoPlayer exoPlayer.setMediaItem(mediaItem) exoPlayer.prepare() exoPlayer.playWhenReady true } } private fun releasePlayer() { playerView.player null player?.release() player null }然后在 Activity 中把生命周期绑定好onStart里如果当前没有播放器就initializePlayer()。onStop里暂停播放视需求决定是否释放后台播放场景需要特殊处理。onDestroy里必须releasePlayer()否则会内存泄漏。onSaveInstanceState里把当前播放位置保存下来转屏后恢复。还有一点容易忽略就是音频焦点。视频 App 一般不需要后台传音但你播放过程中来了电话或者对方 App 抢了音频焦点播放器要能自觉暂停。网上很多播放器没有处理 AudioFocus结果用户看视频时来了通知声音直接变成“双声道打架”。3.3 横竖屏切换与手势快进快退现在的播放器横竖屏切换基本是标配。Android 12 之前常规做法是在配置变更里手动切换布局Android 12 开始官方提供了setRotation的过渡动画但实际开发中我还是习惯手动处理因为播放器的控制栏在全屏和窗口模式下通常有不同布局。我这里给一个在onConfigurationChanged里切换全屏状态的参考override fun onConfigurationChanged(newConfig: Configuration) { super.onConfigurationChanged(newConfig) if (newConfig.orientation Configuration.ORIENTATION_LANDSCAPE) { // 隐藏状态栏全屏显示 PlayerView window.decorView.systemUiVisibility View.SYSTEM_UI_FLAG_FULLSCREEN params LinearLayout.LayoutParams(MATCH_PARENT, MATCH_PARENT) } else { // 恢复竖屏比例比如 16:9 或 4:3 window.decorView.systemUiVisibility View.SYSTEM_UI_FLAG_VISIBLE } playerView.layoutParams params }如果你愿意花点时间我建议做一个相对平滑的动画过渡而不是瞬间跳变。手势方面Media3 的 PlayerView 没有内置双击快进和滑动调节进度需要自己实现GestureDetector。双击右侧屏幕快进 10 秒、左侧回退 10 秒这个交互非常符合用户习惯。我在项目里会在PlayerView上挂一个SimpleOnGestureListenergestureDetector GestureDetector(context, object : GestureDetector.SimpleOnGestureListener() { override fun onDoubleTap(e: MotionEvent): Boolean { val width playerView.width if (e.x width / 2) { player?.seekForward() } else { player?.seekBack() } return true } })注意seekForward()和seekBack()是需要自定义配置增量的我在初始化时设置了setSeekForwardIncrementMs(10000)正好配合双击手势。用户实际体验下来反馈很正向因为手指不用再精准拖拽进度条了。3.4 播放列表、倍速与字幕的细节处理列表播放是视频类 App 最常用的需求之一。Media3 对播放列表的支持非常成熟你只需要把多个 MediaItem 一次性传给播放器val firstItem MediaItem.fromUri(https://example.com/video1.mp4) val secondItem MediaItem.fromUri(https://example.com/video2.mp4) player?.setMediaItems(listOf(firstItem, secondItem), startIndex 0, startPositionMs 0L) player?.prepare()播放完第一个会自动切到第二个如果有片头片尾、选集这种连续看剧的场景列表模式几乎是必须用上的。而且它内部的预加载机制会提前把下一个视频的缓冲准备好切集时肉眼几乎没有等待。倍速播放我建议用PlaybackParametersplayer?.playbackParameters PlaybackParameters(1.5f, 1f)第二个参数是 pitch保持 1.0 才不会让声音变尖。Media3 对倍速的音频处理做得比较均衡没有以前 MediaPlayer 那种明显的“电子音”问题。字幕方面如果视频自带字幕轨用TrackSelector就可以在运行时切换如果是独立的.srt文件通常需要先解析后通过SidecarConfiguration绑定到 MediaItem 上这部分对于视频 App 不是高优需求我一般是二期再上避免一开始功能面铺太开。4. 播放本地视频绕不开的内容 URI 与文件访问权限4.1 content://、file://、SAF 到底怎么选很多人在播放器里加载本地视频时都会遇到一个问题拿到了一个路径但播不出来。这不是播放器的问题而是你根本不应该直接拿文件路径去播放。Android 从 7.0 开始就引入 FileUriExposedException限制了file://Scheme 在跨应用间传递到 Android 11 以后Scoped Storage 进一步限制了对公共目录的随机访问。我实测下来正确方式只有一条通过content://形式的 URI 访问。如果你用系统文件选择器去选视频拿到的回调是一个content://UriActivityResultContracts.OpenDocument()选择文件后你可以直接把这个 Uri 传给播放器val mediaItem MediaItem.fromUri(uri) player?.setMediaItem(mediaItem)不需要申请任何存储权限这也是我最推荐的方式。因为 Media3 底层用的是ContentResolver来打开文件对于content://Uri 天然支持。如果你是读取自己应用私有目录或应用专属目录里的视频直接用绝对路径也合法。但凡涉及读取公共存储图片或视频不要碰Environment.getExternalStoragePublicDirectory在 Android 11 上这条路基本走不通。4.2 使用 Storage Access Framework 打开本地视频完整流程是这样在页面里注册一个ActivityResultLauncherprivate val openVideoLauncher registerForActivityResult( ActivityResultContracts.OpenDocument() ) { uri: Uri? - uri ?: returnregisterForActivityResult contentResolver.takePersistableUriPermission( uri, Intent.FLAG_GRANT_READ_URI_PERMISSION ) playVideo(uri) }通过按钮触发系统文件选择器openVideoLauncher.launch(arrayOf(video/*, application/octet-stream))拿到 uri 后直接绑定到播放器。takePersistableUriPermission这一步非常关键。如果你只是临时播放可以不调用它但如果你需要把这个视频加进“最近播放”列表下次 App 启动还要继续播放就必须申请持久化 URI 授权。否则 App 重启后那个 content:// Uri 就会失效。实际测试下来系统文件选择器对 MP4、MKV、WebM 等常见格式识别都很顺畅。某些小众格式或者无扩展名的视频文件媒体类型会返回application/octet-stream所以上面我特意在 launch 的类型数组里加了这个避免选完文件后出现“无法打开”的情况。5. 实操中踩过的坑与排查方法5.1 虚拟设备无效AVD 启动就黑屏或直接报错开发阶段我经常遇到模拟器启动不了的问题很多同学会以为是代码问题其实大部分是 AVD 配置和系统的虚拟化支持之间没对齐。常见的现象是模拟器能启动但界面一直停在开机动画普通 Android 版本还能等新版本系统基本会卡到死机。排查顺序如下确认 BIOS 里开启了硬件虚拟化Windows 端可用任务管理器查看“虚拟化”是否启用。Android Studio 里 AVD Manager 的 Device 设置里Graphics 切换为 “Software — GLES 2.0”能解决不少渲染启动崩溃。检查 Android SDK Platform-Tools 版本模拟器内核和 adb 版本需要匹配。如果项目依赖的 SDK 版本高于模拟器的系统镜像版本应用可能直接安装失败。如果你用的电脑配置一般我建议直接拿真机调试视频播放因为编解码器在模拟器上表现和真机差异很大很多 H.265 视频在模拟器上会因为缺少硬件解码器而黑屏但在真机上一切正常。“虚拟设备无效”不一定是设备坏更多时候是环境没对齐。5.2 播放器崩溃解码失败、缓冲黑屏的处理播放视频最让人头疼的往往是“黑屏但声音正常”或者“播放进度条在走但画面卡住”。这种问题八成跟视频编码格式和硬件解码能力有关。Media3 默认会优先走硬件解码器如果当前设备硬件不支持该编码格式就会闪退或黑屏。一个比较稳的处理是启用降级逻辑在构建播放器时设置启用软件解码器作为兜底val videoRendererFactory DefaultRenderersFactory(context) .setExtensionRendererMode(DefaultRenderersFactory.EXTENSION_RENDERER_MODE_ON)但这只能解决部分问题真正稳妥的做法是在onPlayerError里拦截错误信息针对PLAYER_ERROR_VIDEO_DECODE_FAILED这类错误尝试切换到软解模式重建播放器。说到底视频 App 一定要有“错误提示 重新尝试”的交互不然用户只会看着一个黑屏一脸问号。另一个常见问题是弱网环境下缓冲一直没有结束经验值是视频加载 5 秒内没出画面就要主动提示“网络不佳”并给重试按钮。Media3 里可以通过监听Player.Listener里的状态变化来判断STATE_BUFFERING进入缓冲超过阈值后调用player.setForegroundMode(false)之类操作不要赌用户有耐心等视频播放器的体验就是快、准、稳。5.3 性能分析火焰图不是玄学但要注意姿势热门词里出现了“android studio 火焰图 指南”这个东西在排查播放器卡顿、掉帧的时候确实有用但我要说清楚火焰图是性能分析工具的一种可视化方式重点不是看图的形状而是找到哪一层函数占用了大量 CPU。Android Studio 自带的 CPU Profiler 可以录制 Java 层方法的调用堆栈。当视频播放时卡顿我会先录制一段从播放到卡顿出现的过程然后看火焰图里哪个函数在卡顿期间最宽。通常问题出在以下几个方面解码后转 Bitmap 时频繁内存分配导致 GC 压力大。UI 线程做了网络请求或文件读取。自定义控制器布局里写了过度复杂的绘制逻辑。如果火焰图里显示主线程长时间占用那代码问题没跑如果显示解码线程全满那大概率是当前机器软解顶不住高分辨率视频。此时就该考虑降低清晰度或切换解码方案而不是继续堆代码。5.4 权限相关记录为什么申请了权限还是读不到视频常见问题里有一个非常典型明明在 AndroidManifest 里写了READ_EXTERNAL_STORAGE代码运行时也授予了权限但用MediaStore查询不到任何视频。这多半是因为 targetSdk 和宿主机版本不一致。Android 13 开始读取视频文件的权限从READ_EXTERNAL_STORAGE细分成了READ_MEDIA_VIDEO。如果你的 targetSdk 已经到 33 或以上就不要再依赖旧的宽泛权限了需要单独申请uses-permission android:nameandroid.permission.READ_MEDIA_VIDEO /如果是比较老的设备Android 12 以下再用READ_EXTERNAL_STORAGE反正权限逻辑要按系统版本做分支。这里最容易踩的坑就是 Unity 调试或者旧项目升级后忘了动态判断权限结果高版本设备上一直返回空列表。我的建议是播放器应用最好设置 targetSdk 为 34并在AndroidManifest.xml里同时声明两个权限旧版和新版然后在运行时按Build.VERSION.SDK_INT分别申请。这样兼容性最优也不影响正常使用。最后再分享一个我在实际项目里沉淀下来的小习惯播放器页面一定要在 Debug 模式下加上“当前解析信息”的调试浮层比如视频分辨率、编码格式、缓冲状态、丢弃帧率、当前渲染器类型。平时不显示打开开关后立刻能看到播放器内部到底在干什么。很多时候你觉得“莫名其妙卡了”“画质变差了”浮层一开原因一眼就明朗——要么是切到软解了要么是缓冲策略在反复横跳。做成功能之前先让自己能一眼看穿播放器的五脏六腑这比任何花哨的优化都管用。本文还有配套的精品资源点击获取