FFMS2错误处理机制深度解析：FFMS_ErrorInfo结构与10大错误类型排查清单

FFMS2错误处理机制深度解析FFMS_ErrorInfo结构与10大错误类型排查清单【免费下载链接】ffms2An FFmpeg based source library and Avisynth/VapourSynth plugin for easy frame accurate access项目地址: https://gitcode.com/gh_mirrors/ff/ffms2FFMS2 是一个基于 FFmpeg 的视频源库也是 Avisynth/VapourSynth 插件用于实现**帧精确frame accurate**读取媒体文件。它的设计哲学是把 FFmpeg 内部那些难懂的细节藏起来而错误处理正是这套封装中最值得新手理解的部分所有 C API 通过统一的FFMS_ErrorInfo结构体返回错误类型、子类型和可读消息让你能快速定位问题出在解码、索引还是文件读取。本文带你读完 include/ffms.h 中核心的错误定义并给出一份即查即用的排查清单。一、FFMS2 是如何把错误递给你的FFMS2 内部用 C 异常FFMS_Exception传递错误但对外只暴露纯 C 接口。工作机制很简单内部函数如打开文件、解码帧出错时抛出FFMS_Exception携带主错误类型、子类型和错误消息每个 C API 函数都用try/catch捕获异常见 src/core/ffms.cpp 中FFMS_GetFrame等函数的写法调用e.CopyOut(ErrorInfo)把信息填入你传入的FFMS_ErrorInfo函数返回空指针或 -1CopyOut还会返回一个组合码(ErrorType 16) | SubType方便程序化判断见 src/core/utils.cpp。 所以判断成功与否的规则非常统一对象指针返回nullptr/ 整数返回-1时去看ErrorInfo。二、FFMS_ErrorInfo 结构体4 个字段全解析定义在 include/ffms.htypedef struct FFMS_ErrorInfo { int ErrorType; // 主错误类型错误发生在哪里1~11 int SubType; // 子类型错误的成因20~31 int BufferSize; // 消息缓冲区长度你指定 char *Buffer; // 指向缓冲区可读的错误消息 } FFMS_ErrorInfo;字段作用使用要点ErrorType错误发生的模块索引、解码、缩放、音频重采样等等于0FFMS_ERROR_SUCCESS表示无错误SubType错误成因文件读不到、参数非法、解码器错误等与ErrorType组合才能精确定位Buffer/BufferSize可读错误消息的容器使用前必须自己分配如char err[1024]初始化模板官方 API 文档 doc/ffms2-api.md 中给出的标准用法char errmsg[1024]; FFMS_ErrorInfo errinfo; errinfo.Buffer errmsg; errinfo.BufferSize sizeof(errmsg); errinfo.ErrorType FFMS_ERROR_SUCCESS; errinfo.SubType FFMS_ERROR_SUCCESS;三、10 个主错误类型FFMS_Errors 枚举速览主类型错误发生在哪与子类型为什么出错在 include/ffms.h 中定义主类型ErrorType常量编号含义FFMS_ERROR_INDEX1索引文件处理读取/写入 .indexFFMS_ERROR_INDEXING2索引过程本身逐帧扫描源文件FFMS_ERROR_POSTPROCESSING3视频后处理libpostprocFFMS_ERROR_SCALING4图像缩放libswscaleFFMS_ERROR_DECODING5音频/视频解码FFMS_ERROR_SEEKING6定位seek操作FFMS_ERROR_PARSER7文件解析/打开容器FFMS_ERROR_TRACK8轨道track处理FFMS_ERROR_WAVE_WRITER9WAVE64 文件写出FFMS_ERROR_CANCELLED10索引被用户取消FFMS_ERROR_RESAMPLING11音频重采样libswresample子类型SubType常量含义FFMS_ERROR_UNKNOWN未知错误FFMS_ERROR_UNSUPPORTED当前二进制不支持该格式或操作FFMS_ERROR_FILE_READ文件无法读取FFMS_ERROR_FILE_WRITE文件无法写入FFMS_ERROR_NO_FILE文件/目录不存在FFMS_ERROR_VERSION版本不匹配FFMS_ERROR_ALLOCATION_FAILED内存不足FFMS_ERROR_INVALID_ARGUMENT参数非法或不合逻辑FFMS_ERROR_CODEC解码器错误FFMS_ERROR_NOT_AVAILABLE此二进制中未启用该功能如未编译 libpostprocFFMS_ERROR_FILE_MISMATCH索引文件与视频文件不匹配FFMS_ERROR_USER键盘和椅子之间有东西坏了用户操作问题四、10 大错误类型排查清单 遇到问题时按下面清单对号入座#典型现象错误组合排查动作1打开源文件失败PARSERFILE_READ/NO_FILE检查文件路径、权限文件是否损坏、是否还在写入src/core/utils.cpp 的LAVFOpenFile会抛出此错2找不到流信息PARSERFILE_READ容器格式损坏或 FFmpeg 版本缺少该 demuxer3索引过程中出错INDEXING 各子类型看Buffer消息尝试换ErrorHandling策略见下一节4播放/取帧时解码失败DECODINGCODEC解码器问题换SeekMode或重新索引确认文件未被剪辑损坏5定位到某帧失败SEEKING 子类型尝试更宽松的FFMS_SEEK_AGGRESSIVE以牺牲精度换成功率6缩放/转换像素格式失败SCALING 子类型目标格式不受支持换TargetFormats参数7音频重采样失败RESAMPLINGINVALID_ARGUMENT检查采样率、声道布局等重采样参数8索引文件与视频不匹配任意 FILE_MISMATCH视频被重新编码/截断过重新生成 .index9功能不可用任意 NOT_AVAILABLE/UNSUPPORTED该编译版本未启用对应库如 libpostproc换构建版本10参数写错了任意 INVALID_ARGUMENT典型如无效的ErrorHandling模式src/core/indexing.cpp 中SetErrorHandling的校验 小技巧Buffer中的消息是英文短句例如 Cant open xxx、Ambisonics and custom channel orders not supported直接对照消息 上表定位比只看数字快得多。五、进阶索引阶段的 4 种错误处理策略索引indexing是 FFMS2 最容易出错的环节FFMS_DoIndexing2允许你选择出错后的行为include/ffms.h策略行为适用场景FFMS_IEH_ABORT遇到错误立即终止要求完整性宁缺毋滥FFMS_IEH_CLEAR_TRACK清空该轨道的索引结果丢弃坏轨道FFMS_IEH_STOP_TRACK停止该轨道保留其他轨道多轨文件中只关心视频轨FFMS_IEH_IGNORE忽略错误继续索引尽量抢救可解内容配合进度回调FFMS_SetProgressCallback还能用FFMS_CancelIndexing主动取消索引——此时会得到FFMS_ERROR_CANCELLED这是预期行为而非故障⚠️。六、常见问答 FAQQ1每次取帧都要传FFMS_ErrorInfo吗是的。FFMS_GetFrame、FFMS_GetAudio等取数据函数内部会先ClearErrorInfo再填充复用同一个结构体即可。Q2FFMS_ERROR_SUCCESS是多少值为0。任何 API 后先判断ErrorInfo-ErrorType FFMS_ERROR_SUCCESS或返回值非空再使用结果。Q3如何知道错误详情打印Buffer消息ErrorType/SubType上表定位即可覆盖绝大多数场景。Q4Avisynth/VapourSynth 用户会遇到这些错误吗会。插件层src/avisynth/avssources.cpp、src/vapoursynth/vapoursynth4.cpp同样基于这套机制脚本加载失败时的报错信息正来自这里。七、相关文件导航错误结构体与枚举定义include/ffms.hC API 包装与异常捕获src/core/ffms.cppFFMS_Exception与CopyOut实现src/core/utils.cpp、src/core/utils.h索引与错误处理策略src/core/indexing.cpp视频/音频源实现src/core/videosource.cpp、src/core/audiosource.cpp完整 API 文档doc/ffms2-api.mdAvisynth 插件示例脚本etc/FFMS2.avsi掌握FFMS_ErrorInfo的主类型 子类型 消息三层结构再用本文的排查清单对号入座FFMS2 的绝大多数报错你都能在 1 分钟内定位原因 。【免费下载链接】ffms2An FFmpeg based source library and Avisynth/VapourSynth plugin for easy frame accurate access项目地址: https://gitcode.com/gh_mirrors/ff/ffms2创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考