简介本资源是一个基于FFmpeg的Android原生视频播放器开源项目面向具备C语言基础与Android开发经验的中高级开发者解决在Android平台深度定制音视频播放能力的需求尤其适用于需支持非标格式、硬件加速解码或自定义滤镜处理的场景。压缩包共34个文件涵盖6个Makefile与Android.mk构建脚本支撑NDK交叉编译、4个Java核心类实现JNI调用与SurfaceView渲染控制、10个XML布局与配置文件含AndroidManifest.xml与资源声明、5个PNG图标及README.md、LICENSE等关键文档整体仅130KB轻量紧凑且目录结构清晰便于快速理解FFmpeg集成路径与播放器分层设计。已有745人学习下载项目完整呈现了avformat_open_input、avcodec_send_packet等关键FFmpeg API在Android端的调用链路附带可直接编译运行的jni/源码与预置so集成方案是掌握Android NDKFFmpeg多媒体开发的典型实践范例。1. 安卓端硬核视频播放不依赖系统 MediaCodec纯 C 层 FFmpeg 解码 OpenGL 渲染实测支持 H.265/AV1/VP9 多路软解你有没有遇到过这种场景在一台老旧安卓平板上跑一个监控回放 App系统自带 MediaPlayer 直接报UnsupportedVideoExceptionSurfaceView 黑屏、TextureView 纹理错乱Logcat 里全是codec not found但同一段 H.265 流用 VLC 手机版却能丝滑播放问题不在视频本身而在安卓碎片化——厂商定制 ROM 删减了硬解能力而系统媒体框架又死守“只调用 HAL 层”的教条。这个android-ffmpeg-player就是为这类场景而生的它绕开整个MediaCodec和MediaPlayer栈从AVPacket拆包开始全程在 Native 层用 FFmpeg C API 做解码支持h264,h265,vp8,vp9,av1再把 YUV 数据用 OpenGL ES 2.0 转成 RGB 渲染到 Surface最终通过SurfaceTexture回传给 Java 层 View。它不是 demo而是可嵌入工业级设备的播放内核——某高校实验室的无人机图传终端、某公司车载中控的多路视频墙模块都基于它二次开发。如果你需要稳定支持非标编码、自定义解码参数、或在无硬件解码能力的设备上跑通视频流这份源码就是你的底层弹药库。2. 项目结构与技术栈C 为主干JNI 为桥梁OpenGL 为画布2.1 目录结构解析Native 层才是主战场项目采用典型的 Android NDK 工程结构核心逻辑全部下沉至src/main/cpp/Java 层仅负责生命周期绑定与 UI 交互。目录树如下已剔除 build 文件与测试资源app/ ├── src/ │ ├── main/ │ │ ├── java/ # Java 接口层极薄 │ │ │ └── com/example/ffmpegplayer/ │ │ │ ├── FFmpegPlayer.java # 主播放器封装类暴露 start/stop/seek │ │ │ └── VideoSurfaceView.java # 自定义 View持有 SurfaceTexture │ │ ├── cpp/ # 全部业务逻辑所在 │ │ │ ├── CMakeLists.txt # 构建入口链接 ffmpeg 静态库 │ │ │ ├── ffmpeg_player.cpp # 主解码循环读取 → 解码 → 转码 → 渲染 │ │ │ ├── video_render.cpp # OpenGL 渲染管线YUV→RGB shader、纹理绑定、帧同步 │ │ │ ├── audio_player.cpp # OpenSL ES 音频输出本项目聚焦视频音频仅占 20 行 │ │ │ └── utils/ # 工具集 │ │ │ ├── log.h # 安卓日志宏封装__android_log_print │ │ │ └── time_utils.h # 时间戳对齐、PTS/DTS 计算 │ │ └── res/ │ └── CMakeLists.txt # 顶层 CMake指定 ABI 与构建选项 └── build.gradle # NDK 配置stlc_static, abiFilters[arm64-v8a]提示ffmpeg_player.cpp是整个播放器的“心脏”它不继承任何 Android 类完全用 C 写成所有 JNI 函数均以Java_com_example_ffmpegplayer_FFmpegPlayer_开头符合 JNI 规范。这种设计让代码可脱离 Android 环境单独单元测试——我一般会把ffmpeg_player.cpp拷到 Linux 下用libavdevice模拟输入验证解码逻辑是否健壮。2.2 技术选型依据为什么是 FFmpeg OpenGL ES 2.0 而非 MediaCodec维度系统 MediaPlayer / MediaCodecandroid-ffmpeg-player选型理由编码兼容性严重依赖厂商 HAL 实现H.265/AV1 支持率 40%Android 10 以下FFmpeg 5.1 全编码软解无需硬件支持工业设备常运行 Android 7–9无法升级系统必须靠软解兜底控制粒度黑匣子无法干预解码器内部队列、丢帧策略、色彩空间转换可精确控制AVFrame分配、sws_scale参数、YUV 格式选择NV12/NV21/I420某跨平台系统需强制输出 I420 供后续图像算法处理MediaCodec 默认输出 HAL 特定格式线程模型强制异步回调错误传播链长调试困难全手动线程管理解码线程 渲染线程 音频线程共享AVPacketQueue某导师曾因 MediaCodec 在onOutputBufferAvailable中崩溃导致整机重启改用本方案后稳定性提升 92%内存模型ByteBuffer与Surface绑定内存拷贝不可控AVFrame.data[0]直接映射到 OpenGL 纹理内存零拷贝路径可达在 4K30fps 场景下内存带宽节省 37%帧率更稳FFmpeg 并非直接编译进项目而是作为预编译静态库引入libavcodec.a,libavformat.a,libswscale.a,libswresample.a,libavutil.a。CMakeLists.txt 中关键片段如下# app/src/main/cpp/CMakeLists.txt add_library(ffmpeg_player SHARED ffmpeg_player.cpp video_render.cpp audio_player.cpp ) # 链接预编译 FFmpeg 库位于 libs/ 目录下 target_link_libraries(ffmpeg_player android log GLESv2 OpenSLES ${CMAKE_SOURCE_DIR}/libs/${ANDROID_ABI}/libavcodec.a ${CMAKE_SOURCE_DIR}/libs/${ANDROID_ABI}/libavformat.a ${CMAKE_SOURCE_DIR}/libs/${ANDROID_ABI}/libswscale.a ${CMAKE_SOURCE_DIR}/libs/${ANDROID_ABI}/libswresample.a ${CMAKE_SOURCE_DIR}/libs/${ANDROID_ABI}/libavutil.a )注意${ANDROID_ABI}动态匹配arm64-v8a或armeabi-v7a避免 ABI 不匹配导致UnsatisfiedLinkError。这是新手最容易翻车的第一步——别手贱把x86库塞进arm64设备。2.3 JNI 接口设计Java 如何安全地“指挥” C 层解码器Java 层FFmpegPlayer.java仅暴露 5 个核心方法全部通过native关键字调用 C 函数public class FFmpegPlayer { static { System.loadLibrary(ffmpeg_player); } private long nativeContext; // 指向 C 层 AVFormatContext* 的 long 值 public void setDataSource(String path) { nativeSetDataSource(nativeContext, path); } public void prepare() { nativePrepare(nativeContext); } public void start() { nativeStart(nativeContext); } public void seekTo(long msec) { nativeSeekTo(nativeContext, msec); } public void release() { nativeRelease(nativeContext); } }对应 C 层函数签名ffmpeg_player.cpp// Java 调用时传入的是 jobjectSurfaceTextureC 层需转为 ANativeWindow* JNIEXPORT void JNICALL Java_com_example_ffmpegplayer_FFmpegPlayer_nativeSetDataSource( JNIEnv *env, jobject thiz, jlong context, jstring path) { const char *url (*env)-GetStringUTFChars(env, path, NULL); // 1. 初始化 AVFormatContext AVFormatContext *fmt_ctx avformat_alloc_context(); if (avformat_open_input(fmt_ctx, url, NULL, NULL) 0) { __android_log_print(ANDROID_LOG_ERROR, FFMPEG, Cannot open input %s, url); return; } // 2. 查找视频流索引 int video_stream_idx -1; for (int i 0; i fmt_ctx-nb_streams; i) { if (fmt_ctx-streams[i]-codecpar-codec_type AVMEDIA_TYPE_VIDEO) { video_stream_idx i; break; } } // 3. 保存上下文指针到 Java 对象字段通过 GetFieldID 获取 fieldID jclass clazz (*env)-GetObjectClass(env, thiz); jfieldID fid (*env)-GetFieldID(env, clazz, nativeContext, J); (*env)-SetLongField(env, thiz, fid, (jlong) fmt_ctx); // 关键把 C 指针存进 Java 对象 (*env)-ReleaseStringUTFChars(env, path, url); }注意nativeContext字段是 Java 对象与 C 内存的唯一纽带。一旦 Java 对象被 GC而 C 层未调用avformat_close_input()就会发生野指针访问。这是血泪经验——某开发者在Activity.onDestroy()中忘记调用player.release()导致后台解码线程持续写入已释放内存App 随机闪退。解决方案在release()的 JNI 实现中强制avformat_close_input(fmt_ctx)并置fmt_ctx NULL。3. 核心解码流程拆解从 AVPacket 到 OpenGL 纹理的完整链路3.1 解码主循环阻塞式读包 非阻塞式解码ffmpeg_player.cpp中decode_thread_func()是解码线程入口其核心逻辑是经典的“生产者-消费者”模型使用AVPacketQueue自定义环形缓冲区解耦读包与解码// app/src/main/cpp/ffmpeg_player.cpp typedef struct PacketQueue { AVPacket *pkt_array; // 动态分配的 AVPacket 数组 int front, rear, size; // 环形队列指针 pthread_mutex_t mutex; pthread_cond_t cond; } PacketQueue; void* decode_thread_func(void* arg) { PlayerContext *ctx (PlayerContext*) arg; AVPacket pkt; while (!ctx-abort_request) { // 步骤1从文件/网络读取一个 AVPacket阻塞 if (av_read_frame(ctx-fmt_ctx, pkt) 0) { ctx-eof_reached 1; break; } // 步骤2将 pkt 入队线程安全 packet_queue_put(ctx-video_pkt_queue, pkt); // 步骤3若队列满等待渲染线程消费避免 OOM if (packet_queue_size(ctx-video_pkt_queue) MAX_PACKET_QUEUE_SIZE) { usleep(10000); // 10ms } } return NULL; }packet_queue_put()内部使用pthread_mutex_lock()保证线程安全MAX_PACKET_QUEUE_SIZE默认设为 200约 2 秒视频数据这是经验值——太小易卡顿太大吃内存。某跨平台系统在 8 路 1080p 流场景下将此值调至 500 后 CPU 占用率下降 18%。3.2 视频解码器初始化硬解优先软解兜底init_video_decoder()函数决定最终使用哪种解码器int init_video_decoder(PlayerContext *ctx) { // 1. 尝试查找硬件解码器如 OMX.google.h264.decoder const AVCodec *codec avcodec_find_decoder_by_name(h264_mediacodec); if (!codec) { __android_log_print(ANDROID_LOG_WARN, FFMPEG, Hardware decoder not available, fallback to software); codec avcodec_find_decoder(ctx-video_stream-codecpar-codec_id); } ctx-video_codec_ctx avcodec_alloc_context3(codec); avcodec_parameters_to_context(ctx-video_codec_ctx, ctx-video_stream-codecpar); // 2. 强制设置线程数软解关键 ctx-video_codec_ctx-thread_count 4; // arm64-v8a 设备通常有 4~8 核 ctx-video_codec_ctx-thread_type FF_THREAD_FRAME | FF_THREAD_SLICE; // 3. 打开解码器 if (avcodec_open2(ctx-video_codec_ctx, codec, NULL) 0) { __android_log_print(ANDROID_LOG_ERROR, FFMPEG, Failed to open video codec); return -1; } return 0; }关键点FF_THREAD_FRAME | FF_THREAD_SLICE启用帧级 切片级并行解码对 H.264/H.265 效果显著。实测在骁龙 855 上开启后 4K 解码耗时从 83ms 降至 31ms。但注意thread_count必须 ≤ CPU 核心数否则线程切换开销反超收益。3.3 YUV→RGB 转换与 OpenGL 渲染零拷贝纹理上传video_render.cpp是性能瓶颈所在。它不走glTexImage2D()全量上传而是用glTexSubImage2D()更新 Y/U/V 三个平面// app/src/main/cpp/video_render.cpp void render_yuv_frame(AVFrame *frame, GLuint y_tex, GLuint u_tex, GLuint v_tex) { // 1. 绑定 Y 平面纹理 glBindTexture(GL_TEXTURE_2D, y_tex); glTexSubImage2D(GL_TEXTURE_2D, 0, 0, 0, frame-width, frame-height, GL_LUMINANCE, GL_UNSIGNED_BYTE, frame-data[0]); // Y 平面 // 2. 绑定 U 平面半尺寸 glBindTexture(GL_TEXTURE_2D, u_tex); glTexSubImage2D(GL_TEXTURE_2D, 0, 0, 0, frame-width / 2, frame-height / 2, GL_LUMINANCE, GL_UNSIGNED_BYTE, frame-data[1]); // U 平面 // 3. 绑定 V 平面半尺寸 glBindTexture(GL_TEXTURE_2D, v_tex); glTexSubImage2D(GL_TEXTURE_2D, 0, 0, 0, frame-width / 2, frame-height / 2, GL_LUMINANCE, GL_UNSIGNED_BYTE, frame-data[2]); // V 平面 // 4. 触发着色器绘制vertex shader fragment shader glDrawArrays(GL_TRIANGLE_STRIP, 0, 4); }对应的 fragment shaderyuv_to_rgb.frag实现 BT.601 转换precision mediump float; varying vec2 v_TexCoord; uniform sampler2D y_texture; uniform sampler2D u_texture; uniform sampler2D v_texture; void main() { float y texture2D(y_texture, v_TexCoord).r; float u texture2D(u_texture, v_TexCoord).r - 0.5; float v texture2D(v_texture, v_TexCoord).r - 0.5; // BT.601 YUV to RGB matrix float r y 1.402 * v; float g y - 0.344 * u - 0.714 * v; float b y 1.772 * u; gl_FragColor vec4(r, g, b, 1.0); }注意v_TexCoord是顶点着色器传入的归一化坐标必须确保VideoSurfaceView的SurfaceTexture设置了setDefaultBufferSize()匹配视频分辨率否则纹理拉伸。某开发者曾因忘记调用surfaceTexture.setDefaultBufferSize(width, height)导致 720p 视频在 1080p View 上显示为模糊马赛克——这是 OpenGL 渲染最隐蔽的坑之一。4. 编译与运行从源码到 APK 的完整实操链路4.1 环境准备NDK、CMake、FFmpeg 静态库三件套本项目要求 NDK r21e 或更高版本因使用std::shared_ptr需 C14 支持CMake 3.10且必须启用c_staticSTL。local.properties中需明确指定ndk.dir/path/to/android-ndk-r21e sdk.dir/path/to/android-sdkFFmpeg 静态库需按 ABI 分别编译。项目已提供libs/arm64-v8a/下的预编译库FFmpeg 5.1.2但若需自定义如裁剪libavdevice以减小体积推荐使用 https://github.com/tanersener/mobile-ffmpeg 的mobile-ffmpeg脚本# 在 macOS/Linux 下执行Windows 需 WSL git clone https://github.com/tanersener/mobile-ffmpeg.git cd mobile-ffmpeg ./compile.sh -l full-gpl # 编译含 x264/x265 的全功能版 # 输出位于 ./android/armeabi-v7a/ 等目录拷贝至项目 libs/ 对应 ABI 文件夹提示full-gpl版本包含专利编码器H.264/H.265商用前务必确认授权合规性。若仅需解码用micro版本无编码器即可体积从 42MB 降至 8MB。4.2 Gradle 配置关键点ABI 过滤与 STL 选择app/build.gradle中 NDK 配置必须严格匹配android { compileSdk 33 defaultConfig { applicationId com.example.ffmpegplayer minSdk 21 targetSdk 33 versionCode 1 versionName 1.0 // 关键只支持 arm64-v8a避免 x86 模拟器干扰 ndk { abiFilters arm64-v8a } } externalNativeBuild { cmake { path file(../../src/main/cpp/CMakeLists.txt) version 3.22.1 } } } // 关键STL 必须为 c_static否则 libavutil 中的 std::atomic 会链接失败 externalNativeBuild { cmake { arguments -DANDROID_STLc_static } }若忽略ANDROID_STLc_static编译时会出现undefined reference to __cxa_guard_acquire错误——这是 C 运行时符号缺失的典型表现。4.3 运行时权限与文件路径/storage/emulated/0/ 是你的朋友Android 10 强制分区存储getExternalStorageDirectory()返回路径不可写。播放本地文件时必须使用Context.getExternalFilesDir(null)或MediaStoreAPI。示例代码// Java 层获取合法路径 File videoFile new File(getExternalFilesDir(null), test.mp4); // 或从 Intent 获取 URI推荐用于相册选择 Uri uri intent.getData(); String path getRealPathFromURI(uri); // 需自行实现 ContentResolver 查询 player.setDataSource(path);注意getRealPathFromURI()在 Android 10 需适配 Scoped Storage建议直接用ContentResolver.openInputStream(uri)获取InputStream再通过 JNI 传入AVIOContext自定义读取——这比路径转换更可靠。某导师的项目因此重构了 IO 层将avio_open()替换为avio_open2()AVIOInterruptCB彻底规避路径问题。5. 常见问题排查5 条真实踩坑记录与速查指南5.1 现象App 启动即 crashLogcat 显示java.lang.UnsatisfiedLinkError: dlopen failed: library libavcodec.so not found原因项目使用静态链接.a文件但CMakeLists.txt中误写了find_library(avcodec-lib avcodec)导致 CMake 尝试动态链接。解决删除所有find_library调用改为target_link_libraries()直接链接.a文件见 2.2 节代码。检查libs/arm64-v8a/下是否存在libavcodec.a文件大小应 15MB。5.2 现象视频画面静止Logcat 持续刷avcodec_receive_frame() returned -11AVERROR(EAGAIN)原因解码器输入AVPacket后未等待足够时间就调用avcodec_receive_frame()。FFmpeg 解码器有内部缓冲首帧需多次send_packet()后才能receive_frame()。解决在decode_video_frame()循环中加入重试机制while (avcodec_receive_frame(codec_ctx, frame) AVERROR(EAGAIN)) { if (avcodec_send_packet(codec_ctx, pkt) 0) break; usleep(1000); // 等待 1ms }5.3 现象画面绿屏/紫屏但音频正常原因YUV 格式识别错误。AVFrame.format为AV_PIX_FMT_NV12但 OpenGL 渲染代码按AV_PIX_FMT_YUV420PI420解析frame-data[1]/data[2]。解决在render_yuv_frame()前插入格式转换if (frame-format ! AV_PIX_FMT_YUV420P) { sws_scale(sws_ctx, (const uint8_t* const*)frame-data, frame-linesize, 0, frame-height, dst_frame-data, dst_frame-linesize); frame dst_frame; // 使用转换后的帧 }sws_ctx需提前用sws_getContext()初始化。5.4 现象SeekBar 拖动后画面卡住Logcat 出现av_seek_frame() failed或Invalid data found when processing input原因av_seek_frame()要求输入格式支持随机访问如 MP4而 RTSP/HTTP-FLV 流不支持。强行调用会破坏解码器状态。解决增加流类型判断if (fmt_ctx-iformat-flags AVFMT_SEEK_TO_PTS) { av_seek_frame(fmt_ctx, video_stream_idx, timestamp, AVSEEK_FLAG_BACKWARD); } else { // 重置解码器重新 demux模拟“软拖动” avcodec_flush_buffers(video_codec_ctx); ctx-seek_req 1; // 标记需重新同步 }5.5 现象低端机如联发科 MT6737上播放 1080p 视频严重卡顿CPU 占用 100%原因thread_count设置过高如设为 8但该 SoC 仅 4 核线程竞争激烈。解决动态获取 CPU 核心数并限制int cpu_cores sysconf(_SC_NPROCESSORS_ONLN); // Linux 系统调用 ctx-video_codec_ctx-thread_count (cpu_cores 4) ? 4 : cpu_cores;同时在build.gradle中abiFilters保留armeabi-v7a避免 64 位指令在 32 位 CPU 上崩溃。6. 二次开发实战为工业设备添加低延迟模式与自定义 OSD6.1 低延迟模式砍掉解码器缓冲牺牲容错换实时性工业图传场景如无人机遥控要求端到端延迟 200ms。默认 FFmpeg 解码器会缓存多帧以应对丢包需主动干预// 在 init_video_decoder() 后追加 ctx-video_codec_ctx-flags2 | AV_CODEC_FLAG2_FAST; // 启用快速解码 ctx-video_codec_ctx-skip_frame AVDISCARD_NONREF; // 丢弃非参考帧B帧 ctx-video_codec_ctx-skip_idct AVDISCARD_BIDIR; // 跳过双向帧 IDCT // 关键禁用解码器内部帧队列 ctx-video_codec_ctx-has_b_frames 0; // 强制无 B 帧同时修改解码循环移除packet_queue缓冲改为直通模式// 替换原 decode_thread_func() void* low_latency_decode_thread(void* arg) { PlayerContext *ctx (PlayerContext*) arg; AVPacket pkt; AVFrame *frame av_frame_alloc(); while (!ctx-abort_request) { if (av_read_frame(ctx-fmt_ctx, pkt) 0) { if (pkt.stream_index ctx-video_stream_idx) { avcodec_send_packet(ctx-video_codec_ctx, pkt); while (avcodec_receive_frame(ctx-video_codec_ctx, frame) 0) { render_yuv_frame(frame, y_tex, u_tex, v_tex); // 立即渲染不入队 } } av_packet_unref(pkt); } } av_frame_free(frame); return NULL; }实测在海思 Hi3516DV300 平台上开启此模式后平均延迟从 412ms 降至 167ms代价是弱网下花屏概率上升 23%——这是工业场景可接受的权衡。6.2 自定义 OSDOn-Screen Display在 OpenGL 渲染管线中叠加文字与图形OSD 需与视频帧像素对齐且不能影响主线程。最佳实践是复用 OpenGL 上下文在render_yuv_frame()后立即绘制// video_render.cpp 中新增 void render_osd_text(const char* text, int x, int y, int size) { // 1. 绑定 OSD 纹理预加载的字体图集 glBindTexture(GL_TEXTURE_2D, osd_texture_id); // 2. 计算字符 UV 坐标假设图集为 256x256每个字符 16x16 float char_w 16.0f / 256.0f; float char_h 16.0f / 256.0f; // 3. 逐字符绘制简化版实际用 VBO 存储顶点 for (int i 0; text[i]; i) { char c text[i]; float u1 (c % 16) * char_w; float v1 (c / 16) * char_h; // ... 生成四边形顶点与 UV调用 glDrawArrays } } // 在 render_yuv_frame() 后调用 render_yuv_frame(frame, y_tex, u_tex, v_tex); render_osd_text(REC: 00:01:23, 20, 40, 24); // 右上角录制时间关键OSD 纹理必须用GL_NEAREST插值glTexParameterf(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_NEAREST)避免缩放模糊。某公司车载中控要求 OSD 文字在 1080p 屏幕上清晰可读最终采用 512x512 图集 SDFSigned Distance Field字体边缘抗锯齿效果远超系统 TextView。6.3 验证与调试技巧用 adb shell ffplay 快速定位问题不依赖 Android Studio用命令行快速验证流是否可解# 1. 将视频文件推送到设备 adb push test.mp4 /sdcard/Download/ # 2. 进入设备 shell用 ffplay 检查需预装 termux ffmpeg adb shell termux-setup-storage cd ~/storage/shared/Download ffplay -v debug -i test.mp4 21 | grep -E (codec|stream|error) # 3. 若 ffplay 正常问题必在 JNI 或 OpenGL 层若 ffplay 报错则是 FFmpeg 库或文件问题从那以后我每次集成新版本 FFmpeg都强制走一遍ffplay -v debug验证流兼容性再编译 APK。省去一半 Logcat 盲猜时间。希望帮到你。本文还有配套的精品资源点击获取