Android原生RTSP播放器：MediaCodec硬解+RTP解析稳定方案

简介：本资源是一个面向Android开发者的RTSP流媒体播放入门级DEMO，适用于具备Java基础与Android SDK开发经验的中级学习者，旨在解决在移动设备上快速集成实时视频流播放功能的实际问题。压缩包共55个文件，包含16个编译后的class字节码、15张UI图标png、8个布局与配置xml、5个核心java源码（含MediaPlayer初始化、异步准备、状态监听等关键逻辑），以及apk安装包、so本地库、工程配置文件等，完整呈现从代码编写到可运行应用的全流程，4.73MB体积轻量易导入。已有729人学习下载，资源结构清晰，src与res目录分离规范，gen与bin为自动生成内容，libs中含兼容性支持库，便于开发者快速理解RTSP地址配置、SurfaceView渲染、错误回调处理及资源释放等核心实践要点。

1. 这不是个“能播RTSP流”的Demo，而是一份能让你在Android真机上扛住7×24小时连续拉流、不OOM、不卡死、不闪退的播放器底座

某开发者在产线调试安防摄像头对接时，用过5个开源RTSP播放库：有的播3分钟就ANR，有的切横竖屏必崩，有的连H.264 baseline都解不出画面，还有的把rtsp://192.168.1.100:554/stream1硬编码进Java层，改个端口都要重编。直到他扒开这个android rtsp播放DEMO的源码包——没有花哨UI，没套任何MVVM框架，但SurfaceView直通MediaCodec解码器，RtspClient用纯Socket+状态机实现信令交互，RtpPacketQueue带超时丢包策略，MediaCodecBufferPool复用缓冲区。它不承诺“支持所有RTSP服务器”，但明确告诉你：只兼容RFC2326标准信令 + RTP over UDP传输 + H.264/H.265 Annex-B裸流。适合嵌入式IPC设备对接、工业相机集成、车载DVR二次开发等对稳定性压倒性优先的场景。如果你正被MediaCodec.dequeueOutputBuffer timeout、Surface was abandoned或RTP timestamp jump折磨，这份代码就是你该停下来的第一个锚点。

2. 工程结构与技术栈：从Gradle配置到Native层调用链路全透视

这个项目不是“Android Studio新建项目→加个依赖→写两行MediaPlayer”的玩具。它刻意绕开了MediaPlayer和ExoPlayer的黑匣子，用最底层的组件拼出可控链路。整个工程是纯Java/Kotlin+少量C++的混合体，无第三方播放器SDK，所有音视频处理逻辑都在自己手里。

2.1 目录结构：6个核心包讲清数据流向

项目解压后共12个文件夹，但真正参与播放流程的是以下6个：

app/ ├── src/main/ │ ├── java/com/example/rtspdemo/ │ │ ├── core/ // RTSP信令状态机、RTP解析、NALU分帧 │ │ ├── decoder/ // MediaCodec初始化、输入输出缓冲区管理、H.264/H.265解码循环 │ │ ├── render/ // Surface绑定、OpenGL ES纹理更新、YUV转RGB着色器（可选） │ │ ├── utils/ // 时间戳同步、PTS/DTS计算、网络抖动缓冲区（JitterBuffer） │ │ ├── widget/ // 自定义SurfaceView、触摸控制层（缩放/抓拍） │ │ └── MainActivity.kt // 生命周期管理、Surface创建时机、错误回调注册 │ └── cpp/ // librtspclient.so：C++实现的RTSP信令收发（避免Java层频繁GC）

提示：cpp/目录下没有.so二进制，只有CMakeLists.txt和rtsp_client.cpp——这意味着你必须本地NDK编译。常见踩坑是NDK版本不匹配导致dlopen failed: library "liblog.so" not found，解决方案见第4章。

2.2 Gradle配置：为什么minSdkVersion必须是21？

app/build.gradle中关键配置如下：

android { compileSdk 34 defaultConfig { applicationId "com.example.rtspdemo" minSdk 21 // ⚠️ 强制要求：MediaCodec.createByCodecName()在21+才稳定支持硬件解码器枚举 targetSdk 34 versionCode 1 versionName "1.0" ndk { abiFilters 'armeabi-v7a', 'arm64-v8a' // 不支持x86模拟器！真机调试必须用ARM设备 } } externalNativeBuild { cmake { path "src/main/cpp/CMakeLists.txt" } } }

为什么不能设为16？因为MediaCodec在API 16引入，但createDecoderByType("video/avc")在低端设备上会返回null；API 21起，MediaCodecList保证返回可用解码器列表，且configure()支持surface参数直连SurfaceView。这是本项目能稳定运行的最低安全水位线。

2.3 技术栈选型逻辑：不用ExoPlayer不是因为“炫技”，而是因它不可控

注意：项目默认关闭音频通道。若需加音频，必须在core/RtspClient.kt中取消注释startAudioRtp()，并在decoder/AudioDecoder.kt里补全MediaCodec音频解码循环——这不是“打开开关”就能用的事，涉及PTS对齐和音频缓冲区大小重算。

2.4 Native层调用链：C++如何把RTP包喂给Java层解码器？

cpp/rtsp_client.cpp中核心逻辑是：

// C++层：收到UDP包后，解析RTP头，提取payload type和timestamp void onRtpPacketReceived(uint8_t* data, int len) { RtpHeader header; parseRtpHeader(data, &header); // 提取sequence number, timestamp, payload type if (header.payload_type == 96) { // H.264 // 剥离RTP头，只传NALU数据给Java层 jbyteArray jByteArray = env->NewByteArray(len - 12); env->SetByteArrayRegion(jByteArray, 0, len - 12, (jbyte*)(data + 12)); // 调用Java层方法：onNaluReceived(byte[], timestamp, sequence) env->CallVoidMethod(javaObj, methodId, jByteArray, header.timestamp, header.seq_num); } }

Java层对应接收方法：

fun onNaluReceived(naluData: ByteArray, rtpTimestamp: Long, seqNum: Int) { // 将NALU送入解码器输入缓冲区 val inputBufferIndex = mediaCodec.dequeueInputBuffer(10000) // ⚠️ 10秒超时！防卡死 if (inputBufferIndex >= 0) { val inputBuffer = mediaCodec.getInputBuffer(inputBufferIndex) inputBuffer?.clear() inputBuffer?.put(naluData) // 关键：将RTP timestamp转换为MediaCodec可识别的ptsUs（微秒） val ptsUs = convertRtpTimestampToPtsUs(rtpTimestamp) mediaCodec.queueInputBuffer( inputBufferIndex, 0, naluData.size, ptsUs, 0 // flags: BUFFER_FLAG_KEY_FRAME for IDR ) } }

这里藏着一个血泪经验：convertRtpTimestampToPtsUs()不是简单乘以1000。RTP timestamp是90kHz时钟，而MediaCodec要的是微秒级绝对时间戳。必须用System.nanoTime()做初始偏移校准，否则画面会持续卡顿。项目里用utils/TimestampHelper.kt实现了该转换，原理是记录第一个RTP包到达时的System.nanoTime()，后续所有ptsUs = basePtsUs + (rtpTs - firstRtpTs) * 1000 / 90。

3. 核心模块拆解：从RTSP OPTIONS到MediaCodec解码循环的完整链路

整个播放流程可拆为5个原子阶段，每个阶段失败都会导致黑屏/卡顿/崩溃。下面逐段贴出真实代码并说明每行为何这么写。

3.1 RTSP信令交互：状态机驱动的OPTIONS→DESCRIBE→SETUP→PLAY

core/RtspClient.kt中RtspSession类用enum class State管理连接状态：

enum class State { IDLE, OPTIONS_SENT, DESCRIBE_SENT, SETUP_SENT, READY, PLAYING, ERROR }

发起OPTIONS请求的关键代码：

fun sendOptions() { val request = "OPTIONS rtsp://$host:$port/$path RTSP/1.0\r\n" + "CSeq: ${cseq++}\r\n" + "User-Agent: AndroidRTSPClient/1.0\r\n\r\n" socketOutputStream.write(request.toByteArray()) // ⚠️ 必须读取响应，否则DESCRIBE会因socket缓冲区满而阻塞 readResponse() // 解析CSeq匹配、获取Public头字段 }

为什么CSeq必须递增？RFC2326规定服务器用CSeq匹配请求/响应，若重复发送相同CSeq，某些海康设备会直接断连。项目里cseq是AtomicInteger，确保多线程安全。

DESCRIBE响应解析后，关键是要提取sdp中的a=rtpmap和a=control字段：

private fun parseSdp(sdp: String): SdpInfo { val lines = sdp.split("\n") var videoControlUrl = "" var payloadType = 96 var encodingName = "H264" for (line in lines) { if (line.startsWith("a=rtpmap:")) { // a=rtpmap:96 H264/90000 → payloadType=96, encodingName="H264" val parts = line.substring(9).split(" ") payloadType = parts[0].toInt() encodingName = parts[1].substringBefore("/") } else if (line.startsWith("a=control:")) { videoControlUrl = line.substring(10).trim() } } return SdpInfo(payloadType, encodingName, videoControlUrl) }

videoControlUrl决定后续SETUP请求的URL路径。很多开发者卡在这里：把DESCRIBE返回的a=control:trackID=0直接当URL用，实际应拼成rtsp://host:port/path/trackID=0。项目里setupVideoTrack()方法做了自动拼接。

3.2 RTP包解析：如何从UDP流中精准切出H.264 NALU？

core/RtpParser.kt是本项目最易被低估的模块。它不依赖jrtplib等库，而是手动解析RTP头+FU-A分片：

fun parseRtpPacket(data: ByteArray): RtpPacket? { if (data.size < 12) return null val version = data[0].toInt() and 0xC0 shr 6 // bit 0-1 if (version != 2) return null val payloadType = data[1].toInt() and 0x7F val sequenceNumber = ((data[2].toInt() and 0xFF) shl 8) or (data[3].toInt() and 0xFF) val timestamp = ((data[4].toInt() and 0xFF) shl 24) or ((data[5].toInt() and 0xFF) shl 16) or ((data[6].toInt() and 0xFF) shl 8) or (data[7].toInt() and 0xFF) // 关键：判断是否FU-A分片（H.264大帧拆包） val payloadStart = 12 if (payloadType == 96 && data.size > payloadStart) { val nalHeader = data[payloadStart].toInt() and 0xFF val fuIndicator = nalHeader val fuHeader = data[payloadStart + 1].toInt() and 0xFF if (fuIndicator and 0x1F == 28 && (fuHeader and 0x80) != 0) { // FU-A start: 插入0x000001前缀，合并所有分片 return parseFuA(data, payloadStart) } } // 单NALU：直接返回payload return RtpPacket(payloadType, timestamp, sequenceNumber, data.copyOfRange(payloadStart, data.size)) }

parseFuA()方法负责重组FU-A分片。H.264一帧超过1400字节时，会被拆成多个UDP包，每个包带FU-A头。项目里用ArrayList<ByteArray>缓存分片，直到收到end bit才合并。这是很多Demo黑屏的根源——没处理FU-A，直接把分片当完整NALU送解码器，MediaCodec立刻报-38（ERROR_INVALID_OPERATION）。

3.3 MediaCodec解码循环：如何避免dequeueOutputBuffer永久阻塞？

decoder/VideoDecoder.kt中的decodeLoop()是心跳线程：

private fun decodeLoop() { while (isRunning) { try { // ⚠️ 关键：outputBufferIndex = -1表示无可用输出，必须继续轮询 val outputBufferIndex = mediaCodec.dequeueOutputBuffer(bufferInfo, 10000) // 10秒超时！ when (outputBufferIndex) { MediaCodec.INFO_TRY_AGAIN_LATER -> { // 无输出，继续下一轮 continue } MediaCodec.INFO_OUTPUT_FORMAT_CHANGED -> { // 解码器输出格式变更（如分辨率变化），需重新配置Surface val newFormat = mediaCodec.outputFormat Log.d(TAG, "New format: $newFormat") } MediaCodec.INFO_OUTPUT_BUFFERS_CHANGED -> { // 输出缓冲区变更（Android 5.0以下），已废弃，忽略 } else -> { // ✅ 正常解码输出 val outputBuffer = mediaCodec.getOutputBuffer(outputBufferIndex) if (outputBuffer != null && bufferInfo.size > 0) { // 渲染到Surface renderToSurface(outputBuffer, bufferInfo) } mediaCodec.releaseOutputBuffer(outputBufferIndex, true) // true=render } } } catch (e: Exception) { Log.e(TAG, "Decode error", e) onError(e) break } } }

为什么dequeueOutputBuffer超时设为10000毫秒？因为MediaCodec在输入缓冲区空、解码器内部队列空时，会无限等待。设10秒强制跳出，触发onError()回调，让上层决定是重连还是降级。项目里onError()会调用resetAndReconnect()，而不是直接finish()——这是7×24小时运行的关键设计。

3.4 时间戳同步：PTS/DTS如何对抗网络抖动？

utils/TimestampHelper.kt中adjustTimestamp()方法解决RTP乱序问题：

fun adjustTimestamp(rtpTimestamp: Long): Long { // 使用滑动窗口计算RTP timestamp的期望值 val nowNs = System.nanoTime() val expectedRtpTs = baseRtpTs + ((nowNs - baseNs) * 90L / 1_000_000L) // 90kHz → ns to rtp ts // 允许±2秒偏差，超出则视为乱序包，丢弃 if (abs(rtpTimestamp - expectedRtpTs) > 2 * 90_000L) { Log.w(TAG, "RTP timestamp jump: $rtpTimestamp, expected: $expectedRtpTs") return -1L // 丢弃此包 } // 计算MediaCodec所需ptsUs（微秒） return (basePtsUs + (rtpTimestamp - baseRtpTs) * 1000L / 90L) }

baseRtpTs和basePtsUs在第一个有效RTP包到达时初始化。baseNs是System.nanoTime()，保证高精度。这个设计让项目在WiFi弱网下仍能维持音画同步，而非像某些Demo那样直接跳帧。

4. 运行与避坑：真机调试必踩的5个坑及血泪修复方案

4.1 现象：App启动后黑屏，Logcat显示E/ACodec: [OMX.qcom.video.decoder.avc] storeMetaDataInBuffers failed w/ err -1010

原因：MediaCodec硬件解码器初始化失败。常见于未在AndroidManifest.xml中声明<uses-feature android:name="android.hardware.camera.any" />，或设备不支持video/avc编码类型。

解决：

1. 在AndroidManifest.xml中添加：

<uses-feature android:name="android.hardware.camera.any" android:required="false" /> <uses-feature android:name="android.hardware.opengles.aep" android:required="true" />

2. 在VideoDecoder.kt初始化前，增加设备能力检测：

private fun isH264DecoderAvailable(): Boolean { val codecList = MediaCodecList(MediaCodecList.REGULAR_CODECS) for (codecInfo in codecList.codecInfos) { if (codecInfo.isEncoder) continue for (type in codecInfo.getSupportedTypes()) { if (type == "video/avc" && codecInfo.name.contains("OMX.")) { return true } } } return false }

若返回false，降级到软解（codecInfo.name.contains("c2.android.")）或提示用户设备不支持。

4.2 现象：播放10分钟后突然卡死，Logcat出现W/MediaCodec: Codec reported err 0x80000000, actionCode 0x0

原因：MediaCodec内部缓冲区溢出。项目默认RtpPacketQueue大小为200，但在高码率（4Mbps+）下，UDP包到达速率超过解码速率，队列填满后offer()返回false，RTP包被静默丢弃，解码器因无输入而卡死。

解决：动态调整队列大小。在core/RtspClient.kt中修改：

// 根据码率估算队列大小：1080p@30fps ≈ 2Mbps → 队列需300包 val estimatedQueueSize = when (bitrateMbps) { in 0.0..1.0 -> 150 in 1.0..3.0 -> 250 else -> 400 } rtpPacketQueue = ConcurrentLinkedQueue<ByteArray>() // 启动后每5秒检查队列占用率，超80%则扩容

4.3 现象：横竖屏切换后Surface黑屏，Logcat报E/Surface: getSlotFromBufferLocked: unknown buffer: 0x...

原因：SurfaceView重建时，旧Surface未及时从MediaCodec解绑，新Surface绑定失败。

解决：在MainActivity.kt中重写onConfigurationChanged()：

override fun onConfigurationChanged(newConfig: Configuration) { super.onConfigurationChanged(newConfig) // 1. 停止解码线程 videoDecoder.stop() // 2. 等待MediaCodec释放Surface Thread.sleep(100) // 3. 重建SurfaceView surfaceView.holder.removeCallback(surfaceHolderCallback) surfaceView.holder.addCallback(surfaceHolderCallback) }

surfaceHolderCallback中surfaceCreated()方法里，先调用videoDecoder.setSurface(surface)再videoDecoder.start()。

4.4 现象：NDK编译失败，CMake报错CMake Error at CMakeLists.txt:10 (find_package): By not providing "FindOpenSSL.cmake" in CMAKE_MODULE_PATH...

原因：cpp/CMakeLists.txt中引用了OpenSSL，但项目实际未使用加密功能，属于冗余依赖。

解决：删除CMakeLists.txt中以下行：

find_package(OpenSSL REQUIRED) target_link_libraries(rtspclient ${OpenSSL_LIBRARIES})

并注释掉rtsp_client.cpp中所有#include <openssl/...>和SSL相关代码。本项目RTSP信令走明文，无需TLS。

4.5 现象：连接海康DS-2CD3T系列摄像头时，DESCRIBE返回461错误（Unsupported Transport）

原因：海康设备默认禁用RTP over UDP，要求Transport: RTP/AVP;unicast;client_port=8000-8001，但项目默认发送Transport: RTP/AVP;unicast;client_port=5000-5001。

解决：在RtspClient.kt的setupVideoTrack()中，动态生成Transport头：

val transportHeader = "Transport: RTP/AVP;unicast;client_port=${localRtpPort}-${localRtpPort+1}\r\n" // localRtpPort由Random(5000..65535).nextInt()生成，避开系统保留端口

并在sendSetup()前，用DatagramSocket()绑定该端口，确保防火墙放行。

5. 二次开发实战：如何接入海康/大华IPC并支持H.265解码

5.1 海康IPC对接三步法：URL构造、认证绕过、H.265适配

海康设备RTSP URL格式为：
rtsp://admin:123456@192.168.1.64:554/Streaming/Channels/101
其中101表示主码流（102为子码流）。但直接使用会触发401认证。项目需改造RtspClient.kt：

1. Base64认证头注入：在sendOptions()后，sendDescribe()前插入：

private fun addAuthHeader(request: String): String { val auth = "$username:$password".encodeToByteArray().toBase64String() return request.replace("CSeq:", "Authorization: Basic $auth\r\nCSeq:") }

2. H.265支持开关：海康H.265流a=rtpmap为97 H265/90000。修改SdpInfo类：

data class SdpInfo( val payloadType: Int, val encodingName: String, // "H264" or "H265" val videoControlUrl: String ) { val mimeType: String get() = when (encodingName.uppercase()) { "H264" -> "video/avc" "H265", "H265-STEREO" -> "video/hevc" // Android 7.0+支持HEVC else -> "video/avc" } }

3. MediaCodec初始化适配：在VideoDecoder.kt中，根据mimeType选择解码器：

val codecName = MediaCodecList(MediaCodecList.REGULAR_CODECS) .findDecoderForType(sdpInfo.mimeType) if (codecName == null) { throw IllegalStateException("No decoder found for ${sdpInfo.mimeType}") } mediaCodec = MediaCodec.createByCodecName(codecName)

5.2 大华IPC特殊处理：SETUP响应中Session头缺失

大华设备（如DH-IPC-HFW1830）的SETUP响应不返回Session头，导致项目无法进入PLAYING状态。需在readResponse()中补充容错：

private fun parseSessionHeader(headers: Map<String, String>): String? { var session = headers["Session"] if (session.isNullOrBlank()) { // 大华设备用CSeq作为Session ID session = "dh-${cseq - 1}" // cseq已在sendSetup()中自增 Log.w(TAG, "No Session header, using DH fallback: $session") } return session?.substringBefore(";") // 去掉";timeout=60" }

5.3 H.265解码性能优化：启用Secure Decode与Color Aspects

Android 8.0+支持HEVC Secure Decode，需在MediaCodec.configure()中添加：

val format = MediaFormat.createVideoFormat(sdpInfo.mimeType, width, height) format.setInteger(MediaFormat.KEY_COLOR_FORMAT, MediaCodecInfo.CodecCapabilities.COLOR_FormatSurface) format.setInteger(MediaFormat.KEY_SECURE, 1) // 启用安全解码 // 关键：设置HEVC Color Aspects，避免绿屏 format.setInteger("color-transfer", 3) // BT.709 format.setInteger("color-standard", 1) // BT.601 format.setInteger("color-range", 2) // Limited range

5.4 实测对比：同一台RK3399设备，H.264 vs H.265功耗与帧率

数据来源：adb shell dumpsys batterystats+adb shell top -n 1，测试条件为1080p@30fps流，持续播放30分钟。H.265优势在低码率场景更明显，但需注意Android 7.0以下设备无video/hevc解码器，必须降级。

从那以后我每次对接新品牌IPC，都先抓包看DESCRIBE响应里的a=rtpmap和a=control，再查MediaCodecList确认解码器存在，最后用adb logcat | grep -i "mediacodec\|rtp"盯住首帧日志。这套动作现在已固化成checklist，放在项目根目录dev-checklist.md里——不是为了炫技，是怕哪天凌晨三点产线报警，翻车在同一个坑里。希望帮到你。

本文还有配套的精品资源，点击获取