编码与格式 / 系统课时
刷新编码器缓存
刷新编码器缓存
本课解决“所有输入帧都已发送,但输出文件末尾缺帧或无法正常结束”的问题。你将掌握 FFmpeg 发送/接收式编码 API 的刷新流程,在输入结束后取出因帧重排和编码延迟仍滞留的压缩数据。
学习目标
- 说明编码器为什么会在内部缓存输入帧
- 正确区分
EAGAIN与AVERROR_EOF - 在写文件尾和释放资源前完整排空编码器
为什么输入结束后还有数据
支持 B 帧、前瞻分析或较深流水线的编码器,不一定在收到一帧后立刻返回对应数据包。正常编码阶段,应用不断调用 avcodec_send_frame 发送帧,再循环调用 avcodec_receive_packet 取出当前可用数据;输入结束只代表不会再有新帧,并不代表内部缓存已经为空。

刷新动作是向编码器发送一次 NULL 帧,表示输入流结束。成功进入刷新状态后,应继续接收数据包,直到 avcodec_receive_packet 返回 AVERROR_EOF。在此之前收到的每个包都必须像普通编码包一样缩放时间戳、写入封装器并释放引用。
正确实现刷新循环
下面是片段示例,依赖已经打开的编码器上下文和已分配的数据包。回调函数负责处理每个刷新出来的数据包;真实项目中可在回调里执行时间戳缩放和 av_interleaved_write_frame。
#include <errno.h>
#include <inttypes.h>
#include <stdbool.h>
#include <stdio.h>
#include <libavcodec/avcodec.h>
#include <libavutil/error.h>
typedef int (*PacketHandler)(AVPacket *packet, void *opaque);
static int drain_encoder(
AVCodecContext *codec_ctx,
AVPacket *packet,
PacketHandler handler,
void *opaque
) {
bool eof_sent = false;
for (;;) {
if (!eof_sent) {
int ret = avcodec_send_frame(codec_ctx, NULL);
if (ret == 0 || ret == AVERROR_EOF) {
eof_sent = true;
} else if (ret != AVERROR(EAGAIN)) {
return ret;
}
}
int ret = avcodec_receive_packet(codec_ctx, packet);
if (ret == 0) {
// 回调必须在 packet_unref 之前完成写入或复制。
ret = handler(packet, opaque);
av_packet_unref(packet);
if (ret < 0) {
return ret;
}
continue;
}
if (ret == AVERROR_EOF) {
return 0;
}
if (ret == AVERROR(EAGAIN)) {
// 发送与接收同时返回 EAGAIN 违反该 API 的状态约束。
return AVERROR_BUG;
}
return ret;
}
}
static int print_flushed_packet(AVPacket *packet, void *opaque) {
int *count = opaque;
++(*count);
printf("flush packet %d: pts=%" PRId64
", dts=%" PRId64 ", size=%d\n",
*count, packet->pts, packet->dts, packet->size);
return 0;
}
/* 调用位置:所有正常输入帧都已完成 send/receive 之后。 */
static int finish_encoding(
AVCodecContext *codec_ctx,
AVPacket *packet
) {
int flushed_count = 0;
int ret = drain_encoder(
codec_ctx,
packet,
print_flushed_packet,
&flushed_count
);
if (ret < 0) {
return ret;
}
printf("encoder drained, flushed=%d\n", flushed_count);
return 0;
}预期结果
flush packet 1: pts=<PTS>, dts=<DTS>, size=<BYTES>
encoder drained, flushed=<COUNT><COUNT>、<PTS>、<DTS> 和 <BYTES> 取决于编码器、B 帧数量及此前是否已及时接收数据包。存在延迟包时会出现一行或多行 flush packet;无延迟编码器可能直接输出 encoder drained, flushed=0。
EAGAIN 与 EOF 的含义
AVERROR(EAGAIN) 表示当前调用方向暂时无法继续,不代表编码结束。发送帧时遇到它,通常说明还有输出包未接收;接收包时遇到它,通常说明编码器需要更多输入。刷新阶段只有 avcodec_receive_packet 返回 AVERROR_EOF,才能确认内部缓存已经排空。
正常编码阶段推荐遵循“每次发送后尽可能接收”的节奏。这样在最后发送 NULL 时,编码器通常可以立即进入刷新状态,也能减少缓存占用。若此前只发送不接收,最后一次发送 NULL 很可能先返回 EAGAIN。
写文件尾之前如何验收
刷新完成后才能调用 av_write_trailer。若先写文件尾、关闭输出文件或释放编码器,剩余压缩包将永久丢失,常见表现是视频末尾少几帧、最后一个 GOP 不完整,或者播放器显示的时长短于预期。验收时应同时检查以下结果:
- 日志最终出现编码器排空完成标记,而不是以
EAGAIN提前退出。 - 刷新产生的包与普通包走同一套时间戳缩放和写入逻辑。
av_write_trailer位于刷新成功之后,资源释放位于写文件尾之后。- 任何错误分支都执行
av_packet_unref,避免复用数据包时持有旧引用。
常见错误
只调用一次 avcodec_receive_packet 会漏掉多个延迟包;把 EAGAIN 当作结束会提前停止;重复发送普通帧来“顶出缓存”会制造额外画面。正确的结束信号只能是 NULL 帧,正确的停止条件只能是接收端返回 AVERROR_EOF。