简介面向Android开发者的视频播放器实现源码包集中展示MediaPlayerSurfaceView、VideoView以及Vitamio三种主流方案的工程化写法。包内两个模块需同时导入一个为可运行源码另一个为Vitamio依赖库便于对照学习通过修改清单文件中的启动页面即可快速切换不同实现适合初入播放器开发或需要选型参考的读者。压缩包共124个文件约8.56MB其中以36个Java源码、33个so动态库和16个XML布局/配置为主另有18张PNG资源界面切图结构清晰。已有665人浏览学习适合用于理解播放器生命周期、视频渲染与第三方库集成等关键知识点。 上周帮朋友整理平板里的教学视频他提了个需求一个能自动记住上次看到哪、能倍速、没广告的播放器。我在应用市场翻了一圈要么一顿权限申请要么播放两三集就弹一次推广确实没找到称心的。后来我说要不咱自己写一个吧于是这个Android视频播放器项目就立项了。这篇文章不打算讲太多高深理论就按我实际开发的顺序把内核选型、文件访问、播放功能、踩坑记录、进阶玩法完整过一遍。看这篇文章的人不管你是做本地视频播放的、正在学Kotlin找练手项目的还是单纯好奇ExoPlayer内部机制应该都能拿到一些直接能用的东西。整个工程基于Kotlin Jetpack Media3结构不复杂跟着思路走完全能自己复现。1. 这个项目是怎么立项的需求清单和架构边界1.1 需求清单是怎么来的朋友的需求其实很朴素把平板里下载的几十个教学视频按文件夹连续播放关掉后再打开能回到上次暂停的位置支持1.25倍、1.5倍、2倍速界面干净没有广告。就这么四条放在任何视频播放器App里都是基础功能但真要逐条对着市场上的App去筛选反而没有几个能完全满足。有的播放器对文件夹支持很弱只能一个一个文件手动加有的倍速档位给得少想微调都不行最烦的是安装包权限列表里躺着一堆和播放毫无关系的敏感权限。我把这些痛点整理成了正式的需求清单本地视频扫描按文件夹维度组织记忆每个视频的播放位置重启App后仍能恢复支持自定义倍速变速播放的同时不能变音调竖屏列表、横屏播放的状态切换无广告、无统计、无多余权限。做为一个自用工具我不需要账号系统、不需要在线视频分发、不需要投屏这些都可以砍掉。项目边界小了反而能把每个点做扎实。1.2 技术栈与工程结构技术栈方面语言选Kotlin这是目前Android开发的主流。UI这一层我没有引入复杂架构简单用Activity Fragment RecyclerView。视频播放器的核心逻辑在Player实例本身页面结构不复杂过度设计反而增加维护成本。整个工程分三个模块视频扫描与持久化负责用MediaStore扫描本地视频、保存播放进度播放页面负责视频画面渲染、手势控制、播放列表逻辑工具与异常兜底网络明文配置、解码器降级、前台服务保活。说实话我也考虑过直接拿GitHub上现成的播放器项目改。搜了一圈发现很多项目停更好几年用的还是老旧的API升级到Android 13以后满屏兼容问题。与其花时间改别人的陈旧代码不如用Google官方维护的Media3把核心逻辑重写一遍这个决定在后面的开发中省了非常多时间。2. 播放内核选型Media3、IjkPlayer还是原生MediaPlayer2.1 四套主流内核的对比选播放内核是第一个要拍板的事。我整理了当下能用到的几套方案逐项对比后做的决定。方案维护状态格式与协议支持可定制性包体积适合场景原生MediaPlayer系统级维护MP4、HLS等基础支持很低错误信息粗糙最小简单播放Demo、系统播放器IjkPlayer停更多年FFmpeg全格式能力强高但需要自行适配现代系统较大老项目、对格式兼容有执念libVLC持续维护几乎全格式全协议高但API偏底层很大需要极高格式兼容性的工具型AppMedia3 ExoPlayerGoogle官方维护本地流媒体主流格式高渲染器可自定义适中绝大多数新项目、本文选择2.2 为什么最终选了Media3Media3的前身就是ExoPlayerGoogle在2022年左右把它整体挪到了androidx.media3包下和Jetpack生态完全打通。选它最核心的理由是持续维护。这在Android生态里太重要了Android每年更新一次存储策略、权限模型、后台限制一个不再维护的播放内核迟早会在新系统上翻车。IjkPlayer的FFmpeg能力确实强但它已经宣布停止维护很多年硬解适配、Surface渲染这些都需要自己打补丁适合有专门团队维护的老项目不适合我这种一个人开发的自用工具。libVLC格式兼容性是天花板级别可包体积也感人为了放个本地视频塞进去几十MB和解码器全家桶实在不划算。选Media3还有个隐藏优势它把MediaSession、媒体通知、前台服务这些都打包进了官方体系后面做后台播放续播、通知栏控制非常顺不用自己拼装第三方组件。依赖配置如下implementation androidx.media3:media3-exoplayer:1.3.1 implementation androidx.media3:media3-ui:1.3.1 implementation androidx.media3:media3-session:1.3.1如果遇到不常见的视频编码格式我再补一个media3-decoder-ffmpeg扩展这个后面聊踩坑时细说。3. 先解决文件访问分区存储时代Android 11怎么读视频3.1 存储权限的变迁绝对路径为什么不管用了文件访问是本地视频播放器第一个绕不开的坎。Android 10之前读公共存储只需要READ_EXTERNAL_STORAGE权限然后用Environment.getExternalStorageDirectory()拼路径就能直接拿文件。Android 10开始引入分区存储应用对公共目录的访问必须通过MediaStore或SAF直接拼路径的方式越来越不可靠。到Android 11强制开启后像/storage/emulated/0/Android/data/包名/这种写法要么只能访问到自己应用的目录要么直接Permission Denied。也是因为这样现在网上搜到的大量“安卓视频路径合集”老代码都失效了。它们还在教人怎么拼路径、怎么遍历/mnt/sdcard/DCIM这套东西在新系统上跑起来就是一团糟。正确做法是彻底放弃路径思维改用Uri和ContentResolver这根“管道”操作文件。3.2 用MediaStore扫描视频文件我在扫描模块里用的方式是通过MediaStore查询所有视频文件这在大多数设备上覆盖了用户能看到的所有公共媒体文件。核心代码并不复杂val collection MediaStore.Video.Media.EXTERNAL_CONTENT_URI val projection arrayOf( MediaStore.Video.Media._ID, MediaStore.Video.Media.DISPLAY_NAME, MediaStore.Video.Media.SIZE, MediaStore.Video.Media.DURATION, MediaStore.Video.Media.DATA ) contentResolver.query(collection, projection, null, null, null)?.use { cursor - val idColumn cursor.getColumnIndexOrThrow(MediaStore.Video.Media._ID) val nameColumn cursor.getColumnIndexOrThrow(MediaStore.Video.Media.DISPLAY_NAME) while (cursor.moveToNext()) { val id cursor.getLong(idColumn) val name cursor.getString(nameColumn) val uri ContentUris.withAppendedId(MediaStore.Video.Media.EXTERNAL_CONTENT_URI, id) // 用uri交给播放器不要存绝对路径 } }注意一个细节DATA这一列在Android 10及以上依然能读到真实路径但拿到路径后不要拿去new File()。分区存储下你未必有那个文件的直接访问权限正确姿势是始终通过contentResolver.openFileDescriptor(uri, r)或直接把这个uri交给Media3去播放。3.3 用SAF处理“用户手动选文件夹”的场景MediaStore能覆盖普通视频但有些视频存在用户自己下载的特殊目录里或者被第三方应用以私有方式保存MediaStore不一定收录。这种情况我用系统文件选择器兜底也就是SAFStorage Access Framework。调用方式很简单val intent Intent(Intent.ACTION_OPEN_DOCUMENT_TREE).apply { addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION or Intent.FLAG_GRANT_PERSISTABLE_URI_PERMISSION) } startActivityForResult(intent, REQ_CODE_OPEN_DIR)拿到返回的Uri之后调用takePersistableUriPermission持久化授权这样以后启动App不用再让用户选一次。这个授权持久化很关键漏了的话你下载的播放列表一重启就全部失效。3.4 关于“直接访问data目录”这条老路为什么一定要放弃我在搜索热词里看到大量类似android/data/包名/files/...的路径这其实是很多下载类应用自己的私有外部目录。Android 11之后跨应用去读其他App的android/data目录基本就是Permission Denied就算拿到一个content://开头的Uri授权范围也局限于授予方和你App之间没做持久化照样失效。所以我在这个项目里立了一条规矩扫描层只暴露Uri和元数据所有读取都通过ContentResolver整个App里不出现任何拼出来的绝对文件路径。这条规矩帮我避开了很多莫名其妙的崩溃。4. 播放器本体搭建从PlayerView到播放列表和手势控制4.1 创建播放器实例的几个关键选择播放页布局我直接用Media3提供的PlayerView它内部封装了Surface、TextureView、手势点击、加载动画比自己去维护一个TextureView再处理前后台切换省心太多。布局里放一个PlayerView代码里创建ExoPlayer并绑定val renderersFactory DefaultRenderersFactory(context) .setExtensionRendererMode(DefaultRenderersFactory.EXTENSION_RENDERER_MODE_PREFER) val player ExoPlayer.Builder(context, renderersFactory).build() playerView.player player val mediaItems videoFiles.map { file - MediaItem.Builder() .setUri(file.uri) .setMediaId(file.id.toString()) .build() } player.setMediaItems(mediaItems, startIndex, 0L) player.prepare() player.play()这里setMediaItems(mediaItems, startIndex, startPositionMs)这个重载是连续播放的关键第一参数是列表第二参数指定从第几个开始播第三参数指定起始位置毫秒。用它能同时实现“从文件夹中间某集开始放”和“从上次暂停处继续放”。4.2 播放进度记忆与恢复进度记忆我用SharedPreferences就够不需要上数据库。在onPause和onStop里取player.currentPosition以文件Uri字符串为key存下来进入播放页时读出来把startIndex定位到对应媒体项startPositionMs填成保存的进度。override fun onPause() { super.onPause() prefs.edit() .putLong(currentFileUri, player.currentPosition) .apply() player.pause() }这个方案简单直接满足自用需求。如果以后列表膨胀到上千个视频再考虑换成Room数据库现阶段没必要复杂化。4.3 手势控制音量、亮度、快进快退播放页的手势我用GestureDetector统一处理。单指双击播放/暂停左边竖滑调亮度右边竖滑调音量横向滑动快进或快退。实现思路不复杂亮度拿到Activity的Window修改WindowManager.LayoutParams.screenBrightness范围0f到1f音量通过AudioManager.setStreamVolume(AudioManager.STREAM_MUSIC, ...)调整进度player.seekTo(player.currentPosition delta)delta根据手指横向位移计算。有个容易忽略的细节调音量亮度时一定要显示一个浮层提示否则用户手指在屏幕划了半天界面毫无反馈会以为功能坏了。我在播放页顶部放了一个半透明的TextView手势滑动时实时显示“亮度 60%”“音量 40%”“快进 30秒”这样的文字提示松开手消失。别看这个功能小实际使用体验完全不一样。5. 实测踩坑记录网络限制、硬解兼容和后台播放5.1 网络视频放不出来的真正原因明文HTTP被拦做本地播放器不代表完全接触不到网络视频测试局域网NAS共享视频时翻车了。现象是视频源明明正确Media3没有报解码错误但播放器一直停在STATE_IDLE偶尔弹onPlayerError。后来用logcat过滤关键字看到了关键日志CLEARTEXT communication to 192.168.1.10 not permitted by network security policyAndroid 9之后默认禁止明文HTTP流量Android 11上限制更严格。解决办法是在AndroidManifest.xml里配置网络安全策略只对指定域名放开明文流量而不是全局放开application android:networkSecurityConfigxml/network_security_config /applicationres/xml/network_security_config.xml里这样写network-security-config domain-config cleartextTrafficPermittedtrue domain includeSubdomainstrue192.168.1.10/domain /domain-config /network-security-config生产环境千万别用android:usesCleartextTraffictrue全局放开这会带来不小的安全风险尤其是在一个要读取大量本地媒体文件的App上。如果你只是开发期自用临时开全局倒也行但心里要有数。5.2 硬解兼容性导致的无声、黑屏以及降级方案第二个坑更隐蔽。同一个MKV文件在Pixel设备上播放正常在一台国产手机上却只有声音没有画面。还有一个RMVB文件某台设备直接报解码错误。这类问题的根源在于MediaCodec硬解在不同芯片平台上实现差异很大同样的封装格式和编码格式高通的硬解没问题联发科可能就识别不了。解决方法分两种。第一种是设置DefaultRenderersFactory的setExtensionRendererMode为EXTENSION_RENDERER_MODE_PREFER让Media3优先使用扩展解码器失败时自动降级到软解。第二种是在设置页提供一个“软解模式”开关用户遇到播放异常时手动切换val renderersFactory if (softDecode) { DefaultRenderersFactory(context) .setExtensionRendererMode(DefaultRenderersFactory.EXTENSION_RENDERER_MODE_ON) } else { DefaultRenderersFactory(context) .setExtensionRendererMode(DefaultRenderersFactory.EXTENSION_RENDERER_MODE_PREFER) }需要说明的是Media3的软解能力如果只用media3-exoplayer基础包很多格式依然解不了要补上media3-decoder-ffmpeg扩展模块。这个扩展包会让APK体积增加十几MB但对本地播放器来说完全值得它能帮你应付绝大多数“官方不支持但用户确实有”的野视频格式。5.3 切后台被杀播放器“断片”第三个坑是我在开发后期才遇到的播放页面切到后台几分钟再回到App发现播放器状态变成了STATE_IDLE进度也丢了。第一次遇到时我还以为是播放器自动释放了后来看日志才发现是进程被系统回收了。进程被LMK回收后所有内存对象都会被销毁前台页面重建时自然拿不到原来的Player实例。真正解决问题的方案是前台服务把播放器放到一个MediaSessionService里托管并按Android 14的要求声明前台服务类型为mediaPlayback。核心代码大致是这样class PlaybackService : MediaSessionService() { override fun onCreate() { super.onCreate() player ExoPlayer.Builder(this).build() mediaSession MediaSession.Builder(this, player).build() } override fun onTaskRemoved(rootIntent: Intent?) { // 用户划掉任务时可以选择停止播放或继续后台播 } }服务启动时调用startForeground(id, notification, ServiceInfo.FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK)通知用MediaSession生成的媒体通知这样用户还能在通知栏直接控制播放暂停。这一套做完切后台播放彻底稳了。5.4 android/data目录访问崩溃的提醒最后提醒一个很常见的崩溃场景。市面上很多下载工具分享文件时给的Uri是content://...fileprovider/.../android/data/...这种结构指向另一个App的私有目录。你把这个Uri拿到自己的播放器里想读很可能直接FileNotFoundException因为授权范围是临时的、跨进程的而且Android 11对android/data目录的限制极其严格。我处理的方式是播放器在解析外部传入的Uri时不允许持久化到播放列表里只允许当次临时播放。只有通过MediaStore扫描到、或者用户主动用SAF选择并持久化授权过的Uri才纳入视频库。这样既避免了崩溃也防止了越权访问其他应用数据合规上更安心。6. 进阶玩法变速不变调、字幕加载和隔空手势控制6.1 变速播放不改变音调做过视频播放器的人都知道单纯把播放速度从1.0调到1.5很多播放器会把音调跟着提上去声音像小松鼠说话。ExoPlayer解决这个问题的办法是PlaybackParameters里有两个参数一个速度一个音调player.setPlaybackParameters(PlaybackParameters(speed, 1f))第二个参数设为1f就是“变速不变调”。如果你把两个参数设成一样的值等于速度音调同步变那就会听到小松鼠声音。倍速档位我是在设置页用Slider让用户从0.5倍到2.5倍自由拖动比固定几个档位更实用。6.2 字幕加载本地播放器总有要看外挂字幕的需求。Media3的MediaItem.Builder支持直接塞SubtitleConfigurationval subtitle SubtitleConfiguration.Builder(Uri.parse(file:///sdcard/movie.srt)) .setMimeType(application/x-subrip) .build() val mediaItem MediaItem.Builder() .setUri(videoUri) .setSubtitleConfigurations(listOf(subtitle)) .build()Media3对.srt和.vtt支持得比较好常见的.ass高级特效字幕支持有限如果主力字幕是ass建议找专门的字幕渲染方案。我只做了srt/vtt支持覆盖了朋友90%的使用场景剩下10%直接忽略。6.3 用MediaPipe做隔空手势控制最后说一个我很喜欢玩的进阶方向用MediaPipe的手势识别做一个简单的隔空控制挥手切歌、握拳暂停。整体思路是CameraX预览 MediaPipe Hand Landmarker 回调控制播放器。流程分三步用CameraX打开前置摄像头把每帧图像交给MediaPipe的Hand Landmarker模型模型返回手部21个关键点坐标我根据这些点判断手势五指全张是播放握拳是暂停食指上滑是音量加食指下滑是音量减识别到手势后通过回调调用播放器的play()、pause()、seekTo()等方法。这里要注意两个细节。第一前置摄像头画面是镜像的手势坐标需要做水平翻转否则左右方向反了用户会觉得没反应第二手势识别不是每帧都触发而是要做一个状态机同一个手势保持几帧才触发一次防止画面抖动手势来回切换导致播放器频繁暂停播放。我实测下来100毫秒去抖已经够用。如果感兴趣可以把这一块扩展成完整的“隔空控制模式”在播放页做一个悬浮按钮随时开关。平时用不到但在做饭、手里拿着东西时确实方便。做完这个项目最大的感受是视频播放器看起来是个被做烂了的小工具真要自己做一遍你会发现它把存储、多媒体、解码、系统服务、进程保活这些Android核心知识点全串起来了。我实际用下来最稳妥的组合就是Media3做内核、MediaStore加SAF读文件、前台服务管后台播放这三个大方向不出错基本就成功一大半。最后分享一个小技巧开发时在logcat里过滤关键字PlaybackException和CLEARTEXT很多播放问题第一时间就能看到真正原因不用一遍遍猜。希望这篇东西能帮到同样想自己做播放器的人踩过的坑我已经替你们趟平了。本文还有配套的精品资源点击获取