av_seek_frame 详解：FFmpeg 播放器里那个“古老但危险”的真家伙

目录一、先说结论二、函数原型三、timestamp 的单位90% 的人第一坑错误理解正确规则四、flagsav_seek_frame 的灵魂也是坑源1️.AVSEEK_FLAG_BACKWARD最重要2️.AVSEEK_FLAG_ANY播放器杀手3️.AVSEEK_FLAG_FRAME几乎没人用4️. AVSEEK_FLAG_BYTE老派硬核五、av_seek_frame 到底“做了什么”六、最小可用但正确的 av_seek_frame 示例七、av_seek_frame vs avformat_seek_file再对比一次八、什么时候你“必须”用 av_seek_frame九、一个经典误解必须点破十、总结av_seek_frame是 FFmpeg 的底层 seek 原语只干一件事把 demuxer 跳到指定时间戳附近不负责画面正常。stream_index≥0时 timestamp用流 time_base填 -1才用微秒视频必带 AVSEEK_FLAG_BACKWARD保证跳到 I 帧前AVSEEK_FLAG_ANY拖进度条必花屏。它成功后不会 flush 解码器、不清旧包必须配套 avcodec_flush_buffers 清队列 丢包到目标 PTS才算真正 seek。MKV/WebM 无 Cues 时容易“跳过头直接 EOF”容错差。一句话它是螺丝刀不是成品工具现代播放器应优先用 avformat_seek_file理解它只为懂原理和修老代码。如果你翻过老代码 / ffplay 旧版本 / 各种 GitHub 播放器 Demo一定见过它av_seek_frame(fmt_ctx, stream_index, timestamp, flags);看起来很简单四个参数一个返回值。但只要你敢往生产环境扔它多半会教你做人MKV 拖到结尾直接播完WebM 花屏 3 秒H264 跳过去画面糊成油画今天这篇把av_seek_frame从“能用”讲到“什么时候不该用”。一、先说结论av_seek_frame是底层 seek 原语​不是给 UI 拖进度条直接用的它只干一件事把 demuxer 的文件位置设到某个时间戳附近​不保证精确、不保证舒服、不负责用户体验一句话懂原理时用它做播放器时包一层再用。二、函数原型int av_seek_frame(AVFormatContext *s, int stream_index, int64_t timestamp, int flags);参数含义sAVFormatContextstream_index参考流 index-1 所有流按 AV_TIME_BASEtimestamp时间戳flagsseek 行为控制AVSEEK_FLAG_BYTE按字节大小进行跳转。AVSEEK_FLAG_FRAME按帧数大小进行跳转。AVSEEK_FLAG_ANY可以跳转到非关键帧的读取位置但是解码会出现马赛克。AVSEEK_FLAG_BACKWARD往 ts 的后面找关键帧默认是往 ts 的前面找关键帧。三、timestamp 的单位90% 的人第一坑错误理解av_seek_frame(fmt, 0, 12.34, ...); // 秒毫秒微秒正确规则stream_indextimestamp 单位 0AVStream::time_base-1AV_TIME_BASE微秒MKV 视频流 {1,1000}→ timestamp 是毫秒正确写法int64_t ts target_sec * 1000; // MKV av_seek_frame(fmt, vidx, ts, AVSEEK_FLAG_BACKWARD);或者通用版int64_t ts av_rescale_q(target_sec * AV_TIME_BASE, AV_TIME_BASE_Q, fmt-streams[vidx]-time_base);四、flagsav_seek_frame 的灵魂也是坑源1️.AVSEEK_FLAG_BACKWARD最重要AVSEEK_FLAG_BACKWARD含义跳到 ≤ timestamp 的最近点视频 seek 必选保证 keyframe 在前会偏早要自己丢包2️.AVSEEK_FLAG_ANY播放器杀手AVSEEK_FLAG_ANY含义不管是不是 keyframe直接跳视频拖进度条绝对禁止​只适合音频裸流分析抽帧截图且你知道自己在干嘛3️.AVSEEK_FLAG_FRAME几乎没人用AVSEEK_FLAG_FRAME以 frame number 为 anchor前提是 demuxer 支持MKV / WebM基本忽略​MP4部分支持实战建议别碰4️.AVSEEK_FLAG_BYTE老派硬核AVSEEK_FLAG_BYTEtimestamp file offset用于 flvcut / ts splice播放器别用五、av_seek_frame 到底“做了什么”它只做了三件事找到对应流的时间索引Cues / stts / index把 demuxer 的 IO 位置调到对应 cluster/packet下次av_read_frame()从那里开始吐包它没做没 flush 解码器没清 B 帧参考没管你线程里还有多少旧 packet没保证画面立刻正常所以你看到的现象现象原因花屏GOP 缺参考卡一下才动BACKWARD 没丢包EOF无 Cues 跳过头六、最小可用但正确的 av_seek_frame 示例int64_t ts av_rescale_q(target_sec * AV_TIME_BASE, AV_TIME_BASE_Q, vst-time_base); av_seek_frame(fmt_ctx, vidx, ts, AVSEEK_FLAG_BACKWARD); avcodec_flush_buffers(vctx); avcodec_flush_buffers(actx); clear_queues(); // 丢到目标 PTS AVPacket pkt; while (av_read_frame(fmt_ctx, pkt) 0) { if (pkt.stream_index vidx pkt.pts ! AV_NOPTS_VALUE pkt.pts ts) break; av_packet_unref(pkt); }这才叫“正确使用 av_seek_frame”七、av_seek_frame vs avformat_seek_file再对比一次维度av_seek_frameavformat_seek_file设计年代老新min/max❌✅容错弱强demuxer 自由度小大播放器友好度⭐⭐⭐⭐⭐⭐⭐ffplay 现在用谁❌✅一句话av_seek_frame 螺丝刀​avformat_seek_file 电动螺丝刀八、什么时候你“必须”用 av_seek_frame说实话只剩这几种FFmpeg 2.x 老代码维护自己写 demux wrapper不用 min/max想精确控制“我不希望 FFmpeg 帮我 clamp”教学 / 理解 demux 原理新播放器项目一律 avformat_seek_file九、一个经典误解必须点破“我用 av_seek_frame 成功返回了为什么画面还是旧的”因为av_seek_frame ≠ 播放器 seek 它只是 demuxer.position somewhere真正的播放器 seek av_seek_frame / avformat_seek_file avcodec_flush_buffers 清队列 丢包到目标时间 重置音视频时钟少一步都不算 seek。十、总结av_seek_frame只负责“跳文件位置”不负责“让你看到画面”它是 FFmpeg 的底层能力不是播放器的成品方案。