将FFmpeg 8.1 CLI封装为Android NDK共享库：头文件与符号错误

背景 #

基于FFmpeg 8.1为Android构建自定义视频处理引擎，为复用成熟的混流逻辑，计划将FFmpeg CLI工具封装为库并通过JNI调用，同时避开ffmpeg-kit以精简二进制体积。已在M5芯片的macOS上完成arm64-v8a架构（NDK r28，目标API24）的交叉编译。

已采取的策略 #

• 修改fftools/ffmpeg.c，将main函数重命名为int sm_engine_exec(int argc, char** argv)，作为JNI调用的入口
• 编译FFmpeg时添加--enable-pic参数，确保生成的库兼容Android动态链接库要求

遇到的问题 #

1. 头文件缺失：编译JNI包装器时，ffmpeg.c依赖的非公开头文件（如cmdutils.h）不在make install后的标准include目录，触发“文件未找到”编译错误
2. 链接器错误：修复头文件问题后，链接器无法找到sm_engine_exec及其依赖符号（如stdin_interaction、dec_free、term_init）——这些符号位于fftools/*.o目标文件中，未被包含在FFmpeg标准静态库内

FFmpeg构建配置 #

./configure \
  --prefix=$OUTPUT \
  --target-os=android \
  --arch=aarch64 \
  --cpu=armv8-a \
  --enable-cross-compile \
  --sysroot=$TOOLCHAIN/sysroot \
  --cc=$CC \
  --cxx=$CXX \
  --ar=$AR \
  --ranlib=$RANLIB \
  --nm=$NM \
  --strip=$STRIP \
  --extra-cflags="-fPIC -fPIE" \
  --extra-ldflags="-fPIC -fPIE" \
  --enable-static \
  --disable-shared \
  --enable-ffmpeg     \
  --disable-ffplay \
  --disable-ffprobe \
  --disable-doc \
  --disable-debug \
  --disable-programs \
  --enable-small

技术问题解答 #

1. 如何在CMake/NDK构建中正确引入fftools源目录下的非公开头文件？ #

直接在JNI模块的CMakeLists.txt中添加FFmpeg源码的fftools目录作为包含路径即可，无需依赖make install的结果：

• 在CMakeLists.txt中使用include_directories()添加FFmpeg源码根目录和fftools子目录的路径
• 示例：

  # 假设FFmpeg源码存放在项目的third_party/ffmpeg目录下
  include_directories(${CMAKE_SOURCE_DIR}/third_party/ffmpeg)
  include_directories(${CMAKE_SOURCE_DIR}/third_party/ffmpeg/fftools)
  

fftools的头文件属于FFmpeg内部未公开接口，官方构建系统不会将其安装到prefix目录，直接引用源码目录是最直接的解决方式。

2. 是否有标准方法强制FFmpeg生成包含ffmpeg.c及其依赖的libffmpeg_cli.a静态库？ #

FFmpeg官方构建系统没有直接生成该静态库的选项，但可以手动从编译产物打包：

1. 完成FFmpeg编译后，进入FFmpeg源码根目录下的fftools文件夹，这里已经生成了所有需要的.o文件（ffmpeg.o、ffmpeg_opt.o、ffmpeg_dec.o、cmdutils.o等）
2. 使用Android NDK提供的ar工具将这些.o文件打包为静态库：

   $AR rcs $OUTPUT/lib/libffmpeg_cli.a fftools/*.o
   

3. 将生成的libffmpeg_cli.a与FFmpeg核心静态库（如libavformat.a、libavcodec.a等）一起链接到JNI模块中

如果不想手动操作，也可以修改FFmpeg的Makefile，在fftools目标中添加生成静态库的规则，但手动打包更简单，无需修改FFmpeg原生构建系统。

3. ffmpeg-kit或类似项目是如何成功将CLI封装为共享库的？是否手动将所有fftools/*.o对象创建为静态归档？ #

是的，这类项目的核心逻辑就是手动处理fftools的目标文件：

• 编译FFmpeg时保留fftools的编译产物（即使使用--disable-programs，也确保fftools的.o文件被生成）
• 将fftools下所有相关.o文件与FFmpeg核心库一起链接为共享库
• 修改ffmpeg.c的main函数为可导出的入口函数（和你实现的sm_engine_exec逻辑一致），并补充全局初始化、清理逻辑
  部分项目会额外封装JNI层的参数转换、错误处理，但核心都是手动将fftools目标文件整合到最终库中。

4. 将FFmpeg的CLI代码作为静态库嵌入Android .so在架构设计上是否合理？是否存在全局状态或线程相关的隐藏陷阱？ #

架构合理性

如果仅需复用混流这类成熟逻辑，这种方式是合理的——省去了基于FFmpeg核心API重新实现复杂参数解析、流处理、错误处理的工作量，能快速落地功能。但如果后续需要高度定制化的视频处理逻辑（如实时流处理、动态调整滤镜链），直接使用FFmpeg核心API会更灵活。

隐藏陷阱

• 全局状态残留：FFmpeg CLI代码依赖大量全局变量（如opt_global、decode_options），多次调用sm_engine_exec时会存在状态残留，导致后续调用行为异常。解决办法是在每次调用前后添加全局状态重置逻辑，或通过子进程执行CLI逻辑（但Android上fork存在诸多限制，不推荐）。
• 线程不安全：CLI代码未做线程安全设计，同时在多线程调用sm_engine_exec会触发全局变量竞争，必须保证同一时间只有一个线程执行该函数，或为调用添加全局锁。
• 资源泄漏：CLI代码在异常退出场景下可能存在资源未释放的问题，需要覆盖各类错误场景（如文件不存在、编码失败）测试，确保资源被正确清理。
• 信号处理冲突：CLI代码会注册信号处理函数（如SIGINT），可能与Android应用的信号处理逻辑冲突，需修改fftools代码移除无关的信号处理逻辑。

内容的提问来源于stack exchange，提问作者HARRSH BERMANN