简介安卓Android源码——MusicPlayer音乐播放器源码.zip是一份面向安卓初学者的完整项目源码适合正在学习多媒体开发、界面搭建和核心组件用法的开发者。压缩包共36个文件以java源码、xml布局、class文件为主同时含apk安装包和源码说明文档便于直接运行与对照学习。整体仅126KB结构紧凑适合快速阅读和分析。目前已有776人学习下载。源码以MediaPlayer为核心完整演示了音乐的加载、播放、暂停、停止与进度跳转并展示如何在播放出错时捕获异常界面部分涉及LinearLayout等布局、按钮与进度条的动态更新以及歌曲列表的适配器实现。项目还引入Service实现在后台持续播放并通过前台服务在通知栏保持常驻提示帮助理解组件通信与生命周期管理。配合源码说明和界面截图读者可理清工程目录、主功能模块与关键类的调用关系为后续开发完善功能打下基础。1. 一份 MusicPlayer 源码包先分清能复用与需要重写的部分你从某个渠道拿到一个名为 “MusicPlayer音乐播放器源码.zip” 的压缩包解压后里面是一整套 Android 工程。这类源码在 GitHub、Gitee 和各类源码站上大量存在质量参差但共同点是它把音乐播放器最核心的组件——MediaPlayer 封装、MediaStore 扫描、播放列表 UI、通知栏控制——都摆在面前。对 Android 开发者和想转行的工程师来说这份源码的价值不在“能跑起来”而在能快速定位每一层职责数据层怎么读取本地音频播放层怎么管理状态UI 层怎么避免卡顿。适合刚开始接触 Android 多媒体开发的初级工程师也适合需要把本地播放能力嵌入现有 App 的中级开发者。即便代码写得不完美拆开看一遍比只看官方文档更能理解生命周期和回调的实际串法。2. 把 MusicPlayer 源码导入 Android Studio环境对齐与首个构建2.1 环境对齐Android SDK、Gradle 插件与 JDK 的匹配拿到 zip 后第一步不是急着打开源码而是先看工程配置文件。一个标准的 Android 工程根目录下一定有 settings.gradle、build.gradle 和 gradle/wrapper/gradle-wrapper.properties 三个关键文件。gradle-wrapper.properties 里的 distributionUrl 写明了 Gradle 版本根 build.gradle 里的 com.android.tools.build:gradle 写明 Android Gradle PluginAGP版本而这两个版本又决定了本机需要哪个 JDK。常见的误操作是直接用 Android Studio 默认 JDK 打开老工程结果构建报 Unsupported class file major version 或 Failed to apply plugin。GradleAGP 大致范围JDK 要求6.x4.0 左右JDK 8/117.x7.0 及以上JDK 118.x8.0 及以上JDK 17提示这份对照关系以 gradle-wrapper.properties 实际声明的版本为准不要盲信工程 README 里写的环境要求。导入时直接使用 Android Studio 的 Open 功能选择解压目录让 IDE 根据 gradle wrapper 自动下载对应版本。首次构建最耗时的部分就是下载依赖可以先确认本机网络对 maven 仓库的连通性或配置镜像仓库。如果本机 JDK 版本与 Gradle 不匹配在 File Project Structure 里切换 SDK Location 和 JDK。实际构建也可以在命令行完成便于看到完整日志cd MusicPlayer ./gradlew assembleDebug --consoleplainassembleDebug 会产出 debug 签名的 APK路径一般在 app/build/outputs/apk/debug/ 下。如果工程包含多个模块可以写成./gradlew :app:assembleDebug指定模块。--consoleplain让日志不再有花哨的进度条方便在 CI 或终端里直接 grep 错误关键字。提示构建失败时优先看第一条 ERROR不要抓最后一大段堆栈。常见原因按出现频率排依赖下载超时、AGP 与 Gradle 版本不匹配、compileSdk 版本本地未安装。2.2 解包后的目录结构播放核心在哪个包解压后典型的 app/src/main 目录包含 java或 kotlin、res、AndroidManifest.xml。java 目录下按包名分几块通常能看到 activity、adapter、service、utils 等子包。判断一份 MusicPlayer 源码质量先看 service 包有没有内容有 MediaPlayService 或类似命名的说明作者考虑了后台播放只有一个 MainActivity 包揽所有逻辑那多半是教学演示代码真机息屏后播放就会断。AndroidManifest.xml 里需要重点检查四个权限和两个声明。四个权限分别是 READ_MEDIA_AUDIOAndroid 13及以上、READ_EXTERNAL_STORAGEAndroid 12及以下、WAKE_LOCK防止休眠时 CPU 睡死导致播放卡顿、FOREGROUND_SERVICE前台服务声明。老源码常见问题是没有按 Android 13 的新权限模型适配只写了 READ_EXTERNAL_STORAGE那在高版本系统上扫描结果会是空的。uses-permission android:nameandroid.permission.READ_MEDIA_AUDIO/ uses-permission android:nameandroid.permission.READ_EXTERNAL_STORAGE android:maxSdkVersion32/ uses-permission android:nameandroid.permission.FOREGROUND_SERVICE/ uses-permission android:nameandroid.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK/maxSdkVersion 告诉系统这个权限只在 API 32 及以下使用避免高版本系统弹出冗余授权提示。FOREGROUND_SERVICE_MEDIA_PLAYBACK 是 Android 14 引入的前台服务类型声明不加这个权限启动前台服务时会抛 MissingForegroundServiceTypeException 或直接崩溃。2.3 导入报错的三个高频修复点先说第一个本机 JDK 版本远高于工程声明的 Gradle 版本。报错信息一般是Unsupported Java. Your build is currently configured to use Java 17 and Gradle 6.8。修复方式不是马上换 JDK而是打开 gradle-wrapper.properties把 distributionUrl 里的 Gradle 版本升到与 AGP 配套的版本再同步根 build.gradle 里的 AGP 版本号。第二个依赖仓库失效。老工程常见 jcenter() 或maven { url http://... }这类写法。jcenter 已经停止服务需要把 repositories 改成 mavenCentral() 和 google()。注意 http 明文仓库在 AGP 8 以上会直接被拒绝必须改成 https。第三个compileSdk 高于本机已安装的 SDK。Android Studio 会弹窗提示 Install missing SDK点掉即可命令行构建时报Failed to find target with hash string android-33用 sdkmanager 装对应版本sdkmanager platforms;android-33 build-tools;33.0.1装完后重新构建。这三个问题几乎覆盖老 MusicPlayer 源码导入时八成以上的报错场景剩下的多是依赖传递冲突在 dependencies 里统一加 exclude 即可。3. MusicPlayer 播放核心MediaPlayer 封装、状态机与音频焦点3.1 MediaPlayer 状态机为什么源码里到处是 setDataSourceMediaPlayer 是系统提供的本地播放实现它的生命周期不是简单的 play/stop而是一张严格的状态表。每次调用方法都相当于状态转移new 出来是 Idle 态setDataSource 后进入 Initialized 态prepareAsync 后进入 Preparingprepared 回调后是 Prepared 态start 进入 Startedpause 回到 Pausedstop 进 Stoppedrelease 之后任何调用都会抛异常。很多 MusicPlayer 源码里崩溃都源于在错误状态调用了方法比如 stop 之后想再 start 却没有重新 prepare。状态进入方式可调用的方法Idlenew MediaPlayer()setDataSourceInitializedsetDataSource 完成prepare / prepareAsyncPreparedprepare 完成或 onPrepared 回调start / seekToStartedstart 调用pause / seekTo / stopPausedpause 调用start / seekTo / stopStoppedstop 调用start重新进入 Started/ releasepublic class PlayerWrapper { private MediaPlayer mp; private String currentPath; public void play(String path) { if (mp ! null) { mp.release(); // 释放旧实例避免状态残留 } mp new MediaPlayer(); try { mp.setDataSource(path); // 本地路径或 content:// URI mp.prepare(); // 同步准备仅适合本地小文件 mp.start(); currentPath path; } catch (IOException e) { e.printStackTrace(); } } public void pause() { if (mp ! null mp.isPlaying()) { mp.pause(); } } public void seekTo(int progress) { if (mp ! null) { mp.seekTo(progress); // 单位毫秒 } } }这是多数简易 MusicPlayer 的原始形态。setDataSource 支持文件路径、content:// URI 和网络 URL 三种形式本地音乐用绝对路径最省事。prepare 是同步阻塞版本本地小文件无感但网络流必须用 prepareAsync 配合 OnPreparedListener否则主线程卡顿会被系统判定 ANR。release 之后再 new 一个实例比复用同一个 MediaPlayer 走 reset 路径稳妥得多少踩状态残留的坑。代码中每个调用的顺序本身就是状态机。实际工程里需要封装一个回调接口把 onCompletion、onError、onPrepared 暴露给 UI 层。onError 返回 true 表示已处理错误系统不会继续抛异常返回 false 会让播放器进入 Error 状态后续调用全部无效。3.2 音频焦点不申请 AudioFocus 的播放器会被语音助手打断只写 MediaPlayer 的源码放真机上有一个明显问题正听着歌微信语音通话一来音乐停了但播放按钮还显示在播放。这是音频焦点机制在起作用——多个应用同时出声会互相抢占。一个合格的音乐播放器必须在播放前请求焦点、暂停时释放焦点、被其他应用抢走时做出响应。AudioManager am (AudioManager) getSystemService(AUDIO_SERVICE); AudioAttributes attrs new AudioAttributes.Builder() .setUsage(AudioAttributes.USAGE_MEDIA) .setContentType(AudioAttributes.CONTENT_TYPE_MUSIC) .build(); AudioFocusRequest focusRequest new AudioFocusRequest.Builder(AudioManager.AUDIOFOCUS_GAIN) .setAudioAttributes(attrs) .setOnAudioFocusChangeListener(focusChange - { switch (focusChange) { case AudioManager.AUDIOFOCUS_LOSS: pausePlayback(); // 焦点被永久抢占必须暂停 break; case AudioManager.AUDIOFOCUS_LOSS_TRANSIENT: pausePlayback(); // 临时丢失如语音助手介入 break; case AudioManager.AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK: setVolume(0.3f); // 降低音量适合通知提示场景 break; case AudioManager.AUDIOFOCUS_GAIN: resumePlayback(); setVolume(1.0f); // 恢复音量 break; } }); int result am.requestAudioFocus(focusRequest); if (result AudioManager.AUDIOFOCUS_REQUEST_GRANTED) { startPlayback(); }AudioFocusRequest 是 Android 8.0 起的推荐写法旧源码里用 requestAudioFocus 加 listener 的废弃版本也能跑但编译会有 deprecation 警告。AUDIOFOCUS_GAIN 表示长期占据焦点适合音乐播放器AUDIOFOCUS_GAIN_TRANSIENT 适合铃声或短视频这种短时播放。LOSS 意味着焦点彻底被抢走比如另一个音乐 App 开始播放LOSS_TRANSIENT 是临时情况CAN_DUCK 是最友好的信号只要把音量降下去就好微信通知提示音就属于这一类。暂停还是降音量直接决定用户体验也是这份源码改造里性价比最高的一处。3.3 参数调优缓冲、解码格式与低延迟的取舍MediaPlayer 除了 setAudioStreamType 这类被 AudioAttributes 取代的接口外真正能调的参数不多。网络流播放时可以设置 setOnBufferingUpdateListener 拿当前缓冲百分比用于 UI 显示加载状态。本地音乐文件没有缓冲概念首次 seekTo 的延迟主要来自解码器启动无法主动预热。如果要更细的控制源码里通常会把 MediaPlayer 替换成 ExoPlayer。ExoPlayer 的优势在模块化LoadControl 控制缓冲水位TrackSelector 选择音轨Renderer 负责解码。常用配置是在 DefaultLoadControl.Builder 里设置 minBufferMs 和 maxBufferMs。常见错误是低端机把 maxBuffer 调得过大导致 OOM以及移动网络和 wifi 用同一套缓冲策略浪费流量。建议至少区分网络类型移动网络下把缓冲窗口压到 15 秒以内wifi 下可以放宽到 60 秒。提示MediaPlayer 对 FLAC、APE 等无损格式的支持在不同系统版本上不一致。如果用法侧重本地高码率音频直接考虑用 ExoPlayer 重构播放内核省去逐版本适配的麻烦。音频焦点和播放状态是音乐播放器的骨架。Demo 源码里往往这两部分写得最薄因为演示逻辑只关注“能响”。要把 demo 变成可用的播放器第一步就是把焦点逻辑补上第二步是把 onError 里无提示崩溃改成友好的 Toast 和状态回退。4. MusicPlayer 的数据与界面MediaStore 扫描、列表加载与进度刷新4.1 MediaStore 查询参数扫描不到歌单先从权限和 URI 查MusicPlayer 源码的数据层基本都围绕 MediaStore.Audio.Media 展开这是一个由 MediaProvider 维护的媒体数据库应用通过 ContentResolver 查询。老代码里常见的写法是查询 EXTERNAL_CONTENT_URI 后遍历 CursorAndroid 10 起分区存储后这个方法依然有效只是获取文件路径的限制更多需要精确到某个音频的 DATA 列时要注意权限边界。fun queryAudio(context: Context): ListAudioItem { val uri MediaStore.Audio.Media.EXTERNAL_CONTENT_URI val projection arrayOf( MediaStore.Audio.Media._ID, MediaStore.Audio.Media.TITLE, MediaStore.Audio.Media.ARTIST, MediaStore.Audio.Media.ALBUM_ID, MediaStore.Audio.Media.DURATION, MediaStore.Audio.Media.DATA ) val selection ${MediaStore.Audio.Media.IS_MUSIC} ! 0 // 过滤通知音和语音片段 val sortOrder ${MediaStore.Audio.Media.TITLE} ASC val cursor context.contentResolver.query(uri, projection, selection, null, sortOrder) val list mutableListOfAudioItem() cursor?.use { c - val idCol c.getColumnIndexOrThrow(MediaStore.Audio.Media._ID) val titleCol c.getColumnIndexOrThrow(MediaStore.Audio.Media.TITLE) val artistCol c.getColumnIndexOrThrow(MediaStore.Audio.Media.ARTIST) val durationCol c.getColumnIndexOrThrow(MediaStore.Audio.Media.DURATION) val dataCol c.getColumnIndexOrThrow(MediaStore.Audio.Media.DATA) while (c.moveToNext()) { list.add(AudioItem( id c.getLong(idCol), title c.getString(titleCol), artist c.getString(artistCol), duration c.getLong(durationCol), path c.getString(dataCol) )) } } return list }selection 里的 IS_MUSIC ! 0 用来过滤掉铃声和录音片段。DURATION 的单位是毫秒UI 转 m:ss 时记得除以 1000。query 是耗时操作必须放到子线程Kotlin 里用 Dispatchers.IO 包一层Java 里用 ExecutorService。本地歌曲几千首时主线程直接 query 会触发 StrictMode 提示甚至卡到掉帧。cursor?.use 确保 Cursor 被关闭避免句柄泄漏。权限适配对应关系也要写清楚。Android 13 以上请求 READ_MEDIA_AUDIO以下请求 READ_EXTERNAL_STORAGEif (Build.VERSION.SDK_INT 33) { requestPermissions(new String[]{Manifest.permission.READ_MEDIA_AUDIO}, 100); } else { requestPermissions(new String[]{Manifest.permission.READ_EXTERNAL_STORAGE}, 100); }写反的表现是低版本弹的是存储权限没问题高版本只弹了照片权限音频扫描结果永远是空。老源码里十有八九漏了版本判断这是扫描不到歌单的第一排查点。4.2 RecyclerView 列表与播放高亮Adapter 更新的正确姿势扫描出来的列表数据通过 RecyclerView 展示负责这块的是 AudioAdapter。一个常见的问题是点击列表项后高亮状态不刷新或者更新数据后直接调用 notifyDataSetChanged 导致整个列表闪烁重绘。正确的做法是把“当前播放项”作为 Adapter 的状态点击时只通知变化的两个位置。public class AudioAdapter extends RecyclerView.AdapterAudioAdapter.VH { private ListAudioItem items; private int currentPosition -1; public void setCurrentPosition(int pos) { int oldPos currentPosition; currentPosition pos; notifyItemChanged(oldPos); // 重绘上一项 notifyItemChanged(pos); // 重绘当前项 } Override public void onBindViewHolder(VH holder, int position) { AudioItem item items.get(position); holder.title.setText(item.title); holder.duration.setText(formatDuration(item.duration)); holder.itemView.setActivated(position currentPosition); holder.itemView.setOnClickListener(v - { if (listener ! null) listener.onItemClick(position); }); } }notifyItemChanged 只重绘两个位置代价远小于全量刷新。setActivated(true) 配合 selector drawable 就能实现高亮背景不需要额外维护一个 View 引用。这里有个隐藏坑RecyclerView 滚动时 ViewHolder 复用如果 onBindViewHolder 里不判断 position currentPosition快速滑动后高亮会错位到别的行。把 source 改造成自己的播放器时这一处是必查项。4.3 进度条刷新Handler、协程与回调解耦播放进度条的刷新是音乐播放器 UI 里最容易出 bug 的部分。简易源码常用的模式是 Handler 加 Runnable 每秒发一次消息拿 MediaPlayer 的 currentPosition 去 setProgress。这个写法本身没问题但有两个坑一是 Handler 要记得 removeCallbacks否则 Activity 进入后台后还在刷新进度条一直在跳二是每次 setProgress 会触发 onProgressChanged 回调如果回调里做了耗时操作消息会堆积导致进度条一顿一顿的。private final Handler handler new Handler(Looper.getMainLooper()); private final Runnable progressRunnable new Runnable() { Override public void run() { if (mp ! null mp.isPlaying()) { int pos mp.getCurrentPosition(); seekBar.setProgress(pos); handler.postDelayed(this, 500); } } }; Override protected void onPause() { super.onPause(); handler.removeCallbacks(progressRunnable); } Override protected void onResume() { super.onResume(); handler.post(progressRunnable); }postDelayed 500 毫秒意味着每秒刷新两次视觉上已经流畅。设为 1000 会有轻微卡顿感设为 100 则白白耗电。onPause 里 removeCallbacks、onResume 里重新 post保证页面不可见时不干活。关键点是回调解耦seekBar 的 onProgressChanged 里不要再做 I/O只做 UI 位移真正 seek 的动作放在 onStopTrackingTouch 里触发避免拖动过程中反复创建 MediaPlayer 的 seekTo 请求。用协程可以写得更简洁且不泄漏lifecycleScope.launch { while (isActive) { seekBar.progress mp?.currentPosition ?: 0 delay(500) } }这个循环在 Activity 销毁时会被 lifecycleScope 自动取消省去手动 removeCallbacks。老源码如果是 Java 写的Handler 方案已经够用不值得为了换写法而换。5. 把 MusicPlayer 源码变成自己的三个值得改写的进阶点5.1 用 Service 承载播放Activity 退出不再是音乐停止的借口简易 MusicPlayer 源码最大的架构缺陷是播放逻辑写在 Activity 里一退界面声音就断。改造方向是新建 MediaPlayService把 PlayerWrapper 迁进去Activity 通过 bindService 拿到 Binder 引用调用 play、pause、seek 方法。Service 在 manifest 里声明时加上 foregroundServiceTypemediaPlayback配合 Android 14 的前台服务类型要求。播放过程中调用 startForeground 变成前台服务系统就不太会因为内存压力直接杀掉后台进程。5.2 通知栏媒体控制MediaStyle 与 MediaSessionCompat接上 Service 后通知栏控制是体验分水岭。通过 MediaSessionCompat 向系统注册播放状态通知栏用 MediaStyle 展示上一首、播放暂停、下一首三个按钮Android Auto 和手表也能统一响应。一条核心经验setSmallIcon 必须用纯 alpha 的白色图标彩色图标在系统栏会显示成一团黑。多数改造翻车在现场播报onPlay、onPause、onSkipToNext 三个回调没有在 Service 里正确转发到 PlayerWrapper点击通知按钮毫无反应。MediaSession 的 PlaybackState 也要同步更新否则桌面小组件和蓝牙耳机的按键状态是错的。5.3 用 adb 验证播放状态与日志定位崩溃改造后验证是否真正生效不需要反复按真机按钮。一组实用的 adb 命令adb shell dumpsys media_session adb shell dumpsys audio | grep -A 20 Audio focus adb logcat -s MediaPlayer MusicPlayerService AndroidRuntimedumpsys media_session 能看到当前 MediaSession 的状态、播放位置和元数据用来判断通知栏与控制端的同步是否正常。grep Audio focus 段落能看到当前谁持有了音频焦点焦点被抢时立刻能看出是哪个包名拿走的。logcat 加 -s 标签过滤只保留媒体相关输出崩溃堆栈在 AndroidRuntime 标签下定位。这三条命令组合起来基本能把播放器状态机、焦点和生命周期问题在十分钟内定位完毕。提示真机调试时打开开发者选项里的“不保留活动”可以快速模拟后台被杀场景验证 Service 的存活策略。adb shell settings put global always_finish_activities 1测试完后记得关闭adb shell settings put global always_finish_activities 0。这组验证手法比单纯跑一遍 UI 测试更能暴露源码架构层面的问题也适合接入 CI 的冒烟环节。本文还有配套的精品资源点击获取