企业官网建设流程全解析

先问个问题：你在用MediaPlayer播放的时候，有没有冒出过这些念头——“new MediaPlayer()到底干了多少事？”“为什么setDataSource之后必须prepareAsync，不能直接start？”“onPrepared回调是怎么从底层一层层传上来的？”

如果你只是调用API，这些疑问完全不影响出活，但一旦碰到诡异问题，比如某些格式能播某些不能播、某些设备黑屏但log又没报错、某些机型prepare特别慢，不了解初始化这条链路，排查起来基本靠猜。

这篇是MediaPlayer整体架构源码分析的第一篇，聚焦“初始化和创建”这个核心阶段。我会从Java层构造函数的调用开始，一路追到JNI绑定、Native侧对象创建、数据源探测、播放器后端选择，再到prepare状态机的完整流转。适合想深入Framework层、准备啃源码，或者正在被MediaPlayer初始化问题折磨的开发者。

1. 三层架构：MediaPlayer不是一道墙，是一条流水线

拿到MediaPlayer源码，第一件事不是一头扎进某个文件，而是先把整个调用框架理顺。很多初读源码的人卡住，是因为在Java层找不到真正的实现逻辑，然后开始怀疑自己找错了版本。

MediaPlayer的整体架构是典型的三层结构：Java层、JNI层、Native层。用流水线来理解更准确：Java层是面向开发者的操作面板，JNI层是传送带，Native层才是真正干活的车间。

Java层的核心类是android.media.MediaPlayer，我们平时调的setDataSource()、prepareAsync()、start()，本质上都是在给底层发指令。这个类自己不做任何播放相关的工作，它的主要职责一是暴露API给应用，二是维护一个状态机来约束调用顺序，三是在应用和Native层之间传递回调事件。

JNI层对应frameworks/base/media/jni/android_media_MediaPlayer.cpp，它负责Java和C++之间的桥接。JNI层里做的事看起来琐碎，但每一件都关系到上下两层能不能好好配合：把Java传下来的字符串转换成C++能处理的类型、把Native层产生的事件转发回Java层、管理Native对象的生命周期。

Native层的核心是个sp<MediaPlayer>，定义在frameworks/av/media/libmedia/mediaplayer.cpp，它继承自BnMediaPlayerClient，是真正连接底层播放引擎的入口。在更底层，还有NuPlayerDriver、GenericSource、HTTPLiveSource等一系列组件，它们负责实际的解码、同步和渲染。

用一张表把各层的核心文件理清楚：

这条流水线的启动顺序也很明确：构造Java对象的时候，通过JNI创建Native对象；调用setDataSource的时候，在Native层进行数据源格式化并选择播放后端；调用prepareAsync的时候，真正把播放引擎拉起来干活。

明白这层关系之后再往下追源码，每个文件里函数的职责边界就清晰了。

2. Java层构造函数的四个关键动作

MediaPlayer的构造函数在很多人眼里就是一个空壳——new MediaPlayer()嘛，不就是new了个对象。实际上它做了四件事，每一件都对后面的行为产生影响。

看AOSP里MediaPlayer.java的构造函数，核心逻辑是这样的（以常见AOSP版本为例，细节版本间略有差异）：

public MediaPlayer() { Looper looper; if ((looper = Looper.myLooper()) != null) { mEventHandler = new EventHandler(this, looper); } else if ((looper = Looper.getMainLooper()) != null) { mEventHandler = new EventHandler(this, looper); } else { mEventHandler = null; } mTimeProvider = new TimeProvider(this); mOnSubtitleUpdateListener = null; native_setup(new MediaPlayerListener(this)); }

第一件事是创建EventHandler。仔细看这个逻辑，它优先拿当前线程的Looper，拿不到就拿主线程的Looper。这个设计有什么讲究？因为MediaPlayer底层向Java层投递回调事件，默认是往创建它的那个线程Looper里post消息，如果你在子线程创建MediaPlayer，回调就会在子线程执行；如果子线程没有Looper，就退回到主线程。

这样设计是为了保证一件事：只要创建MediaPlayer的线程有Looper，回调就一定在一个稳定的事件循环里执行，不会出现回调线程忽上忽下、开发者在回调里更新UI还要自己切线程的问题。当然，这也意味着如果你在子线程里创建了MediaPlayer，而子线程Looper一直不退出，回调会一直往那条线程pending，这个坑后面排查时经常会遇到。

第二件事是创建TimeProvider。TimeProvider这个组件很多开发者不熟悉，它负责为MediaPlayer提供统一的时钟源，尤其是做同步字幕、同步外部音轨时，需要从它这里拿播放时间。在初始化和创建阶段，它就是new了一个对象出来，不需要深入，但你得知道它存在，否则后面看mTimeProvider.getTimestamp()会一头雾水。

第三件事，也是整个创建阶段最核心的，就是调用native_setup(new MediaPlayerListener(this))。这个native_setup是native方法，它在Native层创建真正的播放器对象，同时把Java层的listener传下去，让底层可以回调Java层的事件。这个调用之后，Java对象和Native对象才算建立了一一对应的关系。

第四件事容易被忽略：AudioSystem相关的会话注册。在部分AOSP版本里，构造函数还会调用AudioSystem.newAudioSessionId()生成一个AudioSessionId，并通过native_setAudioSessionId()传给底层，这个ID用于音频焦点管理、音量调节和音频效果（比如均衡器）的绑定。你创建MediaPlayer的时候可能根本没想到音频系统已经给它分配了一个独立的会话ID，这是它的身份标识。

这四件事做完，Java层的工作才告一段落。注意构造函数本身并不加载任何媒体数据，也不做任何格式探测，真正的重头戏在setDataSource阶段才开始。

3. JNI绑定：从native_setup到NativePlayerGlue

native_setup在Java层的声明是这样的：

private native void native_setup(Object mediaplayer_this);

这个Object参数实际上是MediaPlayerListener对象。JNI层对应实现是android_media_MediaPlayer_native_setup，在frameworks/base/media/jni/android_media_MediaPlayer.cpp里。

看这个函数的实现（简化版）：

static void android_media_MediaPlayer_native_setup(JNIEnv *env, jobject thiz, jobject weak_this) { sp<MediaPlayer> mp = new MediaPlayer(); if (mp == NULL) { jniThrowException(env, "java/lang/IllegalStateException", "Out of memory"); return; } // 创建NativePlayerGlue sp<NativePlayerGlue> glue = sp<NativePlayerGlue>::make(env, thiz, mp); mp->setNotifyCallback(glue); // 把Native对象的地址保存到Java对象的一个long字段里 setMediaPlayer(env, thiz, mp); }

这里有一个非常重要的中间层：NativePlayerGlue。很多网上的源码分析会跳过它，但它在现代AOSP版本里承担了相当多的工作——它不再纯粹是一个事件转发器，还代管了数据源设置、参数校验、Native回调等事务。理解它的存在，比单纯记函数名更有价值。

NativePlayerGlue的核心职责有两个：

第一，作为Native层MediaPlayer的事件回调目标。mp->setNotifyCallback(glue)这句代码把glue挂到了MediaPlayer上，当Native层产生播放状态变化、错误、缓冲进度更新时，都会回调glue的notify()方法。glue收到回调后，会检查事件的类型，然后通过JNI调用Java层的postEventFromNative()方法，把事件投递到Java层的事件队列里。

第二，管理Java层对象引用。Native层不能直接持有Java对象引用，否则可能导致GC无法回收，所以glue内部保存的是Java对象的弱引用（weak_this），每次需要回调Java层时再通过弱引用获取对象，用完就释放。这个细节直接关系到内存泄漏问题——如果你观察Native内存里MediaPlayer对象迟迟不释放，可以先怀疑弱引用环节出了问题。

看一段glue处理Native回调的核心逻辑：

void NativePlayerGlue::notify(int msg, int ext1, int ext2, const Parcel *obj) { sp<JMediaPlayerListener> listener = mListener; if (listener == nullptr) { return; } switch (msg) { case MEDIA_PREPARED: listener->notify(MEDIA_PREPARED, ext1, ext2, obj); break; case MEDIA_PLAYBACK_COMPLETE: listener->notify(MEDIA_PLAYBACK_COMPLETE, ext1, ext2, obj); break; case MEDIA_ERROR: listener->notify(MEDIA_ERROR, ext1, ext2, obj); break; // ... 其他事件 } }

事件从Native层到Java层的传递路径完整走一遍是：

1. Native MediaPlayer解析完数据源，调mNotify->notify(MEDIA_PREPARED, ...)
2. NativePlayerGlue的notify()被调用
3. glue通过JMediaPlayerListener调Java层的postEventFromNative()
4. Java层的postEventFromNative()把MEDIA_PREPARED封装成一个Message，发到EventHandler
5. EventHandler.handleMessage()里分发各种回调，比如MEDIA_PREPARED就调mOnPreparedListener.onPrepared(mp)，也就是我们熟悉的onPrepared

值得注意的是，JNI层在构造MediaPlayer时，还会顺带处理AudioSessionId和scoped pixel format等参数，这在后续版本迭代里有不少调整，但主线逻辑没有变。

4. Native层对象创建和数据源探测：整个初始化的真正起点

Java层和JNI层的准备工作做完之后，Native层才开始真正忙碌起来。理解Native层mediaplayer.cpp的工作，是理解MediaPlayer初始化的关键分水岭。

4.1 Native MediaPlayer构造函数的状态设置

看mediaplayer.cpp的构造函数：

MediaPlayer::MediaPlayer() { ALOGD("MediaPlayer constructor"); mCurrentState = MEDIA_PLAYER_IDLE; // ... }

这里最核心的是把初始状态设置为MEDIA_PLAYER_IDLE。处于IDLE状态的MediaPlayer，在调用setDataSource之前几乎什么都做不了。这个状态管理不是摆设，它为后续所有调用合法性检查提供了依据。

很多人调用MediaPlayer报IllegalStateException，就是因为状态机判断不通过。比如在IDLE状态下直接调prepareAsync()，Java层的状态机检查直接抛异常；再比如做完prepareAsync()还没等onPrepared回调就去start()，也会失败。状态机是整个MediaPlayer初始化的隐形骨架。

4.2 setDataSource的多个重载如何归一化

Java层提供了多个setDataSource重载，有的是传文件路径字符串，有的是传FileDescriptor，有的是传Context和Uri。不管哪种入口，最终在JNI层都会被归一化。

字符串路径版本最简单，JNI层会做file://的剥离，然后调用Native层的setDataSource(const char *path)。FD版本需要先dup一份文件描述符再传给Native层，因为MediaPlayer是异步播放的——你传入的fd可能在你play之前就被业务代码关了，所以必须先复制一份保证生命周期安全。

Context+Uri版本最终会通过ContentResolver打开一个FD或者把Uri转成文件路径，再走上面的通道。这一层归一化操作，给上层调用提供了极大的灵活性，但也导致一个问题：你调试时很难知道底层到底用的是哪条路径。实际排查时可以通过log确认。

4.3 MediaPlayerFactory：谁来决定用哪个播放后端？

这是整个初始化阶段技术含量最高的一环。很多开发者不知道，MediaPlayer的Native层并不是一个只能播放固定格式的死板引擎，它通过一个MediaPlayerFactory机制来选择到底用哪个播放器后端来干活。

看mediaplayer.cpp中setDataSource的关键路径：

status_t MediaPlayer::setDataSource(int fd, int64_t offset, int64_t length) { // ... player_type = MediaPlayerFactory::getPlayerType(this, fd, offset, length); if (player_type == StagefrightPlayerFactory::PLAYER_TYPE_NONE) { ALOGE("No player type found for data source"); return UNKNOWN_ERROR; } mPlayer = MediaPlayerFactory::createPlayer(player_type, this, notify); // ... }

这里有两个关键方法：getPlayerType和createPlayer。getPlayerType的作用是探测数据源格式，然后给所有已注册的播放器厂商打分，得分最高的获胜。

老版本里还有StagefrightPlayer作为后端，后来基本都统一到了NuPlayer。看到NuPlayer的时候，大部分工作其实已经不在MediaPlayer这个类里了，而是转移到了NuPlayer的NuPlayerDriver上。NuPlayerDriver再往下，还要根据数据源类型创建GenericSource、HTTPLiveSource、RTSPSource等具体Source，这一步真正决定了后面的解码和播放行为。

这里有一个很重要的特点：数据源探测发生在setDataSource阶段，而不是prepare阶段。很多人以为prepareAsync才开始加载数据，其实从setDataSource调用开始，底层的格式探测已经跑起来了，只是这一步比较轻量，不会阻塞太久。

4.4 prepareAsync：把状态从INITIALIZED推向PREPARING

setDataSource完成之后，MediaPlayer的状态从IDLE变成INITIALIZED，但播放引擎还没有真正准备就绪。接下来必须调prepareAsync()或者prepare()。

看mediaplayer.cpp中prepare的路径：

status_t MediaPlayer::prepareAsync() { // 状态检查 if (mCurrentState != MEDIA_PLAYER_INITIALIZED) { ALOGE("prepareAsync called in state %d", mCurrentState); return INVALID_OPERATION; } if (mPlayer != NULL) { mCurrentState = MEDIA_PLAYER_PREPARING; return mPlayer->prepareAsync(); } return INVALID_OPERATION; }

状态从INITIALIZED变成PREPARING之后，真正的引擎就启动了。mPlayer->prepareAsync()对应到NuPlayerDriver，它会开始做数据源解析、提取音视频轨道信息、选择解码器（硬解还是软解）、创建解码器、准备渲染管线等一连串工作。

这串工作全部完成之后，NuPlayerDriver回调“prepared”状态，mediaplayer.cpp收到MEDIA_PREPARED事件，状态切到PREPARED，然后通过之前说的glue链路把事件投递到Java层，最终触发onPrepared回调。

这里有几个关键时间点值得注意：

1. prepareAsync内部的工作量是巨大的，尤其对于网络流媒体，耗时可能达到秒级
2. 在prepare过程中，MediaPlayer的状态是PREPARING，此时调用start()会抛异常
3. 如果prepare失败，状态会切到ERROR，需要通过OnErrorListener接收MEDIA_ERROR事件

5. 状态机：创建阶段最容易踩的规则

MediaPlayer整个生命周期可以看作一张状态迁移图，而创建阶段是最容易发生状态违规的区域。很多开发者的一个直接感受是：我的代码明明按顺序写了setDataSource、prepareAsync、start，为什么还报错？

原因往往不在调用顺序本身，而在状态机的细节约束上。几个常见场景：

第一个是setDataSource被调用两次。第一次setDataSource成功后，状态从IDLE变成INITIALIZED；同一MediaPlayer对象如果再次setDataSource，就会触发异常。但很多人没有意识到，prepare()之后还能不能再次setDataSource？答案是状态在PREPARED之后，setDataSource规则跟INITIALIZED状态时又不一样，需要先reset()回到IDLE状态。

第二个是prepare和prepareAsync不能混用。如果调了prepareAsync()，在onPrepared回调之前再调prepare()，状态检查会直接拒绝。反过来，如果调了阻塞的prepare()，期间状态是PREPARING，此时做任何非法的状态迁移都会抛IllegalStateException。

第三个是onPrepared回调里做耗时操作。有些开发者喜欢在onPrepared里去加载封面图、初始化字幕接口，做一堆耗时工作。这会让当前线程（往往是主线程）卡住，而播放引擎可能已经进入了PREPARED状态，后续的音频数据缓冲逻辑、视频渲染时间基准计算会受到影响。我在线上遇到过一个问题：在onPrepared里同步做了几百毫秒的耗时操作，导致首帧渲染时间被拉长到几秒，用户直接点了返回。后来把耗时操作挪出去，问题立刻消失。

下面整理一张创建阶段的状态迁移表，包含各个状态下的合法调用：

这个表是排查问题的第一工具。任何“奇怪”的IllegalStateException，回到这张表里对照一遍，十有八九能找到答案。

6. 初始化阶段的常见坑与排查手段

源码读完了，最后聊一聊实际开发中遇到的一些典型问题。这一部分是真金白银踩出来的经验，比源码本身更贴近日常开发。

6.1 回调线程问题

前面提到，MediaPlayer的回调默认投递到创建它的线程Looper上。如果你在子线程创建MediaPlayer且该子线程没有Looper，回调会落到主线程；但如果子线程自带Looper且长期存活（比如某些网络库线程），回调就会一直走子线程。

这个设计的隐患在onPrepared里更新UI时特别明显——你以为回调在主线程，结果在子线程直接操作了View，崩溃就会莫名其妙。解决思路有两个：一是利用构造函数里的Handler机制，但MediaPlayer没有公开这个入口；二是在onPrepared回调里主动切回主线程，不要假设回调线程。

6.2 setDataSource 卡住或迟迟不返回

setDataSource阶段做了格式探测，这里如果数据源是网络流且网络不稳定，阻塞的时间就会拉长。我排查过一个“设置数据源卡了8秒”的问题，最后发现原因是传入了一个需要重定向的URL，而HTTPClient在重定向时走了慢链路。

遇到setDataSource迟迟不返回的情况，优先检查是不是网络问题；其次要注意版本差异，新版AOSP中setDataSource的探测逻辑比老版本重了不少，不要用旧版经验直接套新版。

6.3 prepareAsync后没有onPrepared回调

这个问题的原因五花八门，最常见的几类：

1. 数据源不支持，比如传入了空文件、损坏的MP4或加密的TS流，底层prepare失败但没有上层监听的ErrorListener，回调就“消失”了
2. 权限问题，比如data分区读取权限没给，FD能打开但糊了
3. EventHandler的问题，前面说过的Looper问题在prepare失败时同样会发生

排查手段通常是两步走：先看logcat，过滤MediaPlayer、NuPlayer、GenericSource这几个tag，通常能直接看到错误原因；再看上层代码有没有设置setOnErrorListener——没设的话，prepare失败你是完全感知不到的，这是很多“没回调”问题的根因。

6.4 用dumpsys media.player确认底层状态

最后一个调试工具是adb shell dumpsys media.player，它能输出当前所有MediaPlayer实例的底层状态，包括播放器类型、数据源URL、created timestamp、pid、uid等。初始化阶段排查时，这几项能帮你快速判断你创建的MediaPlayer底层到底是什么后端、加载到了什么数据源、是否卡在某个状态。

在你确认自己应用层调用没问题，但播放就是起不来的时候，先抓一份dumpsys，对照状态机看看是不是已经在底层出错但没传回调。

7. 一些源码阅读和排障的体会

把初始化这条链路读完，最大的感受是这个框架在复杂度和稳定性之间做了相当多的取舍。Java层的状态机约束，让大部分错误在早期就暴露；JNI层的弱引用管理，避免了大部分生命周期问题；Native层的工厂模式和状态通知，把后端实现隔离得很彻底——这些都是设计层面的好东西。

实际排障时，我个人养成的习惯是按“状态机检查 -> 回调链路检查 -> 底层log检查 -> dumpsys确认”这个顺序来推进，大多数问题走完前三步就能定位，走完四步基本能确定根因。读源码不建议一次追求“全读”，而是带着问题去查，比如这次查初始化，就只追构造到prepare的链路，start、pause、seek、release那些分支不看，等排查到对应问题时再回头看。

初始化这篇就到这里。下一篇我会围绕start()调用之后的链路展开，重点分析播放开始阶段NuPlayer是如何拉起解码器、何时开始缓冲、首帧渲染的时机怎么控制，以及播放过程中卡顿时的排查方向。