libavcodec之AVCodecContext详解

它是 libavcodec中最核心、最重要的数据结构，代表了一个编解码器实例的完整上下文环境。理解它对于掌握 FFmpeg 编解码至关重要。

​核心定位：​​

• ​编解码会话的“大脑”和“控制中心”​​：它包含了配置、运行和控制一个特定编解码器（如 H.264 解码器或 AAC 编码器）所需的所有信息。
• ​编解码器的“实例”​​：每个 AVCodecContext对象对应一个独立的编解码会话。你可以同时拥有多个上下文来处理不同的流或任务。
• ​参数设置的“总开关”​​：几乎所有影响编解码行为（质量、速度、格式、兼容性等）的参数都在这里设置。
• ​状态信息的“记录仪”​​：它记录了编解码过程中的关键状态信息（如时间戳、帧计数等）。

一、关键组成部分详解

AVCodecContext结构体庞大，包含众多字段。我们可以将其主要功能划分为以下几类：

1. 基础身份与类型

• codec_type(enum AVMediaType): ​媒体类型。标识上下文是用于处理视频 (AVMEDIA_TYPE_VIDEO)、音频 (AVMEDIA_TYPE_AUDIO)、字幕 (AVMEDIA_TYPE_SUBTITLE) 还是其他类型的数据。这是最基础的区分。
• codec_id(enum AVCodecID): ​编解码器 ID。指定具体使用哪个编解码算法。例如：
  • 视频：AV_CODEC_ID_H264, AV_CODEC_ID_HEVC, AV_CODEC_ID_VP9, AV_CODEC_ID_AV1, AV_CODEC_ID_MPEG2VIDEO
  • 音频：AV_CODEC_ID_AAC, AV_CODEC_ID_MP3, AV_CODEC_ID_AC3, AV_CODEC_ID_FLAC, AV_CODEC_ID_OPUS
  • 字幕：AV_CODEC_ID_ASS, AV_CODEC_ID_SRT, AV_CODEC_ID_DVD_SUBTITLE
• codec(const struct AVCodec *): ​指向编解码器实现的指针。通常在调用 avcodec_find_decoder()或 avcodec_find_encoder()后，通过 avcodec_alloc_context3(codec)或 avcodec_open2()关联到这个上下文。它提供了编解码器的具体能力（如是否支持某种像素格式）和操作方法。

2. 通用参数 (适用于视频和音频)

• bit_rate(int64_t): ​目标平均码率 (比特率)​。单位是比特/秒 (bps)。编码时用于控制输出文件大小/质量。解码时通常包含在流信息中。
• bit_rate_tolerance(int): ​码率容差。允许实际码率围绕目标码率波动的范围。编码器会尽量将码率控制在这个范围内。
• global_quality(int): ​全局质量因子。某些编码器（如 libx264的 -qp模式）使用此值直接控制质量（值越低质量越好，文件越大）。优先级通常高于 bit_rate。
• compression_level(int): ​压缩级别。一个抽象级别，通常映射到编码器内部预设的速度/质量权衡（如 libx264的 -preset）。值越大通常压缩效率越高（质量好/文件小），但编码速度越慢。
• flags(int): ​全局标志位。通过位掩码 (AV_CODEC_FLAG_*) 设置各种选项。常见的有：
  • AV_CODEC_FLAG_LOW_DELAY: 低延迟模式（常用于实时通信）。
  • AV_CODEC_FLAG_GLOBAL_HEADER: 指示编码器将全局头信息（如 SPS/PPS for H.264）放在容器层（如 extradata），而不是每个关键帧都携带。某些容器格式（如 MP4）要求这样。
  • AV_CODEC_FLAG2_FAST: 尽可能快地编码（可能牺牲质量）。
  • AV_CODEC_FLAG2_CHUNKS: 将帧分割成小块处理（影响内部调度）。
• flags2(int): ​额外的全局标志位。提供更多精细控制。
• time_base(AVRational): ​时间基 (Time Base)​。这是 AVCodecContext中最重要也最容易出错的概念之一。
  • ​定义​：表示时间戳 (pts, dts) 的单位。它是一个分数 num/den，表示每个时间戳刻度代表多少秒。例如，(1, 1000)表示每个时间戳单位是 1 毫秒；(1, 90000)常用于 MPEG 流，表示 1/90000 秒。
  • ​作用​：
    • ​解码器输出帧的 pts​：解码器输出的 AVFrame->pts是基于这个 time_base的。
    • ​编码器输入帧的 pts​：传递给编码器的 AVFrame->pts需要基于这个 time_base。
    • ​编码器输出包的 pts/dts​：编码器输出的 AVPacket->pts/dts也是基于这个 time_base的。
  • ​关键点​：必须正确设置 time_base以确保音视频同步。它需要与流的实际时间基准匹配，并且通常在打开编解码器之前设置好。解码时，通常从容器（AVStream->time_base）中获取并设置到 AVCodecContext。编码时，需要根据目标格式或应用需求设置。
• ticks_per_frame(int): ​每帧的刻度数。定义一帧包含多少个 time_base刻度。对于大多数视频编解码器，这通常是 1（即一帧的持续时间是 time_base）。对于某些音频编解码器或特殊格式可能不同。
• delay(int): ​编解码延迟（内部缓存帧数）​。表示编解码器内部缓冲了多少帧。对于有 B 帧的编码器，这个值通常大于 0。主要用于高级流程控制。
• thread_count(int): ​线程数。控制编解码器使用的线程数量进行并行处理（帧级或片级多线程）。设置为 0 表示自动检测（通常为 CPU 核心数），设置为 1 表示单线程。
• thread_type(int): ​线程类型。指定多线程的实现方式（位掩码 FF_THREAD_*）：
  • FF_THREAD_FRAME: 帧级多线程（不同线程处理不同帧）。
  • FF_THREAD_SLICE: 片级多线程（一个帧被分割成多个片，不同线程处理不同片）。
  • 通常两者可以组合使用 (FF_THREAD_FRAME | FF_THREAD_SLICE)。
• active_thread_type(int): ​实际生效的线程类型​（只读）。由编解码器在打开后设置，表示实际使用的线程模型。
• max_b_frames(int): ​最大连续 B 帧数。编码器在 I 帧或 P 帧之间允许插入的最大 B 帧数量。影响编码延迟和压缩效率。
• gop_size(int): ​GOP (Group of Pictures) 大小。两个关键帧（I 帧）之间的最大间隔帧数。值为 0 表示仅第一帧是关键帧（之后都是 P/B 帧），值小于 0 表示仅使用关键帧（所有帧都是 I 帧）。
• keyint_min(int): ​最小 GOP 大小。强制关键帧的最小间隔。用于确保在场景切换等情况下也能及时插入关键帧。
• sample_aspect_ratio(AVRational): ​像素宽高比 (SAR)​。描述像素本身的宽高比（非图像显示宽高比）。例如，PAL DV 是 (59, 54)。通常与 width/height结合计算显示宽高比 (DAR)。
• pix_fmt(enum AVPixelFormat): ​​(视频) 像素格式。对于解码器，表示它输出的像素格式；对于编码器，表示它接受的输入像素格式。如 AV_PIX_FMT_YUV420P, AV_PIX_FMT_NV12, AV_PIX_FMT_RGBA。​必须正确设置。
• width, height(int): ​​(视频) 图像的宽度和高度​（以像素为单位）。​必须正确设置。
• coded_width, coded_height(int): ​​(视频) 实际存储/编码的宽度和高度。可能比 width/height大，以满足编解码器或硬件的内存对齐要求（如 16 的倍数）。通常由编解码器在打开后设置。
• sample_rate(int): ​​(音频) 采样率。单位是 Hz（每秒采样数）。如 44100, 48000。​必须正确设置。
• sample_fmt(enum AVSampleFormat): ​​(音频) 采样格式。表示音频样本的存储格式（位深度、有符号/无符号、整型/浮点型、打包/平面）。如 AV_SAMPLE_FMT_S16(16 位有符号整型，打包), AV_SAMPLE_FMT_FLTP(32 位浮点型，平面，每个声道单独数组)。​必须正确设置。
  • ​打包 (Packed)​​：所有声道的样本交错存储在一个数组中 (LRLRLR...)。
  • ​平面 (Planar)​​：每个声道的样本存储在单独的数组中 (LLLL..., RRRR...)。现代编解码器通常偏好平面格式。
• channel_layout(uint64_t): ​​(音频) 声道布局。使用位掩码 (AV_CH_*) 描述音频的声道数量和位置。如 AV_CH_LAYOUT_STEREO(立体声，左+右), AV_CH_LAYOUT_5POINT1(5.1 环绕声)。​推荐设置，比 channels更精确。
• channels(int): ​​(音频) 声道数量。如果设置了 channel_layout，这个值通常会自动计算出来。否则需要手动设置。
• frame_size(int): ​​(音频) 每帧采样数。对于某些音频编解码器（如 AAC），要求每次输入给编码器的音频帧必须是固定数量的采样（例如 1024 或 2048 个采样）。解码器输出时也遵循这个大小。​必须了解所用编解码器的要求。
• strict_std_compliance(int): ​标准严格遵循级别​ (FF_COMPLIANCE_*)。控制编解码器对官方标准的严格遵守程度。提高级别可能增强兼容性，但可能牺牲效率或特性。例如，FF_COMPLIANCE_STRICT会禁用非标准特性。
• profile(int): ​编解码器档次 (Profile)​。指定编解码器支持的功能子集（如 H.264 的 Baseline, Main, High）。影响兼容性和复杂度。
• level(int): ​编解码器级别 (Level)​。指定编解码器支持的最大参数限制（如分辨率、帧率、码率）。影响兼容性和性能需求。
• extradata(uint8_t *), extradata_size(int): ​附加数据。存储编解码器初始化所需的额外信息。
  • ​解码​：通常从容器中读取（如 H.264 的 SPS/PPS，AAC 的 AudioSpecificConfig），在打开解码器前设置好。解码器依赖这些信息才能正确解码。
  • ​编码​：编码器在打开后，可能会生成 extradata（如全局头信息），需要写入容器或传递给解码端。
• hw_device_ctx(AVBufferRef *): ​硬件设备上下文引用。这是启用硬件加速编解码的关键。它指向一个代表特定硬件设备（如 NVIDIA GPU, Intel QSV）的 AVHWDeviceContext。在打开编解码器之前设置。
• hw_frames_ctx(AVBufferRef *): ​硬件帧池上下文引用。当使用硬件编解码时，它指向一个 AVHWFramesContext，描述了编解码器输入（编码）或输出（解码）帧的格式、大小和内存类型（如 CUDA 设备内存、VAAPI 表面）。通常在打开编解码器之后由用户或编解码器自身设置。

3. 私有数据与选项

• priv_data(void *): ​指向编解码器私有上下文数据的指针。每个编解码器实现（如 libx264, libfdk_aac）通常都有自己的私有数据结构（如 x264_t, AACContext），用于存储该编解码器特有的配置和状态。用户不应直接操作这个指针。
• ​设置私有选项​：由于 priv_data是编解码器特定的，FFmpeg 提供了统一的 API 来设置和获取私有选项：
  • av_opt_set(codec_ctx->priv_data, "option_name", value, 0)
  • av_opt_get(codec_ctx->priv_data, "option_name", 0, &out_val)
  • 这些选项的名称和值取决于具体的编解码器实现（例如 libx264的 preset, tune, crf等）。查阅编解码器文档或使用 ffmpeg -h encoder=libx264查看支持的选项。

4. 运行时信息 (主要只读)

• frame_number(int): ​输入帧计数器。记录自打开编解码器以来，发送给编码器的输入帧数（avcodec_send_frame()）或从解码器输出的帧数（avcodec_receive_frame()）。
• pts_correction_num_faulty_pts/dts(int64_t): ​时间戳错误校正统计。记录检测到的异常时间戳数量。
• pts_correction_last_pts/dts(int64_t): ​上次时间戳。用于内部时间戳连续性检查和校正。
• properties(int): ​编解码器属性标志​ (AV_CODEC_PROP_*)。只读，表示编解码器的特性，如 AV_CODEC_PROP_LOSSLESS(无损), AV_CODEC_PROP_INTRA_ONLY(仅 I 帧), AV_CODEC_PROP_REORDER(输出顺序不等于显示顺序，即有 B 帧)。

二、生命周期与管理

1. ​分配​：
   • AVCodecContext *avcodec_alloc_context3(const AVCodec *codec);
   • 分配一个 AVCodecContext并将其与一个编解码器关联（codec可以为 NULL，稍后设置）。
   • 分配后，许多字段被设置为合理的默认值，但关键参数​（如 width, height, pix_fmt, sample_rate, sample_fmt, channel_layout, time_base）​通常需要显式设置。
2. ​配置​：
   • 设置各种参数（如上文所述）。
   • 对于解码器，通常需要设置 extradata（如果容器提供了）。
   • 对于硬件加速，需要设置 hw_device_ctx（有时还需要 hw_frames_ctx）。
   • 使用 av_opt_set()配置私有选项。
3. ​打开​：
   • int avcodec_open2(AVCodecContext *avctx, const AVCodec *codec, AVDictionary **options);
   • 使用配置好的上下文打开编解码器。codec参数如果为 NULL，则使用 avctx->codec。
   • options参数是一个指向 AVDictionary的指针，可以传递额外的键值对选项（这些选项最终会通过 av_opt_set()设置到 priv_data上）。
   • 打开操作会检查参数有效性，初始化编解码器内部状态（包括 priv_data），并可能根据编解码器要求调整某些参数（如 coded_width/coded_height, frame_size）。​打开后，某些参数就不能再修改了。
4. ​使用​：
   • 在编解码流程中（avcodec_send_packet()/avcodec_receive_frame()或 avcodec_send_frame()/avcodec_receive_packet()）使用该上下文。
   • 运行时信息字段会被更新。
5. ​刷新与关闭​：
   • 在流结束时，向编解码器发送 NULL以刷新内部缓冲区。
   • avcodec_close(AVCodecContext *avctx);：关闭编解码器，释放内部资源（包括 priv_data）。上下文本身仍然存在，可以重新打开。
   • avcodec_free_context(AVCodecContext **avctx);：释放上下文本身及其所有内容（包括调用 avcodec_close）。这是释放上下文的推荐方式，因为它处理了所有内部引用计数（如 hw_device_ctx, hw_frames_ctx）。

三、关键点与最佳实践

1. ​区分解码和编码上下文​：虽然结构相同，但配置重点不同。解码上下文通常从容器 (AVFormatContext, AVStream) 获取参数；编码上下文需要用户根据目标格式和应用需求主动设置参数。
2. ​time_base是同步核心​：务必理解其含义并正确设置。解码时通常继承 AVStream->time_base；编码时需要合理选择（如 1/framerate或 1/sample_rate）。
3. ​像素/采样格式必须匹配​：确保 pix_fmt/sample_fmt与输入（编码）或输出（解码）数据的实际格式一致。使用 avcodec_find_best_pix_fmt_of_list或查询编解码器支持的格式列表 (avcodec->pix_fmts/sample_fmts)。
4. ​硬件加速配置链​：理解 hw_device_ctx-> hw_frames_ctx的传递关系。hw_device_ctx必须在 avcodec_open2​之前设置。hw_frames_ctx通常在打开后设置或由编解码器自动创建。
5. ​利用私有选项​：使用 av_opt_set()和 av_opt_get()来访问编解码器特有的强大功能（如 x264 的 crf, preset, tune）。
6. ​线程配置​：合理设置 thread_count和 thread_type以充分利用多核 CPU。
7. ​检查返回值​：所有 FFmpeg API 调用都可能返回错误，务必检查。
8. ​内存管理​：使用 avcodec_free_context()释放上下文。使用 av_frame_unref()/av_packet_unref()管理帧和包。
9. ​查阅文档和源码​：AVCodecContext的字段和编解码器的私有选项可能随 FFmpeg 版本更新而变化。官方文档 (libavcodec/avcodec.h) 和编解码器源码 (libavcodec/*.c) 是最权威的参考。
10. ​过时 API 警告​：避免使用 avcodec_decode_video2/avcodec_decode_audio4/avcodec_encode_video2/avcodec_encode_audio2等旧 API。它们已被基于 send/receive的新 API 取代。

​总结：​​

AVCodecContext是驾驭 libavcodec的舵盘。它汇集了配置、控制和监控一个编解码会话所需的一切。深入理解其核心字段（特别是类型、格式、时间基准、码率控制、线程、硬件加速和私有选项）以及其生命周期管理，是高效、正确地进行音视频编解码开发的基础。务必结合实践，仔细配置参数，并充分利用 FFmpeg 提供的工具和文档。